Merge commit '7c621da28f07e449ad90c387344f07a453927569' as 'tcllib'

1 files changed, 82 insertions, 0 deletions

diff --git a/tcllib/modules/pt/pt_parser_api.man b/tcllib/modules/pt/pt_parser_api.man
new file mode 100644
index 0000000..0abbf9d
--- /dev/null
+++ b/tcllib/modules/pt/pt_parser_api.man
@@ -0,0 +1,82 @@
+[comment {-*- text -*- doctools manpage}]
+[manpage_begin pt_parser_api i 1]
+[include include/module.inc]
+[titledesc {Parser API}]
+[description]
+[include include/ref_intro.inc]
+
+This document describes the API shared by the grammar interpreter
+provided by the package [package pt::peg::interp] and the parsers
+generated by the [cmd pt] application for the result formats
+[const critcl], [const snit], and [const oo] regarding access
+to the actual parsing functionality.
+
+[para]
+
+Its intended audience are people who wish to create a parser for some
+language of theirs and then use that parser within a Tcl-based package
+or application.
+
+[para]
+
+It resides in the User Layer of Parser Tools.
+[para][image arch_user_pkg][para]
+
+[section {Class API}]
+
+[list_begin definitions]
+[call [cmd className] [opt [arg objectName]]]
+
+The class command constructs parser instances, i.e. objects. The
+result of the command is the fully-qualified name of the instance
+command.
+
+[para]
+
+If no [arg objectName] is specified the class will generate and use an
+automatic name. If the [arg objectName] was specified, but is not
+fully qualified the command will be created in the current namespace.
+
+[list_end]
+
+[section {Instance API}]
+
+All parser instances provide at least the methods shown below:
+
+[list_begin definitions]
+[include include/std_parser_object_api.inc]
+[list_end]
+
+[section Usage]
+
+A generated parser is used like this
+
+[example {
+    package require the-parser-package ;# Generated by result-formats 'critcl', 'snit' or 'oo' of 'pt'.
+    set parser [the-parser-class]
+
+    set ast [$parser parse $channel]
+    ... process the abstract syntax tree ...
+}]
+
+When using a grammar interpreter for parsing some differences creep in
+
+[example {
+    package require the-grammar-package ;# Generated by result-format 'container' of 'pt'.
+    set grammar [the-grammar-class]
+
+    package require pt::peg::interp
+    set parser [pt::peg::interp]
+
+    $parser use $grammar
+
+    set ast [$parser parse $channel]
+    $parser destroy
+
+    ... process the abstract syntax tree ...
+}]
+
+[include include/serial/ast.inc]
+[include include/serial/pexpression.inc]
+[include include/feedback.inc]
+[manpage_end]