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/blank_template.html | 21 ++ doc/credits.html | 30 +++ doc/default.css | 29 +++ doc/depends.html | 29 +++ doc/errors.html | 33 +++ doc/example_overview.html | 40 ++++ doc/features.html | 46 ++++ doc/index.html | 48 ++++ doc/lexer_comb.html | 347 +++++++++++++++++++++++++++ doc/license.html | 53 +++++ doc/limits.html | 49 ++++ doc/parse_graph_op.html | 424 +++++++++++++++++++++++++++++++++ doc/parser_comb.html | 589 ++++++++++++++++++++++++++++++++++++++++++++++ doc/quickstart.html | 65 +++++ doc/src_overview.html | 74 ++++++ doc/test_overview.html | 51 ++++ doc/util_func.html | 148 ++++++++++++ 17 files changed, 2076 insertions(+) create mode 100644 doc/blank_template.html create mode 100644 doc/credits.html create mode 100644 doc/default.css create mode 100644 doc/depends.html create mode 100644 doc/errors.html create mode 100644 doc/example_overview.html create mode 100644 doc/features.html create mode 100644 doc/index.html create mode 100644 doc/lexer_comb.html create mode 100644 doc/license.html create mode 100644 doc/limits.html create mode 100644 doc/parse_graph_op.html create mode 100644 doc/parser_comb.html create mode 100644 doc/quickstart.html create mode 100644 doc/src_overview.html create mode 100644 doc/test_overview.html create mode 100644 doc/util_func.html (limited to 'doc') diff --git a/doc/blank_template.html b/doc/blank_template.html new file mode 100644 index 0000000..0f1fcee --- /dev/null +++ b/doc/blank_template.html @@ -0,0 +1,21 @@ + + + + + + + REPLACE THIS - Packrat Docs + + + + + + +

REPLACE THIS

+ + Return to Contents + + + + + diff --git a/doc/credits.html b/doc/credits.html new file mode 100644 index 0000000..74cb19b --- /dev/null +++ b/doc/credits.html @@ -0,0 +1,30 @@ + + + + + + + Credits and Further Reading - Packrat Docs + + + + + + +

Credits and Further Reading

+ + Return to Contents + + +

The Packrat parser combinator library was programmed by + Jedidiah Barber.

+ +

Most of the ideas for the library were obtained from + Parser + Combinators for Ambiguous Left-Recursive Grammars (Frost, Hafiz, Callaghan, 2008) + with the notable exception of handling indirect left recursion.

+ + + + + diff --git a/doc/default.css b/doc/default.css new file mode 100644 index 0000000..d7fe1b6 --- /dev/null +++ b/doc/default.css @@ -0,0 +1,29 @@ + +body { + width: 90%; + margin-left: 2em; + margin-right: 2em; +} + + +table { + margin-top: 2em; + margin-bottom: 2em; + border: 1px solid black; +} + + +th { + padding-top: 0.5em; + padding-bottom: 0.5em; + border: 1px solid black; +} + + +td { + width: 50%; + padding: 0.5em 0.5em 0.5em 0.5em; + border: 1px solid black; +} + + diff --git a/doc/depends.html b/doc/depends.html new file mode 100644 index 0000000..91ee096 --- /dev/null +++ b/doc/depends.html @@ -0,0 +1,29 @@ + + + + + + + Dependencies - Packrat Docs + + + + + + +

Dependencies

+ + Return to Contents + + +

+ Aside from Ada standard libraries, Packrat relies on the following other packages:
+
+ directed-graph
+ basic-unit-test (Only if using unit tests.) +

+ + + + + diff --git a/doc/errors.html b/doc/errors.html new file mode 100644 index 0000000..e0f12c0 --- /dev/null +++ b/doc/errors.html @@ -0,0 +1,33 @@ + + + + + + + Handling Errors - Packrat Docs + + + + + + +

Handling Errors

+ + Return to Contents + + +

Whenever a Lexer_Error or Parser_Error is raised it is always accompanied + with a string that contains encoded information about where in the input the error occurred.

+ +

Such strings should not be examined directly, but if the Decode function from + Packrat.Errors is used then an array of symbol/position pairs is obtained. Each of those + pairs describes a point in the input where, if the given symbol was successfully found, a more + successful parse would have resulted.

+ +

Unfortunately at this time no resumption of lexing or parsing can be done once an error has + occurred.

+ + + + + diff --git a/doc/example_overview.html b/doc/example_overview.html new file mode 100644 index 0000000..88d15a3 --- /dev/null +++ b/doc/example_overview.html @@ -0,0 +1,40 @@ + + + + + + + /example Overview - Packrat Docs + + + + + + +

/example Overview

+ + Return to Contents + + + + + + + + + + + + + + + +
calc.adbImplements a basic expression calculator using lexer and parser combinators. + Can handle + - * / ^ () operators. Run with the --help switch for more info.
sentence.adbImplements the sentence grammar used as an example in the reference paper on pages 2-3.
ssss.adbImplements the highly ambiguous s grammar used in the reference paper on pages 5 and 12-13. + Length of input can be adjusted by command line argument and is therefore good for experiments on + complexity of the library. Also responds to the --help switch.
+ + + + + diff --git a/doc/features.html b/doc/features.html new file mode 100644 index 0000000..7ebad19 --- /dev/null +++ b/doc/features.html @@ -0,0 +1,46 @@ + + + + + + + Features - Packrat Docs + + + + + + +

Features

+ + Return to Contents + + +

Lexing and Parsing

+

Combinators are provided to build both lexers and parsers. Lexing is less flexible + as it does not need to incorporate choices, left recursion, or ambiguity.

+ +

Left Recursion

+

Any form of left recursive grammar will be parsed correctly, without infinite loops.

+ +

Ambiguity

+

All possible valid parses of the input by a constructed grammar will be followed + and incorporated into the resulting parse graph.

+ +

Polynomial Complexity

+

As per the paper that this library draws most of its ideas from, the worst case complexity + involved for both time and space should be polynomial. This has been experimentally confirmed + but as of yet no analysis has been done to determine specifics.

+ +

Error Messages

+

If there is a lexer or parser error then a message will be sent with the exception that + records what symbols were expected and where they were expected.

+ +

Piecewise Parsing

+

Both lexers and parsers can have their input fed to them piece by piece instead of all + at once.

+ + + + + diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..8b26b6e --- /dev/null +++ b/doc/index.html @@ -0,0 +1,48 @@ + + + + + + + Table of Contents - Packrat Docs + + + + + + +

Table of Contents

+ + +

This is documentation for the Packrat parser combinator library.

+ + +
    +
  1. License
    2. +
  2. Dependencies
    3. +
  3. Quickstart Guide
    4. +
  4. Features
    5. +
  5. Limitations
    6. +
  6. File Overview
    +
      +
    1. /src
      2. +
    2. /example
      3. +
    3. /test
      4. +
    +
    7. +
  7. Subprogram Listings
    +
      +
    1. Lexer Components
      2. +
    2. Parser Components
      3. +
    3. Parse Graph Operations
      4. +
    4. Utility Functions
      5. +
    +
    8. +
  8. Handling Errors
    9. +
  9. Credits and Further Reading
    10. +
+ + + + + diff --git a/doc/lexer_comb.html b/doc/lexer_comb.html new file mode 100644 index 0000000..eef5c04 --- /dev/null +++ b/doc/lexer_comb.html @@ -0,0 +1,347 @@ + + + + + + + Lexer Components - Packrat Docs + + + + + + +

Lexer Components

+ + Return to Contents + + +

Lexers are a much simplified version of the parsers. They operate like one giant + Choice combinator, the other combinators that you can combine with are more + limited, all combinators operate in the more usual greedy consume-as-much-as-possible + fashion, and the output is a sequence of tokens instead of a parse graph.
+
+ Think of it like grouping items of input together and labelling the groups, instead of + trying to create any complex parses.
+
+ Usage of lexers is optional.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 
+generic
+    Components : in Component_Array;
+package Scan_Parts is
+
+    function Scan
+           (Input : in Traits.Element_Array)
+        return Traits.Tokens.Token_Array;
+
+    procedure Reset;
+
+end Scan_Parts;
+
The scanner version that allows for piecewise scanning. The Scan function can be +called repeatedly with new input until it is supplied with an empty array, at which point it +is assumed that the end of input has been reached.
+
+The Reset procedure reverts the scanner to a clean state the same as if it was just +declared, with no partial results stored internally.
+generic
+    Components : in Component_Array;
+package Scan_Once is
+
+    function Scan
+           (Input : in Traits.Element_Array)
+        return Traits.Tokens.Token_Array;
+
+    procedure Reset;
+
+end Scan_Once;
+
This scanner version assumes that the input supplied is the only input available.
+
+The Reset procedure reverts the scanner to a clean state the same as if it was just +declared.
+generic
+    Components : in Component_Array;
+package Scan_With is
+
+    function Scan
+           (Input : in With_Input)
+        return Traits.Tokens.Token_Array;
+
+    procedure Reset;
+
+end Scan_With;
+
This scanner uses the supplied function to retrieve input to be lexed. Like the Scan_Parts +scanner it will continue to call the function until an empty array is returned, at which point it is +assumed that the end of input has been reached.
+
+The Reset procedure reverts the scanner to a clean state the same as if it was just +declared.
+generic
+    Components : in Component_Array;
+    Pad_In     : in Traits.Element_Type;
+    Pad_Out    : in Traits.Tokens.Token_Type;
+package Scan_Set is
+
+    procedure Scan
+           (Input  : in     Traits.Element_Array;
+            Output :    out Traits.Tokens.Token_Array);
+
+    procedure Reset;
+
+end Scan_Set;
+
This scanner allows the use of constant length input and output arrays. Scanning is done piecewise +until the input array begins with the supplied Pad_In character, upon which it is assumed that +the end of input has been reached. Any unused space in the output array is padded with the Pad_Out +character.
+
+The Reset procedure reverts the scanner to a clean state the same as if it was just declared.
+
+Note that the input and output array lengths do not have to remain the same between successive calls to +Scan.
+generic
+    Components : in Component_Array;
+    Pad_In     : in Traits.Element_Type;
+    Pad_Out    : in Traits.Tokens.Token_Type;
+package Scan_Set_With is
+
+    procedure Scan
+           (Input  : in     With_Input;
+            Output :    out Traits.Tokens.Token_Array);
+
+    procedure Reset;
+
+end Scan_Set_With;
+
A combination of Scan_With and Scan_Set, this scanner uses the supplied function +to retrieve input to be lexed, but uses padding characters in the same manner as Scan_Set.
+
+The Reset procedure reverts the scanner to a clean state the same as if it was just declared.
+generic
+    Label : in Traits.Label_Enum;
+    with function Combo
+           (Input : in Traits.Element_Array;
+            Start : in Positive)
+        return Combinator_Result;
+function Stamp
+       (Input   : in     Traits.Element_Array;
+        Context : in out Lexer_Context)
+    return Component_Result;
+
Runs the supplied combinator, and if successful converts the result into a token with the supplied +label that then gets added to the output. Scanning then proceeds from just after the input covered by +the token.
+generic
+    Label : in Traits.Label_Enum;
+    with function Combo
+           (Input : in Traits.Element_Array;
+            Start : in Positive)
+        return Combinator_Result;
+function Discard
+       (Input   : in     Traits.Element_Array;
+        Context : in out Lexer_Context)
+    return Component_Result;
+
Does the same thing as Stamp, however rather than adding the token to the output it instead +discards it. Scanning still proceeds from just after the input covered by the token.
+
+Even though the result is ultimately discarded it is nonetheless important that a label is used here so +that informative error messages can be generated.
+generic
+    Params : in Combinator_Array;
+function Sequence
+       (Input : in Traits.Element_Array;
+        Start : in Positive)
+    return Combinator_Result;
+
Lexes the supplied combinator Params in order. If they are all successful then the joined +successful result is returned, otherwise the combinator fails.
+generic
+    with function Param
+           (Input : in Traits.Element_Array;
+            Start : in Positive)
+        return Combinator_Result;
+    Number : in Positive;
+function Count
+       (Input : in Traits.Element_Array;
+        Start : in Positive)
+    return Combinator_Result;
+
Lexes the supplied combinator Param the supplied Number of times one after another. +If it is all successful then the joined successful result is returned, otherwise the combinator fails.
+generic
+    with function Param
+           (Input : in Traits.Element_Array;
+            Start : in Positive)
+        return Combinator_Result;
+    Minimum : in Natural := 0;
+function Many
+       (Input : in Traits.Element_Array;
+        Start : in Positive)
+    return Combinator_Result;
+
Lexes the supplied combinator Param as many times as it can. Succeeds if it manages to do +so at least Minimum number of times.
+generic
+    with function Param
+           (Input : in Traits.Element_Array;
+            Start : in Positive)
+        return Combinator_Result;
+    with function Test
+           (Item : in Traits.Element_Type)
+        return Boolean;
+    Minimum : in Natural := 0;
+function Many_Until
+       (Input : in Traits.Element_Array;
+        Start : in Positive)
+    return Combinator_Result;
+
Lexes the supplied combinator Param over and over until Test succeeds on the next +available item in the input. Succeeds if it manages to lex Param at least Minimum times. +Fails if Param fails before Test succeeds on the next available item of input.
+generic
+    with function Test
+           (Item : in Traits.Element_Type)
+        return Boolean;
+function Satisfy
+       (Input : in Traits.Element_Array;
+        Start : in Positive)
+    return Combinator_Result;
+
Lexes one item of input if the supplied Test function succeeds on that item, otherwise fails.
+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;
+        Start : in Positive)
+    return Combinator_Result;
+
First uses the supplied Change function on the first item of input, then acts as in Satisfy +on the changed item. Upon success the item lexed is the original item.
+generic
+    Item : in Traits.Element_Type;
+function Match
+       (Input : in Traits.Element_Array;
+        Start : in Positive)
+    return Combinator_Result;
+
Lexes one 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;
+        Start : in Positive)
+    return Combinator_Result;
+
Lexes one item of input if, after applying the supplied Change function to it, it +matches Item.
+generic
+    Items : in Traits.Element_Array;
+function Multimatch
+       (Input : in Traits.Element_Array;
+        Start : in Positive)
+    return Combinator_Result;
+
Lexes the next Items'Length items of input if they match Items.
+generic
+    Number : in Positive := 1;
+function Take
+       (Input : in Traits.Element_Array;
+        Start : in Positive)
+    return Combinator_Result;
+
Lexes 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;
+        Start : in Positive)
+    return Combinator_Result;
+
Lexes successive items of input as long as they satisfy the supplied Test function.
+generic
+    with function Test
+           (Item : in Traits.Element_Type)
+        return Boolean;
+function Take_Until
+       (Input : in Traits.Element_Array;
+        Start : in Positive)
+    return Combinator_Result;
+
Lexes items of input until the next available item satisfies the supplied Test function.
+ + + + + diff --git a/doc/license.html b/doc/license.html new file mode 100644 index 0000000..33b1631 --- /dev/null +++ b/doc/license.html @@ -0,0 +1,53 @@ + + + + + + + Licensing Information - Packrat Docs + + + + + + +

Licensing Information

+ + Return to Contents + + +

The Packrat parser combinator library is licensed under the Sunset License v1.0.
+ The full text of this license is as follows:

+ + 
+
+SUNSET LICENSE
+Version 1.0, June 2017
+
+
+1. You may copy, modify, use, sell, or distribute this work, verbatim or
+modified, for any purpose.
+
+2. If you sell or distribute this work, whether verbatim or modified, you must
+include a copy of this license, and you must make the source code available for
+no extra charge.
+
+3. A modified version of this work must be clearly labeled as such.
+
+4. Derivative works must also be licensed under this license or a license of
+equivalent terms. As an exception, linking this work with another, whether
+statically or dynamically, does not impose any license requirements on the
+other work.
+
+5. If a minimum of 15 years have passed since the date of first publishing for
+a part of this work, then that part is placed into the public domain and you
+may do whatever you want with it, regardless of all other clauses.
+
+
+ +

This text can also be found in license.txt in the main directory of this repo.

+ + + + + diff --git a/doc/limits.html b/doc/limits.html new file mode 100644 index 0000000..d09fe5b --- /dev/null +++ b/doc/limits.html @@ -0,0 +1,49 @@ + + + + + + + Limitations - Packrat Docs + + + + + + +

Limitations

+ + Return to Contents + + +

Recognisers

+

While this package can be used to construct recognisers easily, this would likely + not be very efficient compared to a library more specialised for that purpose.

+ +

Cyclic Grammars

+

Grammars that have cycles in them will be treated as any other form of left recursion + and eventually be curtailed. This means that the resulting parse graph will not have + any cycles. If you want a cyclic grammar to result in a cyclic result, then this library + is not what you are after.

+ +

Generics

+

This library makes very heavy use of generics. If your Ada compiler has any issues + handling generics then you may experience suboptimal performance.

+ +

Parse Graph Data Structure

+

In order to keep the parse graph to polynomial space complexity, it is a specialised + data structure and is not the same thing as a more standard directed graph.

+ +

Piecewise Parsing

+

Due to the possibility of incomplete parses, in the worst case using piecewise parsing + can result in the lexer or parser holding the entire input in memory before returning a + result.

+ +

Error Recovery

+

While error messages can be informative, there is currently no consideration given to + being able to recover from an error and continue parsing.

+ + + + + diff --git a/doc/parse_graph_op.html b/doc/parse_graph_op.html new file mode 100644 index 0000000..2cc3591 --- /dev/null +++ b/doc/parse_graph_op.html @@ -0,0 +1,424 @@ + + + + + + + Parse Graph Operations - Packrat Docs + + + + + + +

Parse Graph Operations

+ + Return to Contents + + +

While this uses a directed graph library with node and edge labels internally, it is rather + different from a usage point of view. A parse graph is designed around tokens (from + Packrat.Tokens) that can each have more tokens as children.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 
+procedure Assign
+       (Target : in out Parse_Graph;
+        Source : in     Parse_Graph);
+
+function Copy
+       (Source : in Parse_Graph)
+    return Parse_Graph;
+
+procedure Move
+       (Target, Source : in out Parse_Graph);
+
Standard assignment operations that are common to most things in the Ada standard Container library.
+function Is_Empty
+       (Container : in Parse_Graph)
+    return Boolean;
+
Tests whether a graph is empty.
+procedure Clear
+       (Container : in out Parse_Graph);
+
Completely clears a graph, leaving it empty afterwards.
+function Debug_String
+       (Container : in Parse_Graph)
+    return String;
+
Generate a string that shows a pretty printed structure of the graph in a similar way to page three of +the paper referenced in Further Reading.
+function Contains
+       (Container : in Parse_Graph;
+        Token     : in Traits.Tokens.Token_Type)
+    return Boolean;
+
+function Contains
+       (Container : in Parse_Graph;
+        Position  : in Traits.Tokens.Finished_Token_Type)
+    return Boolean;
+
+function Contains
+       (Container : in Parse_Graph;
+        Grouping  : in Token_Group)
+    return Boolean;
+
+function Contains
+       (Container : in Parse_Graph;
+        Parent    : in Traits.Tokens.Finished_Token_Type;
+        Subtokens : in Traits.Tokens.Finished_Token_Array)
+    return Boolean;
+
Tests for whether a graph contains various things.
+function Reachable
+       (Container : in Parse_Graph;
+        Position  : in Traits.Tokens.Finished_Token_Type)
+    return Boolean
+with Pre => Container.Has_Root;
+
Checks whether a given finished token is reachable somehow from one or more of the root tokens of +the graph.
+function All_Reachable
+       (Container : in Parse_Graph)
+    return Boolean
+with Pre => Container.Has_Root;
+
Checks whether all tokens in the graph are reachable from one or more of the root tokens.
+function Valid_Token
+       (Fin_Token : in Traits.Tokens.Finished_Token_Type)
+    return Boolean;
+
Checks whether the start and finish values of a token make sense, or in other words that the finish +value is no more than one less than the start value..
+function Valid_Starts_Finishes
+       (Parent    : in Traits.Tokens.Finished_Token_Type;
+        Subtokens : in Traits.Tokens.Finished_Token_Array)
+    return Boolean
+with Pre => Subtokens'Length > 0;
+
Checks whether the various start and finish values of all the tokens make sense for being a parent +and a list of children. All the starts and finishes of individual tokens must make sense as in +Valid_Token, all the children tokens must be in order, the parent start and finish range must +fully cover all the children start and finish ranges, and none of the children start and finish ranges +can overlap each other.
+function Loops_Introduced
+       (Container : in Parse_Graph;
+        Parent    : in Traits.Tokens.Finished_Token_Type;
+        Subtokens : in Traits.Tokens.Finished_Token_Array)
+    return Boolean
+with Pre => Subtokens'Length > 0 and
+        Valid_Starts_Finishes (Parent, Subtokens);
+
Checks whether adding the given parent and children group connection would introduce a loop into +the graph.
+function Is_Sorted
+       (Finishes : in Traits.Tokens.Finish_Array)
+    return Boolean;
+
+function Is_Sorted
+       (Positions : in Traits.Tokens.Finished_Token_Array)
+    return Boolean;
+
+function Is_Sorted
+       (Groupings : in Token_Group_Array)
+    return Boolean;
+
Checks whether various sorts of arrays are sorted.
+function No_Duplicates
+       (Finishes : in Traits.Tokens.Finish_Array)
+    return Boolean;
+
+function No_Duplicates
+       (Positions : in Traits.Tokens.Finished_Token_Array)
+    return Boolean;
+
+function No_Duplicates
+       (Groupings : in Token_Group_Array)
+    return Boolean;
+
Checks whether there are any duplicates in various sorts of arrays.
+procedure Include
+       (Container : in out Parse_Graph;
+        Token     : in     Traits.Tokens.Token_Type)
+with Post => Container.Contains (Token);
+
Adds a token to the graph. If the graph already contains the token, this does nothing.
+procedure Connect
+       (Container : in out Parse_Graph;
+        Parent    : in     Traits.Tokens.Finished_Token_Type;
+        Subtokens : in     Traits.Tokens.Finished_Token_Array)
+with Pre => Subtokens'Length > 0 and
+        Valid_Starts_Finishes (Parent, Subtokens) and
+        not Container.Loops_Introduced (Parent, Subtokens);
+
Adds a connection group between a parent token and some children tokens in the graph. If +any of the tokens involved is not in the graph already they are first added. If the connection +already exists in the graph, this does nothing.
+procedure Prune
+       (Container : in out Parse_Graph;
+        Token     : in     Traits.Tokens.Token_Type)
+with Post => not Container.Contains (Token);
+
+procedure Prune
+       (Container : in out Parse_Graph;
+        Position  : in     Traits.Tokens.Finished_Token_Type)
+with Post => not Container.Contains (Position);
+
+procedure Prune
+       (Container : in out Parse_Graph;
+        Grouping  : in     Token_Group)
+with Post => not Container.Contains (Grouping);
+
Removes various things from a graph. No effort is made to remove anything made unreachable +by these operations.
+procedure Delete_Unreachable
+       (Container : in out Parse_Graph)
+with Pre => Container.Has_Root,
+    Post => Container.All_Reachable;
+
Removes all unreachable tokens, edges, and otherwise from a graph. Note that if the graph has +no root tokens then this will become equivalent to Clear.
+function Has_Root
+       (Container : in Parse_Graph)
+    return Boolean;
+
Checks whether a graph contains a root token.
+procedure Set_Root
+       (Container : in out Parse_Graph;
+        Tokens    : in     Traits.Tokens.Finished_Token_Array)
+with Pre => (for all F of Tokens => Container.Contains (F.Token)),
+    Post => Container.Has_Root;
+
Sets one or more root tokens for a graph.
+procedure Clear_Root
+       (Container : in out Parse_Graph)
+with Post => not Container.Has_Root;
+
Removes all root tokens from the graph. Note that the graph will still contain the tokens, +they just won't be considered root tokens anymore.
+function Root_Elements
+       (Container : in Parse_Graph)
+    return Traits.Tokens.Finished_Token_Array
+with Pre => Container.Has_Root;
+
Retrieves all the root tokens for a given graph.
+function Finish_List
+       (Container : in Parse_Graph;
+        Token     : in Traits.Tokens.Token_Type)
+    return Traits.Tokens.Finish_Array
+with Pre => Container.Contains (Token),
+    Post => Is_Sorted (Finish_List'Result) and
+        No_Duplicates (Finish_List'Result);
+
For a given unfinished token and a graph, returns all valid finishes that the token could take +such that the finished token is in the graph.
+function Is_Leaf
+       (Container : in Parse_Graph;
+        Position  : in Traits.Tokens.Finished_Token_Type)
+    return Boolean
+with Pre => Container.Contains (Position);
+
Predicate to check whether a finished token is a leaf node in the graph. That is, whether it +has no children.
+function Is_Branch
+       (Container : in Parse_Graph;
+        Position  : in Traits.Tokens.Finished_Token_Type)
+    return Boolean
+with Pre => Container.Contains (Position);
+
Predicate to check whether a finished token is a branch node in the graph. That is, whether it +has children.
+function Subgroups
+       (Container : in Parse_Graph;
+        Position  : in Traits.Tokens.Finished_Token_Type)
+    return Token_Group_Array
+with Pre => Container.Contains (Position),
+    Post => Is_Sorted (Subgroups'Result) and
+        No_Duplicates (Subgroups'Result) and
+        (for all G of Subgroups'Result => Finish (G) = Position.Finish);
+
Returns an array of all the groups of children of a particular token in the graph. There will only +be multiple groups if the graph is ambiguous at this point.
+function First_Index
+       (Grouping : in Token_Group)
+    return Positive;
+
+function Last_Index
+       (Grouping : in Token_Group)
+    return Positive;
+
+function Length
+       (Grouping : in Token_Group)
+    return Ada.Containers.Count_Type;
+
+function Element
+       (Grouping : in Token_Group;
+        Index    : in Positive)
+    return Traits.Tokens.Finished_Token_Type
+with Pre => Index in First_Index (Grouping) .. Last_Index (Grouping);
+
These work as you would expect on an array/vector. Element returns a particular +child token in the given group.
+function Elements
+       (Grouping : in Token_Group)
+    return Traits.Tokens.Finished_Token_Array
+with Post => Is_Sorted (Elements'Result) and
+        Valid_Starts_Finishes (Parent (Grouping), Elements'Result);
+
Returns all the children tokens in the group as an array instead of a Token_Group.
+function Parent
+       (Grouping : in Token_Group)
+    return Traits.Tokens.Finished_Token_Type;
+
Returns the parent token of the group.
+function Finish
+       (Grouping : in Token_Group)
+    return Traits.Tokens.Finish_Type;
+
Returns the finishing position of the group, which is the same as the finish of the parent token.
+function Is_Root_Ambiguous
+       (Container : in Parse_Graph)
+    return Boolean
+with Pre => Container.Has_Root;
+
Checks whether the root tokens for a graph are ambiguous. The root is ambiguous if there are multiple +root tokens, or if there are multiple child groups attached to a root token.
+function Is_Ambiguous
+       (Container : in Parse_Graph)
+    return Boolean;
+
Checks if the graph is ambiguous. That is, checks whether there are multiple root tokens or if +any token in the graph has multiple child groups attached to it.
+function Ambiguities
+       (Container      : in     Parse_Graph;
+        Ambiguous_Root :    out Boolean)
+    return Traits.Tokens.Finished_Token_Array
+with Post => Is_Sorted (Ambiguities'Result) and
+        No_Duplicates (Ambiguities'Result);
+
Gives the parent tokens of all ambiguities in the graph.
+function Isomorphic
+       (Left, Right : in Parse_Graph)
+    return Boolean
+with Pre => Left.Has_Root and Right.Has_Root;
+
Checks whether the two graphs are isomorphic in structure. This means that the tokens and groups +are all the same except for any consistent offset in the start and finish values.
+function Isomorphic_Subgraph
+       (Left_Graph     : in Parse_Graph;
+        Left_Position  : in Traits.Tokens.Finished_Token_Type;
+        Right_Graph    : in Parse_Graph;
+        Right_Position : in Traits.Tokens.Finished_Token_Type)
+    return Boolean
+with Pre => Left_Graph.Contains (Left_Position) and
+        Right_Graph.Contains (Right_Position);
+
Checks whether the subgraphs formed by the respective positions in each graph and all their connected +children are isomorphic. This means that all the tokens and groups in those subgraphs are all the same +except for any consistent offset in the start and finish values. Note that it is possible to check +for isomorphism between two subgraphs in the same graph.
+ + + + + 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.
+ + + + + diff --git a/doc/quickstart.html b/doc/quickstart.html new file mode 100644 index 0000000..b525f8f --- /dev/null +++ b/doc/quickstart.html @@ -0,0 +1,65 @@ + + + + + + + Quickstart Guide - Packrat Docs + + + + + + +

Quickstart Guide

+ + Return to Contents + + +

Lexing and Parsing

+ +

The package that you will need is Packrat.Standard. If you are parsing + ordinary strings then Packrat.Utilities may also be useful.
+
+ Define enumeration types for all the lexer token labels and parse graph node labels + you need, then use them to instantiate Packrat.Standard.
+
+ Instantiate subprograms from the nested Lexers package to create your lexer, + and subprograms from the nested Parsers package to create your parser.
+
+ Take special care when using any redirects from Parsers. They are used to + allow for self-referential instantiation of parser combinators and must be set properly + before using any parsers built with them. Otherwise an exception will be raised.
+
+ Feed your input through the lexer, then the results of that through the parser to + obtain a parse graph.
+
+ Use subprograms from the nested Parse_Graphs package to inspect and manipulate + the resulting graph. +

+ + +

Parsing Only

+ +

The package that you will need is Packrat.No_Lex. If you are parsing + ordinary strings then Packrat.Utilities may also be useful.
+
+ Define an enumeration type for all the parse graph node labels you need, then use it + to instantiate Packrat.No_Lex.
+
+ Instantiate subprograms from the nested Parsers package to create your parser.
+
+ Take special care when using any redirects. They are used to allow for self-referential + instantiation of parser combinators and must be set properly before using any parsers + built with them. Otherwise an exception will be raised.
+
+ Feed your input through the parser to obtain a parse graph.
+
+ Use subprograms from the nested Parse_Graphs package to inspect and manipulate + the resulting graph. +

+ + + + + diff --git a/doc/src_overview.html b/doc/src_overview.html new file mode 100644 index 0000000..a0f4341 --- /dev/null +++ b/doc/src_overview.html @@ -0,0 +1,74 @@ + + + + + + + /src Overview - Packrat Docs + + + + + + +

/src Overview

+ + Return to Contents + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
packrat.adb
packrat.ads		The main Packrat package.
packrat-errors.adb
packrat-errors.ads
packrat-errors-parts.adb		Error handling functionality. Use this if you need to handle Lexer_Error or + Parser_Error exception messages.
packrat-lexers.adb
packrat-lexers.ads		Scanner functions, lexer components and combinators.
packrat-no_lex.adsConvenience package to allow use of parser combinators and related functionality without + having to with and instantiate a long list of packages.
packrat-parse_graphs.adb
packrat-parse_graphs.ads		The data structure that parse results end up in. Externally it gives the appearance + of a directed acyclic graph with several root nodes. Internally a lot of deduplication is + done by labeling the nodes with starting points and the edges with finishing points then + keeping track of what edges are valid to go down given the current position.
packrat-parsers.adb
packrat-parsers.ads		Parser functions and combinators. More flexible and extensive than Packrat.Lexers.
packrat-standard.adsConvenience package to allow use of both lexer and parser combinators as well as related + functionality without having to with and instantiate a long list of packages.
packrat-tokens.adb
packrat-tokens.ads		Handles the individual tokens that lexers give as output and that form the nodes + of a parse graph.
packrat-traits.adb
packrat-traits.ads		Convenience package to collect the various other things necessary to instantiate + a lot of the other packages.
packrat-utilities.adb
packrat-utilities.ads		Convenience predicates for use with Satisfy combinators and the like when + lexing or parsing standard strings.
+ + + + + diff --git a/doc/test_overview.html b/doc/test_overview.html new file mode 100644 index 0000000..a5c7856 --- /dev/null +++ b/doc/test_overview.html @@ -0,0 +1,51 @@ + + + + + + + /test Overview - Packrat Docs + + + + + + +

/test Overview

+ + Return to Contents + + +

CAUTION: These files are used for unit testing the library and can + undergo changes at any time.

+ + + + + + + + + + + + + + + + + + +
packrat-lexers-debug.adb
packrat-lexers-debug.ads
+ packrat-parsers-debug.adb
packrat-parsers-debug.ads		Extensions to the Packrat.Lexers and Packrat.Parsers package to expose + some of the functionality for unit testing.
rat_tests.adsSets up some common packages needed for all the unit tests.
rat_tests-errors.adb
rat_tests-errors.ads
+ rat_tests-lexers.adb
rat_tests-lexers.ads
+ rat_tests-parse_graphs.adb
rat_tests-parse_graphs.ads
+ rat_tests-parsers.adb
rat_tests-parsers.ads
+ rat_tests-tokens.adb
rat_tests-tokens.ads
+ rat_tests-utilities.adb
rat_tests-utilities.ads		Unit tests for the various packages in Packrat.
test_main.adbThe main program that runs all the unit tests.
+ + + + + diff --git a/doc/util_func.html b/doc/util_func.html new file mode 100644 index 0000000..13d7c21 --- /dev/null +++ b/doc/util_func.html @@ -0,0 +1,148 @@ + + + + + + + Utility Functions - Packrat Docs + + + + + + +

Utility Functions

+ + Return to Contents + + +

These are intended as helper functions for use with Satisfy combinators and the like + when parsing ordinary strings.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 
+generic
+    Set : in Ada.Strings.Maps.Character_Set;
+function In_Set
+       (Element : in Character)
+    return Boolean;
+
Tests whether a Character is present within the given Character_Set.
+generic
+    Set : in Ada.Strings.Maps.Character_Set;
+function Not_In_Set
+       (Element : in Character)
+    return Boolean;
+
Tests whether a Character is not present within the given Character_Set.
+function Is_Digit
+       (Char : in Character)
+    return Boolean;
+
Tests whether a Character is one of the digits 0 through 9.
+function Is_Hex
+       (Char : in Character)
+    return Boolean;
+
Tests whether a Character is one of the digits 0 through 9 or one of the letters +A through F, case insensitive.
+function Is_Letter
+       (Char : in Character)
+    return Boolean;
+
Tests whether a Character is one of the letters A through Z, case insensitive.
+function Is_Alphanumeric
+       (Char : in Character)
+    return Boolean;
+
Tests whether a Character is one of the digits 0 through 9 or one of the letters +A through Z, case insensitive.
+function Is_Punctuation
+       (Char : in Character)
+    return Boolean;
+
Tests whether a Character is one of the punctuation characters ! " # $ % +& ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ which annoyingly +occupies several disjoint sections of ASCII.
+function Is_ASCII
+       (Char : in Character)
+    return Boolean;
+
Tests whether a Character is in the lower half of the ASCII character set.
+function Is_Extended_ASCII
+       (Char : in Character)
+    return Boolean;
+
Tests whether a Character is in the upper half of the ASCII character set.
+function Is_Space
+       (Char : in Character)
+    return Boolean;
+
Tests whether a Character is a space.
+function Is_Linespace
+       (Char : in Character)
+    return Boolean;
+
Tests whether a Character is a space or horizontal tab.
+function Is_End_Of_Line
+       (Char : in Character)
+    return Boolean;
+
Tests whether a Character is a linefeed or carriage return.
+function Is_Whitespace
+       (Char : in Character)
+    return Boolean;
+
Tests whether a Character is a space, horizontal tab, linefeed, or carriage return.
+function Not_Whitespace
+       (Char : in Character)
+    return Boolean;
+
Tests whether a Character is not a space, horizontal tab, linefeed, or carriage return.
+ + + + + -- cgit