From da389927ddf9240bbba10b819eb782e80a5d6bf7 Mon Sep 17 00:00:00 2001 From: Jed Barber Date: Tue, 19 Jan 2021 02:25:44 +1100 Subject: Basic HTML documentation added --- doc/parser_comb.html | 589 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 589 insertions(+) create mode 100644 doc/parser_comb.html (limited to 'doc/parser_comb.html') 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 @@ + + + + + + + Parser Components - Packrat Docs + + + + + + +

Parser Components

+ + Return to Contents + + +

Several of the combinators were inspired from Haskell's Parsec library.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 
+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;
+
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.
+
+The Reset procedure returns the parser to a clean state as if it had just been declared.
+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;
+
Parser that only accepts input all in one go, returning the result after one call of the Parse +function.
+
+The Reset procedure returns the parser to a clean state as if it had just been declared.
+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;
+
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.
+
+The Reset procedure returns the parser to a clean state as if it had just been declared.
+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;
+
Runs the supplied Combo combinator. If the result is successful, generates a node in the +parse graph with label of Label. Any nodes generated by Combo are made into children of +the new node. Any non-node input parsed by Combo is made into the value of the new node.
+
+If the Combo combinator is not successful, stores the error result in case a Parser_Error +needs to be raised.
+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;
+
Operates similar to Stamp but discards any successful result of Combo instead of +adding it to the parse graph. Any error result is still stored in case of a Parser_Error needing +to be raised.
+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;
+
Operates similar to Discard but no error result is stored. Any result of Combo is +ultimately discarded regardless of success or failure.
+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;
+
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 +Redirect, use Call in the instantiation of other combinators, then set the actual +target of the redirect with Set before you call the parser. If the redirect is not set when +the parser is called then a Constraint_Error is raised.
+generic
+    Params : in Combinator_Array;
+function Sequence
+       (Input   : in     Traits.Element_Array;
+        Context : in out Parser_Context;
+        Start   : in     Positive)
+    return Combinator_Result;
+
Attempts to parse all the combinators in Params one after the other. Only succeeds if +all combinators succeed.
+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;
+
Parses Part_One, then Part_Two directly after. Only succeeds if both succeed. This +combinator exists because Sequence can have instantiation issues due to access level restrictions.
+generic
+    Params : in Combinator_Array;
+function Choice
+       (Input   : in     Traits.Element_Array;
+        Context : in out Parser_Context;
+        Start   : in     Positive)
+    return Combinator_Result;
+
Parses all the combinators in Params all starting from the current starting point, then combines +all the results. In this way all possible valid parse choices are taken.
+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;
+
Parses Choice_One and Choice_Two both starting at the current starting point, then +combines the results. In other words it takes both possible parse choices. Like Sequence_2, this +exists because the Choice can have instantiation issues due to access level restrictions.
+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;
+
Parses the supplied Param combinator Number of times sequentially.
+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;
+
Parses the supplied Param combinator as many times as it can, one after the other, until it +fails. If at least Minimum number of parses are successful then the whole result is successful.
+
+The result includes every possible valid number of times that Param could be parsed. For example, +if Param could be parsed 0-6 times and Minimum is 3, then the result will include cases +where Param was parsed 3, 4, 5, 6 times.
+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;
+
Checks whether Param succeeds at the given point in the input and succeeds if Param +succeeds. Does not actually progress the input, regardless of what Param does.
+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;
+
Checks whether Param succeeds at the given point in the input and succeeds if Param +fails. Does not actually progress the input, regardless of what Param does.
+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;
+
Parses the supplied Param combinator as many times as it can until a point is reached when +Test would succeed. The overall result succeeds if Param was successfully parsed at least +Minimum number of times.
+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;
+
Combines the result of parsing Param with the result of not parsing it.
+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;
+
Parses as many of Item as it can, separated by Separator and requiring a minimum of +Minimum items parsed. The separators are ignored in the final result. Combines different length +results in the same way that Many does.
+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;
+
Works the same way as Separate_By in sequence with Ender. The ender is ignored in +the final result.
+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;
+
Parses Starter then Item then Ender in sequence. The results of +Starter and Ender are discarded.
+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;
+
Parses the next item of input if the supplied Test function succeeds on it.
+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;
+
Parses the next item of input if the supplied Test function succeeds on it after it has +been transformed by the Change function. The original unchanged item is what is parsed.
+generic
+    Item : in Traits.Element_Type;
+function Match
+       (Input   : in     Traits.Element_Array;
+        Context : in out Parser_Context;
+        Start   : in     Positive)
+    return Combinator_Result;
+
Parses the next item of input if it matches Item.
+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;
+
Parses the next item of input if it matches Item after the input item has been transformed +by the Change function. The original unchanged item is what is parsed.
+generic
+    Items : in Traits.Element_Array;
+function Multimatch
+       (Input   : in     Traits.Element_Array;
+        Context : in out Parser_Context;
+        Start   : in     Positive)
+    return Combinator_Result;
+
Parses the next Items'Length items of input if they match Items.
+generic
+    Number : in Positive := 1;
+function Take
+       (Input   : in     Traits.Element_Array;
+        Context : in out Parser_Context;
+        Start   : in     Positive)
+    return Combinator_Result;
+
Parses the next Number items of input.
+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;
+
Parses items of input as long as the supplied Test function succeeds on them.
+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;
+
Parses items of input until the supplied Test function succeeds on the next item of input.
+function Empty
+       (Input   : in     Traits.Element_Array;
+        Context : in out Parser_Context;
+        Start   : in     Positive)
+    return Combinator_Result;
+
Does not parse any input but returns an empty, yet successful, result.
+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;
+
Parses the supplied Combo combinator as normal but excludes any empty results.
+function End_Of_Input
+       (Input   : in     Traits.Element_Array;
+        Context : in out Parser_Context;
+        Start   : in     Positive)
+    return Combinator_Result;
+
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.
+ + + + + -- cgit