<!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>