From 91c46438fed4c472407edaafe11442e4697317a4 Mon Sep 17 00:00:00 2001
From: Michael Wallner <mike@php.net>
Date: Mon, 16 Feb 2015 08:15:01 +0100
Subject: [PATCH] header parser docs

---
 http/Header/Parser.md          | 36 ++++++++++++++++
 http/Header/Parser/getState.md | 16 +++++++
 http/Header/Parser/parse.md    | 76 ++++++++++++++++++++++++++++++++++
 http/Message/Parser.md         |  3 ++
 4 files changed, 131 insertions(+)
 create mode 100644 http/Header/Parser.md
 create mode 100644 http/Header/Parser/getState.md
 create mode 100644 http/Header/Parser/parse.md

diff --git a/http/Header/Parser.md b/http/Header/Parser.md
new file mode 100644
index 0000000..76f4eaf
--- /dev/null
+++ b/http/Header/Parser.md
@@ -0,0 +1,36 @@
+# class http\Header\Parser
+
+The parser which is underlying http\Header and http\Message.
+
+## Changelog:
+
+| Version | Change 
+|---------|--------
+| 2.3.0   | Added http\Header\Parser API
+
+## Constants:
+
+### Parser flags:
+
+* CLEANUP  
+  Finish up parser at end of (incomplete) input.
+
+### Parser states:
+
+* STATE_FAILURE  
+  Parse failure.
+* STATE_START  
+  Expecting HTTP info (request/response line) or headers.
+* STATE_KEY  
+  Expecting a key or already parsing a key.
+* STATE_VALUE  
+  Expecting a value or already parsing the value.
+* STATE_VALUE_EX  
+  At EOL of an header, checking whether a folded header line follows.
+* STATE_HEADER_DONE  
+  A header was completed.
+* STATE_DONE  
+  Finished parsing the headers.
+
+> ***NOTE:***  
+> Most of this states won't be returned to the user, because the parser immediately jumps to the next expected state.
diff --git a/http/Header/Parser/getState.md b/http/Header/Parser/getState.md
new file mode 100644
index 0000000..14a29bd
--- /dev/null
+++ b/http/Header/Parser/getState.md
@@ -0,0 +1,16 @@
+# int http\Header\Parser::getState()
+
+Retrieve the current state of the parser.
+See http\Header\Parser::STATE_* constants.
+
+## Params:
+
+None.
+
+## Returns:
+
+* int, http\Header\Parser::STATE_* constant.
+
+## Throws:
+
+* http\Exception\InvalidArgumentException
diff --git a/http/Header/Parser/parse.md b/http/Header/Parser/parse.md
new file mode 100644
index 0000000..444a1b3
--- /dev/null
+++ b/http/Header/Parser/parse.md
@@ -0,0 +1,76 @@
+# int http\Header\Parser::parse(string $data, int $flags, array &$message = NULL)
+
+Parse a string.
+
+## Params:
+
+* string $data  
+  The (part of the) header to parse.
+* int $flags  
+  Any combination of [parser flags](http/Header/Parser#Parser.flags:).
+* array &$header = NULL 
+  Successfully parsed headers.
+
+## Returns:
+
+* int, http\Header\Parser::STATE_* constant.
+
+## Throws:
+
+* http\Exception\InvalidArgumentException
+
+## Example:
+
+	<?php
+	
+	$headers = [
+		"One: ","header\n",
+		"Two: header\n\tlines\n",
+		"Three",": header\n lines\n here\n",
+		"More: than one header\n",
+		"More: ", "than: ", "you: ", "expect\n",
+		"\n",
+	];
+
+	$states = [-1=>"FAILURE",0=>"START","KEY","VALUE","VALUE_EX","HEADER_DONE","DONE"];
+	$parser = new http\Header\Parser;
+	do {
+		$state = $parser->parse($part = array_shift($headers), 
+			$headers ? 0 : http\Header\Parser::CLEANUP, 
+			$result);
+		printf("%2\$-32s | %1\$s\n", $states[$state], addcslashes($part, "\r\n\t\0"));
+	} while ($headers && $state !== http\Header\Parser::STATE_FAILURE);
+
+	var_dump($result);
+
+	?>
+
+Yields:
+
+	Test
+	One:                             | VALUE
+	header\n                         | VALUE_EX
+	Two: header\n\tlines\n           | VALUE_EX
+	Three                            | KEY
+	: header\n lines\n here\n        | VALUE_EX
+	More: than one header\n          | VALUE_EX
+	More:                            | VALUE
+	than:                            | VALUE
+	you:                             | VALUE
+	expect\n                         | VALUE_EX
+	\n                               | DONE
+	array(4) {
+	  ["One"]=>
+	  string(6) "header"
+	  ["Two"]=>
+	  string(12) "header lines"
+	  ["Three"]=>
+	  string(17) "header lines here"
+	  ["More"]=>
+	  array(2) {
+		[0]=>
+		string(15) "than one header"
+		[1]=>
+		string(17) "than: you: expect"
+	  }
+	}
diff --git a/http/Message/Parser.md b/http/Message/Parser.md
index 78398fd..bd70220 100644
--- a/http/Message/Parser.md
+++ b/http/Message/Parser.md
@@ -43,3 +43,6 @@ The parser which is underlying http\Message.
   Finished parsing the body.
 * STATE_DONE  
   Finished parsing the message.
+
+> ***NOTE:***  
+> Most of this states won't be returned to the user, because the parser immediately jumps to the next expected state.
-- 
2.30.2