1pt_parse_peg(i)                  Parser Tools                  pt_parse_peg(i)
2
3
4
5______________________________________________________________________________
6

NAME

8       pt_parse_peg - Parser Tools PEG Parser
9

SYNOPSIS

11       package require Tcl  8.5
12
13       package require pt::parse::peg  1
14
15       pt::parse::peg ?objectName?
16
17       objectName destroy
18
19       objectName parse chan
20
21       objectName parset text
22
23______________________________________________________________________________
24

DESCRIPTION

26       Are  you  lost ?  Do you have trouble understanding this document ?  In
27       that case please read the overview  provided  by  the  Introduction  to
28       Parser  Tools.  This document is the entrypoint to the whole system the
29       current package is a part of.
30
31       This package provides a class whose instances are parsers  for  parsing
32       expression grammars in textual form.
33

CLASS API

35       pt::parse::peg ?objectName?
36              The class command constructs parser instances, i.e. objects. The
37              result of  the  command  is  the  fully-qualified  name  of  the
38              instance command.
39
40              If no objectName is specified the class will generate and use an
41              automatic name. If the objectName  was  specified,  but  is  not
42              fully  qualified  the  command  will  be  created in the current
43              namespace.
44

INSTANCES API

46       All parser instances provide at least the methods shown below:
47
48       objectName destroy
49              This method destroys the parser instance, releasing all  claimed
50              memory and other resources, and deleting the instance command.
51
52              The result of the command is the empty string.
53
54       objectName parse chan
55              This  method runs the parser using the contents of chan as input
56              (starting at the current location in the channel), until parsing
57              is  not  possible anymore, either because parsing has completed,
58              or run into a syntax error.
59
60              Note here that the Parser Tools are based on Tcl 8.5+. In  other
61              words, the channel argument is not restricted to files, sockets,
62              etc. We have the full power of reflected channels available.
63
64              It should also be noted that the  parser  pulls  the  characters
65              from  the  input stream as it needs them. If a parser created by
66              this package has to be operated in a push aka event-driven  man‐
67              ner  it  will  be necessary to go to Tcl 8.6+ and use the corou‐
68              tine::auto to wrap it into a coroutine where  read  is  properly
69              changed for push-operation.
70
71              Upon  successful completion the command returns an abstract syn‐
72              tax tree as its result.  This AST is in the  form  specified  in
73              section AST serialization format.  As a plain nested Tcl-list it
74              can then be processed with any  Tcl  commands  the  user  likes,
75              doing  transformations,  semantic  checks, etc.  To help in this
76              the package pt::ast provides a set of convenience  commands  for
77              validation of the tree's basic structure, printing it for debug‐
78              ging, and walking it either from the bottom up, or top down.
79
80              When encountering a syntax error the command will throw an error
81              instead.   This  error will be a 4-element Tcl-list, containing,
82              in the order listed below:
83
84              [1]    The string  pt::rde  identifying  it  as  parser  runtime
85                     error.
86
87              [2]    The location of the parse error, as character offset from
88                     the beginning of the parsed input.
89
90              [3]    The location of parse error, now as a 2-element list con‐
91                     taining line-number and column in the line.
92
93              [4]    A  set  of atomic parsing expressions indicating encoding
94                     the characters  and/or  nonterminal  symbols  the  parser
95                     expected  to  see at the location of the parse error, but
96                     did not get.  For the  specification  of  atomic  parsing
97                     expressions  please see the section PE serialization for‐
98                     mat.
99
100       objectName parset text
101              This method runs the parser using the string in text  as  input.
102              In all other ways it behaves like the method parse, shown above.
103

BUGS, IDEAS, FEEDBACK

105       This  document,  and the package it describes, will undoubtedly contain
106       bugs and other problems.  Please report such in the category pt of  the
107       Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please also
108       report any ideas for enhancements  you  may  have  for  either  package
109       and/or documentation.
110
111       When proposing code changes, please provide unified diffs, i.e the out‐
112       put of diff -u.
113
114       Note further that  attachments  are  strongly  preferred  over  inlined
115       patches.  Attachments  can  be  made  by  going to the Edit form of the
116       ticket immediately after its creation, and  then  using  the  left-most
117       button in the secondary navigation bar.
118

KEYWORDS

120       EBNF,  LL(k),  PEG,  TDPL, context-free languages, expression, grammar,
121       matching, parser, parsing expression, parsing expression grammar,  push
122       down  automaton,  recursive descent, state, top-down parsing languages,
123       transducer
124

CATEGORY

126       Parsing and Grammars
127
129       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
130
131
132
133
134tcllib                                 1                       pt_parse_peg(i)
Impressum