header parser docs

diff --git a/http/Header/Parser.md b/http/Header/Parser.md
new file mode 100644 (file)
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 (file)
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 (file)
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 78398fdbc0bc7c8ca64c3a076b4baaa6608301fc..bd7022054f6be21b30c870de99ae38376c438197 100644 (file)
--- 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.