1doctools::tcl::parse(n)       Documentation tools      doctools::tcl::parse(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools::tcl::parse - Processing text in 'subst -novariables' format
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require snit
14
15       package require fileutil
16
17       package require logger
18
19       package require struct::list
20
21       package require struct::stack
22
23       package require struct::set
24
25       package require treeql
26
27       package require doctools::tcl::parse
28
29       ::doctools::tcl::parse text tree text ?root?
30
31       ::doctools::tcl::parse file tree path ?root?
32
33______________________________________________________________________________
34

DESCRIPTION

36       This  package provides commands for parsing text with embedded Tcl com‐
37       mands as accepted by the Tcl builtin command  subst  -novariables.  The
38       result of the parsing is an abstract syntax tree.
39
40       This  is  an  internal package of doctools, for use by the higher level
41       parsers processing the docidx, doctoc, and doctools markup languages.
42

API

44       ::doctools::tcl::parse text tree text ?root?
45              The command takes the text and parses it  under  the  assumption
46              that  it contains a string acceptable to the Tcl builtin command
47              subst -novariables. Errors are thrown otherwise during the pars‐
48              ing.  The  format  used for these errors in described in section
49              Error format.
50
51              The command returns the empty string as it  result.  The  actual
52              result  of  the parsing is entered into the tree structure tree,
53              under the node root.  If root is not specified the root of  tree
54              is  used.  The  tree  has  to exist and be the command of a tree
55              object which supports the same methods as trees created  by  the
56              package struct::tree.
57
58              In case of errors tree will be left in an undefined state.
59
60       ::doctools::tcl::parse file tree path ?root?
61              The same as text, except that the text to parse is read from the
62              file specified by path.
63

ERROR FORMAT

65       When the parser encounters a problem in the  input  it  will  throw  an
66       error using the format described here.
67
68       [1]    The  message will contain the reason for the problem (unexpected
69              character or end of input in input), the character in  question,
70              if  any,  and the line and column the problem was found at, in a
71              human readable form. This part is not documented further as  its
72              format  may  change as we see fit. It is intended for human con‐
73              sumption, not machine.
74
75       [2]    The error code however will contain a machine-readable represen‐
76              tation  of the problem, in the form of a 5-element list contain‐
77              ing, in the order listed below
78
79              [1]    the constant string doctools::tcl::parse
80
81              [2]    the cause of the problem, one of
82
83                     char   Unexpected character in input
84
85                     eof    Unexpected end of the input
86
87              [3]    The location of the problem as offset from the  beginning
88                     of  the  input, counted in characters. Note: Line markers
89                     count as one character.
90
91              [4]    The line the problem was found on (counted from 1 (one)),
92
93              [5]    The column the problem  was  found  at  (counted  from  0
94                     (zero))
95

TREE STRUCTURE

97       After  successfully  parsing  a string the generated tree will have the
98       following structure:
99
100       [1]    In the following items the word 'root' refers to the node  which
101              was  specified as the root of the tree when invoking either text
102              or file. This may be the actual root of the tree.
103
104       [2]    All the following items further ignore the possibility  of  pre-
105              existing  attributes  in  the  pre-existing nodes. If attributes
106              exists with the same names as the attributes used by the  parser
107              the  pre-existing values are written over. Attributes with names
108              not clashing with the parser's attributes are not touched.
109
110       [3]    The root node has no attributes.
111
112       [4]    All other nodes have the attributes
113
114              type   The value is a string from the set {  Command  ,  Text  ,
115                     Word }
116
117              range  The  value is either empty or a 2-element list containing
118                     integer numbers. The numbers are the offsets of the first
119                     and  last  character  in  the  input  text,  of the token
120                     described by the node,.
121
122              line   The value is an integer, it describes  the  line  in  the
123                     input  the token described by the node ends on. Lines are
124                     counted from 1 (one).
125
126              col    The value is an integer, it describes the column  in  the
127                     line  in  the  input the token described by the node ends
128                     on. Columns are counted from 0 (zero).
129
130       [5]    The children of the root, if any, are of type Command and  Text,
131              in  semi-alternation.  This  means:  After a Text node a Command
132              node has to follow, and anything can follow a  Command  node,  a
133              Text or other Command node.
134
135       [6]    The children of a Command node, if any, are of type Command, and
136              Text, and Word, they describe the arguments of the command.
137
138       [7]    The children of a Word node, if any, are of type Command,  Text,
139              in  semi-alternation.  This  means:  After a Text node a Command
140              node has to follow, and anything can follow a  Command  node,  a
141              Text or other Command node.
142
143       [8]    A Word node without children represents the empty string.
144
145       [9]    All Text nodes are leaves of the tree.
146
147       [10]   All  leaves  of the tree are either Text or Command nodes.  Word
148              nodes cannot be leaves.
149

BUGS, IDEAS, FEEDBACK

151       This document, and the package it describes, will  undoubtedly  contain
152       bugs  and  other problems.  Please report such in the category doctools
153       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
154       also  report any ideas for enhancements you may have for either package
155       and/or documentation.
156
157       When proposing code changes, please provide unified diffs, i.e the out‐
158       put of diff -u.
159
160       Note  further  that  attachments  are  strongly  preferred over inlined
161       patches. Attachments can be made by going  to  the  Edit  form  of  the
162       ticket  immediately  after  its  creation, and then using the left-most
163       button in the secondary navigation bar.
164

KEYWORDS

166       Tcl syntax, command, doctools, parser, subst, word
167

CATEGORY

169       Documentation tools
170
172       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
173
174
175
176
177tcllib                                 1               doctools::tcl::parse(n)
Impressum