diff options
| author | Jed Barber <jjbarber@y7mail.com> | 2021-01-19 02:25:44 +1100 |
|---|---|---|
| committer | Jed Barber <jjbarber@y7mail.com> | 2021-01-19 02:25:44 +1100 |
| commit | da389927ddf9240bbba10b819eb782e80a5d6bf7 (patch) | |
| tree | 88b167b892de8c419151ca9a02c16f8d4ed96bec /doc/parser_comb.html | |
| parent | 901c7e61278f16dc5c08cbebf74c2a816cd4b4b6 (diff) | |
Basic HTML documentation added
Diffstat (limited to 'doc/parser_comb.html')
| -rw-r--r-- | doc/parser_comb.html | 589 |
1 files changed, 589 insertions, 0 deletions
diff --git a/doc/parser_comb.html b/doc/parser_comb.html new file mode 100644 index 0000000..c6fd63c --- /dev/null +++ b/doc/parser_comb.html @@ -0,0 +1,589 @@ + +<!DOCTYPE html> + +<html lang="en"> + <head> + <meta charset="utf-8"> + <title>Parser Components - Packrat Docs</title> + <link href="default.css" rel="stylesheet"> + </head> + + <body> + + + <h2>Parser Components</h2> + + <a href="index.html">Return to Contents</a> + + + <p>Several of the combinators were inspired from Haskell's Parsec library.</p> + + <table> + <tr> +<td><pre> +generic + with function Root + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +package Parse_Parts is + + procedure Parse + (Input : in Traits.Element_Array; + Result : out Graphs.Parse_Graph); + + procedure Reset; + +end Parse_Parts; +</pre></td> +<td>The parser that allows for piecewise parsing. It will continue to accept more input until an empty +input array is supplied, at which point it is assumed that the end of input has been reached. No result +will be given until end of input.<br> +<br> +The <em>Reset</em> procedure returns the parser to a clean state as if it had just been declared.</td> + </tr> + <tr> +<td><pre> +generic + with function Root + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +package Parse_Once is + + function Parse + (Input : in Traits.Element_Array) + return Graphs.Parse_Graph; + + procedure Reset; + +end Parse_Once; +</pre></td> +<td>Parser that only accepts input all in one go, returning the result after one call of the <em>Parse</em> +function.<br> +<br> +The <em>Reset</em> procedure returns the parser to a clean state as if it had just been declared.</td> + </tr> + <tr> +<td><pre> +generic + with function Root + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +package Parse_With is + + function Parse + (Input : in With_Input) + return Graphs.Parse_Graph; + + procedure Reset; + +end Parse_With; +</pre></td> +<td>Piecewise parsing, but uses the supplied input function to retrieve further pieces of input as +needed, until the function return an empty array upon which end of input is assumed.<br> +<br> +The <em>Reset</em> procedure returns the parser to a clean state as if it had just been declared.</td> + </tr> + <tr> +<td><pre> +generic + Label : in Traits.Label_Enum; + with function Combo + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +function Stamp + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Runs the supplied <em>Combo</em> combinator. If the result is successful, generates a node in the +parse graph with label of <em>Label</em>. Any nodes generated by <em>Combo</em> are made into children of +the new node. Any non-node input parsed by <em>Combo</em> is made into the value of the new node.<br> +<br> +If the <em>Combo</em> combinator is not successful, stores the error result in case a <em>Parser_Error</em> +needs to be raised.</td> + </tr> + <tr> +<td><pre> +generic + Label : in Traits.Label_Enum; + with function Combo + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +function Discard + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Operates similar to <em>Stamp</em> but discards any successful result of <em>Combo</em> instead of +adding it to the parse graph. Any error result is still stored in case of a <em>Parser_Error</em> needing +to be raised.</td> + </tr> + <tr> +<td><pre> +generic + with function Combo + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +function Ignore + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Operates similar to <em>Discard</em> but no error result is stored. Any result of <em>Combo</em> is +ultimately discarded regardless of success or failure.</td> + </tr> + <tr> +<td><pre> +generic +package Redirect is + + procedure Set + (Target : in Combinator); + + function Call + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + +end Redirect; +</pre></td> +<td>Use this whenever you need to refer to a combinator that you haven't declared yet in a combinator +instantiation. This generally happens when there is some form of recursion in the grammar. Instantiate +<em>Redirect</em>, use <em>Call</em> in the instantiation of other combinators, then set the actual +target of the redirect with <em>Set</em> before you call the parser. If the redirect is not set when +the parser is called then a <em>Constraint_Error</em> is raised.</td> + </tr> + <tr> +<td><pre> +generic + Params : in Combinator_Array; +function Sequence + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Attempts to parse all the combinators in <em>Params</em> one after the other. Only succeeds if +all combinators succeed.</td> + </tr> + <tr> +<td><pre> +generic + with function Part_One + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + with function Part_Two + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +function Sequence_2 + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses <em>Part_One</em>, then <em>Part_Two</em> directly after. Only succeeds if both succeed. This +combinator exists because <em>Sequence</em> can have instantiation issues due to access level restrictions.</td> + </tr> + <tr> +<td><pre> +generic + Params : in Combinator_Array; +function Choice + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses all the combinators in <em>Params</em> all starting from the current starting point, then combines +all the results. In this way all possible valid parse choices are taken.</td> + </tr> + <tr> +<td><pre> +generic + with function Choice_One + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + with function Choice_Two + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +function Choice_2 + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses <em>Choice_One</em> and <em>Choice_Two</em> both starting at the current starting point, then +combines the results. In other words it takes both possible parse choices. Like <em>Sequence_2</em>, this +exists because the <em>Choice</em> can have instantiation issues due to access level restrictions.</td> + </tr> + <tr> +<td><pre> +generic + with function Param + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + Number : in Positive; +function Count + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses the supplied <em>Param</em> combinator <em>Number</em> of times sequentially.</td> + </tr> + <tr> +<td><pre> +generic + with function Param + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + Minimum : in Natural := 0; +function Many + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses the supplied <em>Param</em> combinator as many times as it can, one after the other, until it +fails. If at least <em>Minimum</em> number of parses are successful then the whole result is successful.<br> +<br> +The result includes every possible valid number of times that <em>Param</em> could be parsed. For example, +if <em>Param</em> could be parsed 0-6 times and <em>Minimum</em> is 3, then the result will include cases +where <em>Param</em> was parsed 3, 4, 5, 6 times.</td> + </tr> + <tr> +<td><pre> +generic + with function Param + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +function Followed_By + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Checks whether <em>Param</em> succeeds at the given point in the input and succeeds if <em>Param</em> +succeeds. Does not actually progress the input, regardless of what <em>Param</em> does.</td> + </tr> + <tr> +<td><pre> +generic + with function Param + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +function Not_Followed_By + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Checks whether <em>Param</em> succeeds at the given point in the input and succeeds if <em>Param</em> +fails. Does not actually progress the input, regardless of what <em>Param</em> does.</td> + </tr> + <tr> +<td><pre> +generic + with function Param + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + with function Test + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + Minimum : in Natural := 0; +function Many_Until + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses the supplied <em>Param</em> combinator as many times as it can until a point is reached when +<em>Test</em> would succeed. The overall result succeeds if <em>Param</em> was successfully parsed at least +<em>Minimum</em> number of times.</td> + </tr> + <tr> +<td><pre> +generic + with function Param + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +function Optional + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Combines the result of parsing <em>Param</em> with the result of not parsing it.</td> + </tr> + <tr> +<td><pre> +generic + with function Item + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + with function Separator + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + Minimum : in Natural := 0; +function Separate_By + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses as many of <em>Item</em> as it can, separated by <em>Separator</em> and requiring a minimum of +<em>Minimum</em> items parsed. The separators are ignored in the final result. Combines different length +results in the same way that <em>Many</em> does.</td> + </tr> + <tr> +<td><pre> +generic + with function Item + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + with function Separator + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + with function Ender + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + Minimum : in Natural := 0; +function Separate_End_By + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Works the same way as <em>Separate_By</em> in sequence with <em>Ender</em>. The ender is ignored in +the final result.</td> + </tr> + <tr> +<td><pre> +generic + with function Starter + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + with function Item + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; + with function Ender + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +function Between + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses <em>Starter</em> then <em>Item</em> then <em>Ender</em> in sequence. The results of +<em>Starter</em> and <em>Ender</em> are discarded.</td> + </tr> + <tr> +<td><pre> +generic + with function Test + (Item : in Traits.Element_Type) + return Boolean; +function Satisfy + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses the next item of input if the supplied <em>Test</em> function succeeds on it.</td> + </tr> + <tr> +<td><pre> +generic + with function Test + (Item : in Traits.Element_Type) + return Boolean; + with function Change + (From : in Traits.Element_Type) + return Traits.Element_Type; +function Satisfy_With + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses the next item of input if the supplied <em>Test</em> function succeeds on it after it has +been transformed by the <em>Change</em> function. The original unchanged item is what is parsed.</td> + </tr> + <tr> +<td><pre> +generic + Item : in Traits.Element_Type; +function Match + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses the next item of input if it matches <em>Item</em>.</td> + </tr> + <tr> +<td><pre> +generic + Item : in Traits.Element_Type; + with function Change + (From : in Traits.Element_Type) + return Traits.Element_Type; +function Match_With + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses the next item of input if it matches <em>Item</em> after the input item has been transformed +by the <em>Change</em> function. The original unchanged item is what is parsed.</td> + </tr> + <tr> +<td><pre> +generic + Items : in Traits.Element_Array; +function Multimatch + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses the next <em>Items'Length</em> items of input if they match <em>Items</em>.</td> + </tr> + <tr> +<td><pre> +generic + Number : in Positive := 1; +function Take + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses the next <em>Number</em> items of input.</td> + </tr> + <tr> +<td><pre> +generic + with function Test + (Item : in Traits.Element_Type) + return Boolean; +function Take_While + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses items of input as long as the supplied <em>Test</em> function succeeds on them.</td> + </tr> + <tr> +<td><pre> +generic + with function Test + (Item : in Traits.Element_Type) + return Boolean; +function Take_Until + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses items of input until the supplied <em>Test</em> function succeeds on the next item of input.</td> + </tr> + <tr> +<td><pre> +function Empty + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Does not parse any input but returns an empty, yet successful, result.</td> + </tr> + <tr> +<td><pre> +generic + with function Combo + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +function Not_Empty + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>Parses the supplied <em>Combo</em> combinator as normal but excludes any empty results.</td> + </tr> + <tr> +<td><pre> +function End_Of_Input + (Input : in Traits.Element_Array; + Context : in out Parser_Context; + Start : in Positive) + return Combinator_Result; +</pre></td> +<td>A combinator that only succeeds if the end of input has been reached and there is nothing more +to parse, at which point it will return an empty yet successful result.</td> + </tr> + </table> + + + </body> +</html> + |