summaryrefslogtreecommitdiff
path: root/doc/parser_comb.html
diff options
context:
space:
mode:
authorJed Barber <jjbarber@y7mail.com>2021-01-19 02:25:44 +1100
committerJed Barber <jjbarber@y7mail.com>2021-01-19 02:25:44 +1100
commitda389927ddf9240bbba10b819eb782e80a5d6bf7 (patch)
tree88b167b892de8c419151ca9a02c16f8d4ed96bec /doc/parser_comb.html
parent901c7e61278f16dc5c08cbebf74c2a816cd4b4b6 (diff)
Basic HTML documentation added
Diffstat (limited to 'doc/parser_comb.html')
-rw-r--r--doc/parser_comb.html589
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>
+