distrib/sources/api/tcl/parse.h

   1 /*      $LAAS: parse.h,v 1.2 2003/07/08 15:47:17 mallet Exp $ */
   2
   3 /*
   4  * Copyright (C) 2001 LAAS/CNRS
   5  * All rights reserved.
   6  *
   7  * The  following  data  structures  and declarations   are for  the  new
   8  * customized  Tcl  parser. They   are almost the    same  as in  the Tcl
   9  * distribution but are duplicated here to prevent  future changes in the
  10  * undocumented part. Furthermore, these structure  did not exist in  Tcl
  11  * 8.0.
  12  *
  13  * Redistribution and use  in source  and binary  forms,  with or without
  14  * modification, are permitted provided that the following conditions are
  15  * met:
  16  *
  17  *   1. Redistributions of  source  code must retain the  above copyright
  18  *      notice, this list of conditions and the following disclaimer.
  19  *   2. Redistributions in binary form must reproduce the above copyright
  20  *      notice,  this list of  conditions and the following disclaimer in
  21  *      the  documentation  and/or  other   materials provided  with  the
  22  *      distribution.
  23  *
  24  * THIS  SOFTWARE IS PROVIDED BY  THE  COPYRIGHT HOLDERS AND CONTRIBUTORS
  25  * "AS IS" AND  ANY  EXPRESS OR IMPLIED  WARRANTIES,  INCLUDING,  BUT NOT
  26  * LIMITED TO, THE IMPLIED WARRANTIES  OF MERCHANTABILITY AND FITNESS FOR
  27  * A PARTICULAR  PURPOSE ARE DISCLAIMED. IN  NO EVENT SHALL THE COPYRIGHT
  28  * HOLDERS OR      CONTRIBUTORS  BE LIABLE FOR   ANY    DIRECT, INDIRECT,
  29  * INCIDENTAL,  SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  30  * BUT NOT LIMITED TO, PROCUREMENT OF  SUBSTITUTE GOODS OR SERVICES; LOSS
  31  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  32  * ON ANY THEORY OF LIABILITY, WHETHER IN  CONTRACT, STRICT LIABILITY, OR
  33  * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
  34  * USE   OF THIS SOFTWARE, EVEN   IF ADVISED OF   THE POSSIBILITY OF SUCH
  35  * DAMAGE.
  36  */
  37 #ifndef H_PARSE
  38 #define H_PARSE
  39
  40 /*
  41  * For each word of a command, and for each piece of a word such as a
  42  * variable reference, one of the following structures is created to
  43  * describe the token.
  44  */
  45
  46 typedef struct ElTclToken {
  47     int type;                   /* Type of token, such as TCL_TOKEN_WORD;
  48                                  * see below for valid types. */
  49     char *start;                /* First character in token. */
  50     int size;                   /* Number of bytes in token. */
  51     int numComponents;          /* If this token is composed of other
  52                                  * tokens, this field tells how many of
  53                                  * them there are (including components of
  54                                  * components, etc.).  The component tokens
  55                                  * immediately follow this one. */
  56 } ElTclToken;
  57
  58 /*
  59  * Type values defined for Tcl_Token structures.  These values are
  60  * defined as mask bits so that it's easy to check for collections of
  61  * types.
  62  *
  63  * ELTCL_TOKEN_WORD -           The token describes one word of a command,
  64  *                              from the first non-blank character of
  65  *                              the word (which may be " or {) up to but
  66  *                              not including the space, semicolon, or
  67  *                              bracket that terminates the word.
  68  *                              NumComponents counts the total number of
  69  *                              sub-tokens that make up the word.  This
  70  *                              includes, for example, sub-tokens of
  71  *                              TCL_TOKEN_VARIABLE tokens.
  72  * ELTCL_TOKEN_SIMPLE_WORD -    This token is just like TCL_TOKEN_WORD
  73  *                              except that the word is guaranteed to
  74  *                              consist of a single TCL_TOKEN_TEXT
  75  *                              sub-token.
  76  * ELTCL_TOKEN_TEXT -           The token describes a range of literal
  77  *                              text that is part of a word.
  78  *                              NumComponents is always 0.
  79  * ELTCL_TOKEN_BS -             The token describes a backslash sequence
  80  *                              that must be collapsed.  NumComponents
  81  *                              is always 0.
  82  * ELTCL_TOKEN_COMMAND -        The token describes a command whose result
  83  *                              must be substituted into the word.  The
  84  *                              token includes the enclosing brackets.
  85  *                              NumComponents is always 0.
  86  * ELTCL_TOKEN_VARIABLE -       The token describes a variable
  87  *                              substitution, including the dollar sign,
  88  *                              variable name, and array index (if there
  89  *                              is one) up through the right
  90  *                              parentheses.  NumComponents tells how
  91  *                              many additional tokens follow to
  92  *                              represent the variable name.  The first
  93  *                              token will be a TCL_TOKEN_TEXT token
  94  *                              that describes the variable name.  If
  95  *                              the variable is an array reference then
  96  *                              there will be one or more additional
  97  *                              tokens, of type TCL_TOKEN_TEXT,
  98  *                              TCL_TOKEN_BS, TCL_TOKEN_COMMAND, and
  99  *                              TCL_TOKEN_VARIABLE, that describe the
 100  *                              array index; numComponents counts the
 101  *                              total number of nested tokens that make
 102  *                              up the variable reference, including
 103  *                              sub-tokens of TCL_TOKEN_VARIABLE tokens.
 104  * ELTCL_TOKEN_SUB_EXPR -       The token describes one subexpression of a
 105  *                              expression, from the first non-blank
 106  *                              character of the subexpression up to but not
 107  *                              including the space, brace, or bracket
 108  *                              that terminates the subexpression.
 109  *                              NumComponents counts the total number of
 110  *                              following subtokens that make up the
 111  *                              subexpression; this includes all subtokens
 112  *                              for any nested TCL_TOKEN_SUB_EXPR tokens.
 113  *                              For example, a numeric value used as a
 114  *                              primitive operand is described by a
 115  *                              TCL_TOKEN_SUB_EXPR token followed by a
 116  *                              TCL_TOKEN_TEXT token. A binary subexpression
 117  *                              is described by a TCL_TOKEN_SUB_EXPR token
 118  *                              followed by the TCL_TOKEN_OPERATOR token
 119  *                              for the operator, then TCL_TOKEN_SUB_EXPR
 120  *                              tokens for the left then the right operands.
 121  * ELTCL_TOKEN_OPERATOR -       The token describes one expression operator.
 122  *                              An operator might be the name of a math
 123  *                              function such as "abs". A TCL_TOKEN_OPERATOR
 124  *                              token is always preceeded by one
 125  *                              TCL_TOKEN_SUB_EXPR token for the operator's
 126  *                              subexpression, and is followed by zero or
 127  *                              more TCL_TOKEN_SUB_EXPR tokens for the
 128  *                              operator's operands. NumComponents is
 129  *                              always 0.
 130  */
 131
 132 #define ELTCL_TOKEN_WORD        1
 133 #define ELTCL_TOKEN_SIMPLE_WORD 2
 134 #define ELTCL_TOKEN_TEXT        4
 135 #define ELTCL_TOKEN_BS          8
 136 #define ELTCL_TOKEN_COMMAND     16
 137 #define ELTCL_TOKEN_VARIABLE    32
 138 #define ELTCL_TOKEN_SUB_EXPR    64
 139 #define ELTCL_TOKEN_OPERATOR    128
 140
 141 /*
 142  * Parsing error types.  On any parsing error, one of these values
 143  * will be stored in the error field of the Tcl_Parse structure
 144  * defined below.
 145  */
 146
 147 #define ELTCL_PARSE_SUCCESS             0
 148 #define ELTCL_PARSE_QUOTE_EXTRA         1
 149 #define ELTCL_PARSE_BRACE_EXTRA         2
 150 #define ELTCL_PARSE_MISSING_BRACE       3
 151 #define ELTCL_PARSE_MISSING_BRACKET     4
 152 #define ELTCL_PARSE_MISSING_PAREN       5
 153 #define ELTCL_PARSE_MISSING_QUOTE       6
 154 #define ELTCL_PARSE_MISSING_VAR_BRACE   7
 155 #define ELTCL_PARSE_SYNTAX              8
 156 #define ELTCL_PARSE_BAD_NUMBER          9
 157
 158 /*
 159  * A structure of the following type is filled in by Tcl_ParseCommand.
 160  * It describes a single command parsed from an input string.
 161  */
 162
 163 #define ELPARSE_NUM_STATIC_TOKENS 20
 164
 165 typedef struct ElTclParse {
 166     char *commentStart;         /* Pointer to # that begins the first of
 167                                  * one or more comments preceding the
 168                                  * command. */
 169     int commentSize;            /* Number of bytes in comments (up through
 170                                  * newline character that terminates the
 171                                  * last comment).  If there were no
 172                                  * comments, this field is 0. */
 173     char *commandStart;         /* First character in first word of command. */
 174     int commandSize;            /* Number of bytes in command, including
 175                                  * first character of first word, up
 176                                  * through the terminating newline,
 177                                  * close bracket, or semicolon. */
 178     int numWords;               /* Total number of words in command.  May
 179                                  * be 0. */
 180     ElTclToken *tokenPtr;       /* Pointer to first token representing
 181                                  * the words of the command.  Initially
 182                                  * points to staticTokens, but may change
 183                                  * to point to malloc-ed space if command
 184                                  * exceeds space in staticTokens. */
 185     int numTokens;              /* Total number of tokens in command. */
 186     int tokensAvailable;        /* Total number of tokens available at
 187                                  * *tokenPtr. */
 188     int errorType;              /* One of the parsing error types defined
 189                                  * above. */
 190
 191     /*
 192      * The fields below are intended only for the private use of the
 193      * parser.  They should not be used by procedures that invoke
 194      * Tcl_ParseCommand.
 195      */
 196
 197     char *string;               /* The original command string passed to
 198                                  * Tcl_ParseCommand. */
 199     char *end;                  /* Points to the character just after the
 200                                  * last one in the command string. */
 201     char *term;                 /* Points to character in string that
 202                                  * terminated most recent token.  Filled in
 203                                  * by ParseTokens.  If an error occurs,
 204                                  * points to beginning of region where the
 205                                  * error occurred (e.g. the open brace if
 206                                  * the close brace is missing). */
 207     int incomplete;             /* This field is set to 1 by Tcl_ParseCommand
 208                                  * if the command appears to be incomplete.
 209                                  * This information is used by
 210                                  * Tcl_CommandComplete. */
 211     ElTclToken staticTokens[ELPARSE_NUM_STATIC_TOKENS];
 212                                 /* Initial space for tokens for command.
 213                                  * This space should be large enough to
 214                                  * accommodate most commands; dynamic
 215                                  * space is allocated for very large
 216                                  * commands that don't fit here. */
 217 } ElTclParse;
 218
 219 #endif /* H_PARSE */