Provided by: tcllib_1.21+dfsg-1_all bug

NAME

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

SYNOPSIS

       package require Tcl  8.4

       package require snit

       package require fileutil

       package require logger

       package require struct::list

       package require struct::stack

       package require struct::set

       package require treeql

       package require doctools::tcl::parse

       ::doctools::tcl::parse text tree text ?root?

       ::doctools::tcl::parse file tree path ?root?

_________________________________________________________________________________________________

DESCRIPTION

       This  package provides commands for parsing text with embedded Tcl commands as accepted by
       the Tcl builtin command subst -novariables. The result  of  the  parsing  is  an  abstract
       syntax tree.

       This  is  an  internal package of doctools, for use by the higher level parsers processing
       the docidx, doctoc, and doctools markup languages.

API

       ::doctools::tcl::parse text tree text ?root?
              The command takes the text and parses it under the assumption that  it  contains  a
              string  acceptable to the Tcl builtin command subst -novariables. Errors are thrown
              otherwise during the parsing. The format used for  these  errors  in  described  in
              section Error format.

              The command returns the empty string as it result. The actual result of the parsing
              is entered into the tree structure tree, under the  node  root.   If  root  is  not
              specified  the  root of tree is used. The tree has to exist and be the command of a
              tree object which supports the  same  methods  as  trees  created  by  the  package
              struct::tree.

              In case of errors tree will be left in an undefined state.

       ::doctools::tcl::parse file tree path ?root?
              The  same as text, except that the text to parse is read from the file specified by
              path.

ERROR FORMAT

       When the parser encounters a problem in the input it will throw an error using the  format
       described here.

       [1]    The message will contain the reason for the problem (unexpected character or end of
              input in input), the character in question, if any, and the  line  and  column  the
              problem was found at, in a human readable form. This part is not documented further
              as its format may change as we see fit. It is intended for human  consumption,  not
              machine.

       [2]    The  error  code  however  will  contain  a  machine-readable representation of the
              problem, in the form of a 5-element list containing, in the order listed below

              [1]    the constant string doctools::tcl::parse

              [2]    the cause of the problem, one of

                     char   Unexpected character in input

                     eof    Unexpected end of the input

              [3]    The location of the problem as offset  from  the  beginning  of  the  input,
                     counted in characters. Note: Line markers count as one character.

              [4]    The line the problem was found on (counted from 1 (one)),

              [5]    The column the problem was found at (counted from 0 (zero))

TREE STRUCTURE

       After successfully parsing a string the generated tree will have the following structure:

       [1]    In  the  following  items the word 'root' refers to the node which was specified as
              the root of the tree when invoking either text or file. This may be the actual root
              of the tree.

       [2]    All  the  following items further ignore the possibility of pre-existing attributes
              in the pre-existing nodes.  If  attributes  exists  with  the  same  names  as  the
              attributes  used by the parser the pre-existing values are written over. Attributes
              with names not clashing with the parser's attributes are not touched.

       [3]    The root node has no attributes.

       [4]    All other nodes have the attributes

              type   The value is a string from the set { Command , Text , Word }

              range  The value is either empty or a 2-element list  containing  integer  numbers.
                     The  numbers  are  the  offsets of the first and last character in the input
                     text, of the token described by the node,.

              line   The value is an integer, it describes  the  line  in  the  input  the  token
                     described by the node ends on. Lines are counted from 1 (one).

              col    The  value  is  an integer, it describes the column in the line in the input
                     the token described by the node ends on. Columns are counted from 0 (zero).

       [5]    The children of the  root,  if  any,  are  of  type  Command  and  Text,  in  semi-
              alternation.  This  means:  After  a  Text  node  a Command node has to follow, and
              anything can follow a Command node, a Text or other Command node.

       [6]    The children of a Command node, if any, are of type Command, and  Text,  and  Word,
              they describe the arguments of the command.

       [7]    The  children  of  a  Word  node,  if  any,  are  of  type  Command, Text, in semi-
              alternation. This means: After a Text node  a  Command  node  has  to  follow,  and
              anything can follow a Command node, a Text or other Command node.

       [8]    A Word node without children represents the empty string.

       [9]    All Text nodes are leaves of the tree.

       [10]   All  leaves  of  the  tree  are either Text or Command nodes.  Word nodes cannot be
              leaves.

BUGS, IDEAS, FEEDBACK

       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other
       problems.    Please   report  such  in  the  category  doctools  of  the  Tcllib  Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be made by going to the Edit form of the ticket immediately after its creation,  and  then
       using the left-most button in the secondary navigation bar.

KEYWORDS

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

CATEGORY

       Documentation tools

COPYRIGHT

       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>