OS/2 Shareware BBS: 10 Tools/10-Tools.zip/ssvpar.zip/SSPARSE.HLP

OS/2 Help File | 1994-11-30 | 168KB | 7,859 lines

ΓòÉΓòÉΓòÉ 1. Visual Parse++ Programmer's Guide ΓòÉΓòÉΓòÉ

Welcome to the Visual Parse++ development system from SandStone Technology Inc.
Using this system, you can develop state-of-the-art lexical analyzers and
parsers in a fraction of the time it takes with other tools.

The languages accepted by Visual Parse++ are the LALR(1) languages.  Visual
Parse++ supports all the constructs found in other lex and yacc tools plus some
powerful additions.  These include:

   o A unique and sophisticated graphical debugging environment to test your
     language specification.

   o Unicode and DBCS support.  All character sets are supported.

   o The lexical analysis section(s) support multiple regular expression lists
     which you can 'push' and 'pop' when tokens are recognized. This makes it
     very easy to perform some context dependent processing in the lexical
     analysis phase which can greatly simplify the LALR(1) grammar.

   o The grammar specification supports a sophisticated error recovery
     technique, called synchronization tokens, that provides reliable and
     powerful error recovery.  This is in addition to an advanced form of
     'error' tokens found in other tools.

   o The lexical analyzer has the ability to recognize but ignore tokens
     without any extra coding on your part.  This is very useful for weeding
     out things like comments and white space.  The comment or white space
     (say) is recognized, but not passed to the parser.

   o Complete seperation of the language specification from the application
     code.  Visual Parse++ generates tables and language bindings that you use
     to write your application.  You can develop and test your lexical analyzer
     and/or parser without any coding (other than the rule file).

 There are 3 steps you must perform to develop a lexical analyzer and/or
 parser.

  1. Write a rule file describing your language. Rule files are discussed in
     Rule Files

  2. Use the graphical debugger to test your rule file.  The graphical debugger
     is described in the Visual Parse++ User's Guide.

  3. Generate the tables and language bindings and write your application. See
     Language Bindings and Commands for more information.


ΓòÉΓòÉΓòÉ 2. Rule Files ΓòÉΓòÉΓòÉ

 Description
 Conventions
 %macro
 %expression
 Regular Expressions
 %prec
 %production
 Error Recovery
 Ambiguities
 Reserved Symbols


ΓòÉΓòÉΓòÉ 2.1. Description ΓòÉΓòÉΓòÉ

Rule files supply the specification for the language you are developing. The
languages accepted by Visual Parse++ are the LALR(1) languages.  Rule files
have a simple and clean syntax, simplifying language design.

There are 4 sections to a rule file.

   %macro         Define any macros used in %expression sections. See %macro
                  for more information.

   %expression    1 or more named regular expression lists. See %expression for
                  more information.

   %prec          Precedence information used to resolve shift/reduce
                  conflicts. See %prec for more information.

   %production    Used to define the LALR(1) grammar. See %production for more
                  information.

 The sections must be specified in the order indicated.  An example follows.

      %macro
        ┬╖
        ┬╖
      %expression exprList1
        ┬╖
        ┬╖
      %expression exprList2
        ┬╖
        ┬╖
      %prec
        ┬╖
        ┬╖
      %production
        ┬╖
        ┬╖


ΓòÉΓòÉΓòÉ 2.2. Conventions ΓòÉΓòÉΓòÉ

The rule file description that follows obey the following conventions.

   o Keywords and reserved symbols are bold.

   o Optional parameters are enclosed in braces [].

   o A name matches the regular expression [a-z_A-Z][a-z_A-Z0-9]*.

   o Tokens must be seperated by white space.  White space matches [ \t\n,]+.

   o Regular expressions can be composed of any string of characters.

   o Regular expressions and alias names must be enclosed in single quotes if
     they contain a character in the set [ \t\n/,;].

   o All regular expressions and alias names should be enclosed in single
     quotes (') to avoid confusion and enhance readability.

   o Inside a quoted regular expression or alias, two consecutive quotes ('')
     represent a single quote.

   o Parameters with multiple alternatives are lined up vertically with each
     alternative on a different line.

   o C++ style comments are supported.  Everything after a '//' is ignored to
     end of line as well as anything enclosed in '/* ... */'.


ΓòÉΓòÉΓòÉ 2.3. %macro ΓòÉΓòÉΓòÉ

The %macro section is used to define any macros used in subsequent %expression
sections. This section is optional. The syntax of each line is:

      {name}  regExpr;

 The braces are required on macro names. Regular expressions are described in
 Regular Expressions. An example is:

      %macro

      {name}   '[a-z_A-Z][a-z_A-Z0-9]*';
      {number} '[0-9]+';


ΓòÉΓòÉΓòÉ 2.4. %expression ΓòÉΓòÉΓòÉ

Each %expression section defines a regular expression list.  Each list is
named.  The syntax is:

      %expression name

 %expression names have their own name space, e.g.,  an %expression name can be
 the same as a regular expression name or a production label.

 Visual Parse++ maintains a stack of %expression lists that you can %push,
 %goto, and %pop. The %push and %goto operators make the regular expression
 list the active lexical analyzer.  You can easily do a great deal of context
 dependent processing in the lexical analysis phase to simplify your grammar.

 Each line in an %expression section has syntax:

      regExpr name    [ alias ] [ %push name ] ;
              %ignore          [ %goto name ]
                                [ %pop       ]

   regExpr        A regular expression.  Regular expressions are described in
                  Regular Expressions

   name           Either a valid name or the reserved word %ignore. %ignore
                  tells the lexical analyzer to recognize the token, but not to
                  pass it to the parser. The name (or %ignore) is required. The
                  name is used to generate symbols used in your application
                  code to identify this regular expression.

   alias          An alias that can be used in the %production section to aid
                  readability. An alias can be anything that would constitute a
                  valid regular expression, though they are not interpreted as
                  regular expressions. For example, '+' is a valid alias, but
                  not a valid name. The alias is not required. It is a good
                  idea to enclose all alias names in single quotes.  This will
                  make it easier to distinguish terminals from nonterminals in
                  the %production section.

   %push name     Push the %expression list with name.

   %pop           Pop the most recent %expression list.  Whatever is on top of
                  the expression list stack is now active.

   %goto name     Goto the %expression list with name.  %goto  is equivalent to
                  a %pop followed by a %push.

 If two regular expressions recognize the same language, the ambiguity is
 resolved in favor of the one that occurs later in the specification.

 An example illustrating some of the features is:

      %expression Main
       '\/\*'                     %ignore, %push MultiLineComment;
       '\/\/'                     %ignore, %push SingleLineComment;
       '[ \t\n]+'                 %ignore;
       '[a-z_A-Z][a-z_A-Z0-9]*'   Name;
       '[0-9]+'                   Number;
       'keyword'                  Keyword;


      %expression MultiLineComment
       '.'                        %ignore;
       '\n'                       %ignore;
       '\*\/'                     %ignore, %pop;

      %expression SingleLineComment
       '.'                        %ignore;
       '\n'                       %ignore, %pop;

 This example will recognize C++ like comments, names, numbers, and the
 reserved word 'keyword' seperated by whitespace.  The comments and whitespace
 are recognized but %ignored. The backslashes (\) in the regular expressions
 are required because '*' and '/' are meta-characters with special meaning in a
 regular expression.  The '\' turns off the special meaning.

 The example also illustrates ambiguity resolution.  The string 'keyword' is
 recognized as a Name as well as a Keyword.  The Keyword occurs later in the
 list and the ambiguity is resolved in it's favor.


ΓòÉΓòÉΓòÉ 2.4.1. Regular Expressions ΓòÉΓòÉΓòÉ

Regular expressions are composed of normal characters and meta-characters which
have special meaning.  If the regular expression contains [ ;/,\t\n], it must
be enclosed in single quotes (').  Single quotes must also be used to recognize
a reserved symbol (%macro, %expression, ...). Two consecutive quotes ('')
represent a single quote in a quoted regular expression.  You should enclose
all regular expressions in single quotes to avoid confusion.  The
meta-characters are:

   .              Matches any single character except '\n'.

   [...]          Matches any character enclosed in the braces.  A range of
                  characters is indicated with a '-' (0-9, a-z, etc.).  If the
                  first character is a '^' the meaning is to match any
                  character not in the set.

   *              Matches 0 or more of the preceding regular expression.

   +              Matches 1 or more of the preceding regular expressions.

   ()             Groups a series of regular expressions.

   ^              As the first character in a regular expression, matches the
                  beginning of a line.  The regular expression will not be
                  recognized unless it is anchored at the beginning of a line.

   $              As the last character in a regular expression, matches the
                  end of a line. The regular expression will not be recognized
                  unless it is immediately followed by a '\n'.

   "..."          Literal match.  Turns off recognition of all meta-characters,
                  except the '\' sequences.

   |              The 'or' operator. An infix operator that will match either
                  the left part 'or' the right part.

   ?              Matches 0 or 1 occurences of the preceding regular
                  expression.

   {m,n}          A postfix operator matching between m and n occurences of the
                  preceding regular expression.

   {name}         Substitutes macro 'name' in the regular expression.

   \              The meaning depends on what follows.  The following letters
                  have special meaning.

      a                     BEL

      b                     backspace

      f                     formfeed

      n                     new line

      r                     carriage return

      t                     tab

      v                     vertical tab

      d[0-9]+               decimal number

      o[0-7]+               octal number

      x[0-9a-fA-F]+         hex number

      Any other character   The value of the character.


ΓòÉΓòÉΓòÉ 2.5. %prec ΓòÉΓòÉΓòÉ

The precedence section is used to resolve any shift/reduce conflicts in the
subsequent grammar.  Conflicts are discussed in Ambiguities. The %prec section
assigns precedence and associativity information to tokens (terminal symbols).

By default tokens have precedence 0 and are %left associative. Each line has
syntax:

number expr %left     ;
            %right
            %nonassoc

   number         The precedence, which must be a number. The number supplied
                  is incremented by 1 internally, reserving precedence number
                  0.

   expr           The name or alias of a previously defined regular expression.
                  This parameter is required.

   %left          The token is left associative.

   %right         The token is right associative.

   %nonassoc      The token is non associative.


ΓòÉΓòÉΓòÉ 2.6. %production ΓòÉΓòÉΓòÉ

The %production section defines the grammar. The %production statement syntax
is:

      %production startSymbol

 The start symbol must be a nonterminal.

 Grammars are made of production rules.  Each rule has the form:

      label leftside -> [ symbol [ symbol ] ...] [ %prec expr ] ;

   label          A production label. This is used in the language bindings to
                  identify the production. Labels have their own name space.
                  In other words, a label name can be the same as a terminal or
                  nonterminal name.

   leftside       The left side symbol.  It must be a nonterminal.

   ->             The production separator.

   symbol         Symbols are one of the following:

       1. A name or alias of an entry in an %expression  list.  These are the
          terminal symbols.

       2. The synchronization token %.  Synchronization tokens are discussed in
          Error Recovery.

       3. The %error token.  Error tokens are discussed in Error Recovery.

       4. A nonterminal symbol.  If it isn't one of the above, it is a
          nonterminal.

   %prec expr     The optional precedence of the production.  A production has
                  the same precedence as the right most terminal symbol in the
                  production unless overridden by this parameter.  'expr' is
                  either a name or alias  of an entry defined in the %prec
                  section. If the production has no terminal symbol and no
                  %prec parameter, the precedence is 0. The precedence is used
                  to resolve any shift/reduce conflicts in the grammar.
                  Conflicts are discussed in Ambiguities.


ΓòÉΓòÉΓòÉ 3. Error Recovery ΓòÉΓòÉΓòÉ

Visual Parse++ contains an advanced form of error recovery called
synchronization tokens in addition to an enhanced type of error tokens. When
Visual Parse++ detects a syntax error, it executes the following procedure:

  1. It searches the stack (the current context) for all tokens that can follow
     either a synchronization token '%', or an %error token.  This is the valid
     token set.  Typical recovery schemes look for only the most recent error
     token, not all error tokens (synchronization tokens don't exist in other
     recovery schemes).

  2. It skips tokens in the input stream until it finds a token matching one in
     the valid token set.

  3. If a token is found,  it pops states off the stack to make the matched
     token valid.  Parsing continues from this point.

 There are several advantages to this scheme over other common error recovery
 procedures.

  1. Synchronization tokens do not add any productions to the grammar.  You add
     the tokens (%) at points in the grammar that recovery will likely succeed.

  2. The entire stack (current context) is searched for tokens when making the
     valid set.

  3. Because of this, a minimum number of tokens are discarded before parsing
     proceeds.

 A good example to use to illustrate error recovery is the rule file grammar
 itself.  The start production looks like:

      Start -> MacroSection ExpressionSection PrecSection ProdSection;

 Each section begins with a unique keyword.  At a minimum, we would like to
 recover at the next section, e.g., if there is an error in the %prec section,
 we would like parsing to proceed when it hits a %production token. To
 accomplish this we add the following synchronization tokens to the production:

      Start -> MacroSection % ExpressionSection % PrecSection % ProdSection;

 This is the highest level of recovery we need, but since each statement in any
 section ends in a ';', we should be able to enhance the error recovery to
 handle this common case.  We need to use an %error token in this case, not a
 synchronization token.  Let me illustrate.

 This is what an entry in an %expression list entry looks like:

      Expr -> ExprReg ExprAlias ExprAction ';';

 If we want parsing to proceed at the ';' token we need to add the following
 production to the grammar:

      Expr -> %error ';';

 But why couldn't we do this ?

      Expr -> ExprReg ExprAlias ExprAction % ';';

 This says to recover on a ';' symbol as well, but only when the parser has the
 entire context to the left of the % on the stack. In other words this will
 recover on a ; after the parser has shifted an ExprReg, an ExprAlias, and an
 ExprAction onto the stack.  The production with the %error token is not so
 picky, we merely have to be expecting an Expr for the recovery to operate
 properly.

 The diferences between synchronization tokens (%) and %error tokens are:

   o Error tokens add productions to the grammar.  These productions will never
     be reduced unless an error occurs.

   o Synchronization tokens can be added to existing productions at any point
     in the development process without changing the language in any way.


ΓòÉΓòÉΓòÉ 4. Ambiguities ΓòÉΓòÉΓòÉ

LALR(1) grammars can generate 2 types of conflicts, shift/reduce and
reduce/reduce conflicts.

Reduce/reduce conflicts are always resolved in favor of the production that
occurs later in the grammar.

Shift/reduce conflicts are handled using the %prec information included in the
rule file.

The precedence of the shift token is compared to the precedence of the
production.  As mentioned above, productions have the same precedence as the
rightmost terminal symbol in the production unless overridden by the %prec
parameter.  Productions have precedence 0 if they don't contain a terminal
symbol or %prec parameter. Tokens have precedence 0 by default also.  The
following rules resolve the conflict:

  1. If the production or token have precedence 0, the shift is taken.

  2. If the token precedence is greater than the production precedence, use the
     shift.

  3. If the production precedence is greater than the token precedence, use the
     reduce.

  4. If the precedences are equal, and the token is %left associative, use the
     reduce.

  5. If the precedences are equal, and the token is not %left associative, use
     the shift.

 A common example is an arithmetic expression grammar such as the following.

      %expression Main

      '[ \n\t]+'       %ignore;
      '\+'             Plus, '+';
      '\-'             Minus, '-';
      '\/'             Div, '/';
      '\*'             Mult, '*';
      '\*\*'           Power, '**';
      '\('             OParen, '(';
      '\)'             CParen, ')';
      '[0-9]+'         Number, 'n';

      %prec

      1, '+',  %left;
      1, '-',  %left;
      2, '*',  %left;
      2, '/',  %left;
      3, '**', %right;

      %production Expr

      ExprPlus   Expr   -> Expr '+'  Expr;
      ExprMinus  Expr   -> Expr '-'  Expr;
      ExprMult   Expr   -> Expr '*'  Expr;
      ExprPower  Expr   -> Expr '**' Expr;
      ExprNested Expr   -> '(' Expr ')';
      ExprNumber Expr   -> 'n';

 Without the %prec section, this grammar would generate numerous shift/reduce
 conflicts.


ΓòÉΓòÉΓòÉ 5. Reserved Symbols ΓòÉΓòÉΓòÉ

The following symbols are reserved in the rule file specification and should
not be used outside of their intended scope.  If they need to be recognized in
a regular expression, use single quotes (').  Regular expressions should always
be enclosed in single quotes.  Symbols starting with a % are reserved for
expansion.

   ;
   ->
   %
   %error
   %expression
   %goto
   %left
   %macro
   %nonassoc
   %pop
   %prec
   %production
   %push
   %right


ΓòÉΓòÉΓòÉ 6. Language Bindings ΓòÉΓòÉΓòÉ

 Concepts
 C++


ΓòÉΓòÉΓòÉ 6.1. Concepts ΓòÉΓòÉΓòÉ

After you have designed and tested your lexical analyzer and parser, Visual
Parse++ will generate the language bindings you need to develop your
application.

There are 2 files that are common to all language bindings.

  1. The lexical analyzer.  By default, this has the same name as the rule file
     with extension '.dfa'.

  2. The parser.  By default, this has the same name as the rule file with
     extension '.llr'.

 These files, sometimes referred to as tables, contain the information needed
 to control the lexing and parsing process.  The language bindings access these
 tables, regardless of the language used to implement your application.


ΓòÉΓòÉΓòÉ 6.2. C++ ΓòÉΓòÉΓòÉ

 Concepts
 SSLex
 SSLexTable
 SSLexLexeme
 SSLexExpressionList
 SSLexConsumer
 SSLexFileConsumer
 SSLexStringConsumer
 SSYacc
 SSYaccTable
 SSYaccStackElement
 SSException
 Reference Counting
 SSRef
 SSRefCount


ΓòÉΓòÉΓòÉ 6.2.1. Concepts ΓòÉΓòÉΓòÉ

The C++ classes provide a comprehensive set of classes to handle all of your
lexing and parsing needs.  In the large majority of cases, the only classes you
will need to be aware of are SSLex and SSYacc.  The only coding you will need
to perform in most cases is in the SSYacc::reduce member function generated by
Visual Parse++.  This is what a typical application looks like:

SSLex  zLex( "file.name", "table.dfa");
SSYacc zYacc( zLex, "table.llr");
zYacc.parse();
  ┬╖
  ┬╖
SSYaccStackElement* MyYaccClass::reduce( SSUnsigned32 qProd,
   SSUnsigned32 qSize);
   {
   switch( qProd)
     {
     case MyYaccProduction0:
     // Prod -> ...

     case MyYaccProduction1:
     // Prod -> ...

     case MyYaccProduction2:
     // Prod -> ...

     ┬╖
     ┬╖
     ┬╖
     default:
        break;
     }
   return stackElement();
   }

A complete set of classes is provided for applications requiring greater
control of the lexing and parsing process.


ΓòÉΓòÉΓòÉ 6.2.2. SSLex ΓòÉΓòÉΓòÉ

 Concepts
 Constructors
 complete
 error
 gotoExpressionList
 isCurrentExpressionList
 operator++
 popExpressionList
 pushExpressionList
 reset
 setTable
 setConsumer
 tokenToConstChar


ΓòÉΓòÉΓòÉ 6.2.2.1. Concepts ΓòÉΓòÉΓòÉ

The SSLex class is used to access the lexical analyzer. Visual Parse++
generates a subclass of this class in the '.yh' file.

A lexer needs two pieces of data to function, a table and a consumer.  Each of
these is represented by a class in sslex.hpp.

The table is the '.dfa' file generated by Visual Parse++.  The associated class
is SSLexTable. This controls the lexer.

The consumer represents the data to be lexed.  Supplied consumer classes
include a string consumer, SSLexStringConsumer and a file consumer,
SSLexFileConsumer.  There is a base class called SSLexConsumer that you can use
to construct your own specialized consumer if the need arises.

See SSLexTable and SSLexConsumer for more information.

The main virtual functions of interest to the programmer are complete and
error.

The complete virtual function is called each time a token is recognized.  The
complete function returns a SSLexLexeme*.  The default function simply
allocates an SSLexLexeme and passes it back.  It is then passed to the parser.
By overriding this function, you can construct your own SSLexLexeme (or perhaps
something derived from one), and perform any special processing.

The error virtual function is called whenever an invalid lexeme is detected.
The default function throws an SSException.


ΓòÉΓòÉΓòÉ 6.2.2.2. Constructors ΓòÉΓòÉΓòÉ

Signature

SSLex::SSLex( const char* = 0);
SSLex::SSLex( const char*, const char*);
SSLex::SSLex( SSLexConsumer&, SSLexTable&);

You can construct a SSLex class in one of the following ways:

  1. With a const char* representing the file name to consume.  In this case
     you must supply the table with the setTable member function ( and the
     consumer with setConsumer if the default is used).

  2. With a const char* representing the file name to consume and a const char*
     representing the table name.

  3. With a previously constructed SSLexConsumer and SSLexTable.

 Example

  SSLexTable        zTable( "table.dfa");
  SSLexFileConaumer zConsumer( "file.name");

  SSLex             zLex;
                    zLex.setTable( zTable);
                    zLex.setConsumer( zConsumer);

  SSLex             zLex( "file.name", "table.dfa");

  SSLex             zLex( zConsumer, zTable);


ΓòÉΓòÉΓòÉ 6.2.2.3. complete ΓòÉΓòÉΓòÉ

The complete virtual function is called each time a token is recognized. The
default complete function allocates an SSLexLexeme and returns.

Warning: You must issue the SSLexConsumer::flushLexeme to flush the current
lexeme, if you don't use lexemeToMark to allocate the lexeme.

Signature

virtual SSLexLexeme* SSLex::complete(
   SSLexConsumer&, SSUnsigned32, SSLexMark&);

 Parameters          Meaning

 SSLexConsumer&      A reference to the consumer.  There are various ways to
                     construct an SSLexLexeme from an SSLexConsumer.  See
                     SSLexConsumer for more information.

 SSUnsigned32        The token id associated with the recognized lexeme.
                     Typically, this parameter is passed to an SSLexConsumer
                     function to construct the SSLexLexeme.

 SSLexMark&          A reference to a class that contains information that an
                     SSLexConsumer function uses to construct the SSLexLexeme.

 Returns

 A pointer to an SSLexLexeme or 0. If 0 is returned, the lexeme is ignored and
 lexing continues.

 Example

 This is the default complete virtual function:

  SSLexLexeme* SSLex::complete( SSLexConsumer& qConsumer
     SSUnsigned32 qulToken, SSLexMark& qMark)
     {
     return qConsumer.lexemeToMark( qMark, qulToken);
     }


ΓòÉΓòÉΓòÉ 6.2.2.4. error ΓòÉΓòÉΓòÉ

The error virtual function is called when an invalid lexeme is detected. The
default error function throws an SSException.

Signature

virtual SSLexLexeme* SSLex::error( SSLexConsumer&);

 Parameters          Meaning

 SSLexConsumer&      A reference to an SSLexConsumer instance. You can get
                     information about the lexeme using SSLexConsumer member
                     functions.

 Returns

 An SSLexLexeme instance or 0.  Zero causes the lexeme to be ignored. If an
 SSLexLexeme instance is returned, it is processed as though it were a normal
 lexeme.

 Example

 This is the default error virtual function:

  SSLexLexeme* SSLex::error( SSLexConsumer& qConsumer)
     {
     SSLexLexeme* zpLexeme = qConsumer.lexemeToCurrent();
     throwException( SSExceptionLexError, SSLexMsgError, zpLexeme->.line(),
        zpLexeme->offset(), zpLexeme->asConstChar());
     return SSFalse;
     }


ΓòÉΓòÉΓòÉ 6.2.2.5. gotoExpressionList ΓòÉΓòÉΓòÉ

The gotoExpressionList function pops and then pushes an %expression list on the
expression list stack, making it active.  It performs the exact same function
as %goto does in a rule file.  See %expression for more information on %goto
and SSLexTable for more information on accessing expression lists.

Signature

SSBooleanValue SSLex::gotoExpressionList( SSLexExpressionList&);

 Parameters                    Meaning

 SSLexExpressionList&          The expression list to goto.  You obtain
                               references to SSLexExpressionLists from
                               SSLexTable

 Returns

 Throws an SSException if the expression list stack is empty or full.

 Example

  #define ALexExpressionListMain 0 /* Generated in header file '.yh' */

  SSLexTable           zTable( "table.dfa");
  SSLexFileConsumer    zConsumer( "file.name");
  SSLex                zLex( zConsumer, zTable);
  SSLexExpressionList& zExpressionList( zTable.expressionList( ALexExpressionListMain));

  zLex.gotoExpressionList( zExpressionList);


ΓòÉΓòÉΓòÉ 6.2.2.6. isCurrentExpressionList ΓòÉΓòÉΓòÉ

The isCurrentExpressionList function queries the the top of the expression list
stack,  using the passed expression list identifier as a parameter. An
expression list is equivalent to an %expression list in a rule file.  The '.yh'
header file contains #define statements for each %expression list name.  This
function provides the ability to determine the expression list currently in
control.

Signature

SSBooleanValue SSLex::isCurrentExpressionList( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        An expression list identifier number.

 Returns

 An SSBooleanValue. An SSException is thrown if an invalid expression list
 identifier is passed.

 Example

  #define ALexExpressionListMain 0 /* Generated in header file '.yh' */

  SSLex          zLex( "file.name", "table.dfa");
  SSBooleanValue zBool = zLex.isCurrentExpressionList( ALexExpressionListMain);

  if ( zBool)
     {
     /* Expression list ALexExpressionListMain is current */
     }


ΓòÉΓòÉΓòÉ 6.2.2.7. operator++ ΓòÉΓòÉΓòÉ

The operator++ function gets the next lexeme. SSYacc uses this function to
fetch lexemes from the input data.  This is the function to use to lex your
data if you need to access a lexical analyzer independent of a parser.

Note: This is the postfix operator++.

Signature

SSLexLexeme* SSLex::operator++( int);

Returns

An SSLexLexeme*. 0 indicates end of data.

Example

SSLexLexeme* zpLexeme;
SSLex        zLex( "file.name", "table.dfa");

while ( zpLexeme = zLex++)
   {
   /* Process lexeme */
   }


ΓòÉΓòÉΓòÉ 6.2.2.8. popExpressionList ΓòÉΓòÉΓòÉ

The popExpressionList function pops the top %expression list off the expression
list stack.  It performs the exact same function as %pop does in a rule file.
See %expression for more information on %pop and SSLexTable for more
information on accessing expression lists.

Signature

SSBooleanValue SSLex::popExpressionList( void);

Returns

Throws an SSException if the expression list stack is empty.

Example

SSLex zLex( "file.name", "table.dfa");
zLex.popExpressionList();


ΓòÉΓòÉΓòÉ 6.2.2.9. pushExpressionList ΓòÉΓòÉΓòÉ

The pushExpressionList function pushes an %expression list on the expression
list stack, making it active.  It performs the exact same function as %push
does in a rule file.  See %expression for more information on %push and
SSLexTable for more information on accessing expression lists.

Signature

SSBooleanValue SSLex::pushExpressionList( SSLexExpressionList&);

 Parameters                    Meaning

 SSLexExpressionList&          The expression list to push.  You obtain
                               references to SSLexExpressionLists from
                               SSLexTable

 Returns

 Throws an SSException if the expression list stack is full.

 Example

  #define ALexExpressionListMain 0 /* Generated in header file '.yh' */

  SSLexTable           zTable( "table.dfa");
  SSLexFileConsumer    zConsumer( "file.name");
  SSLex                zLex( zConsumer, zTable);
  SSLexExpressionList& zExpressionList( zTable.expressionList( ALexExpressionListMain));

  zLex.pushExpressionList( zExpressionList);


ΓòÉΓòÉΓòÉ 6.2.2.10. reset ΓòÉΓòÉΓòÉ

The reset resets the lexer to its initial state.

Signature

void SSLex::reset( void);

Example

zLex.reset();


ΓòÉΓòÉΓòÉ 6.2.2.11. setTable ΓòÉΓòÉΓòÉ

The setTable function sets the active table for the lexer.

Signature

SSBooleanValue SSLex::setTable( const char*);
SSBooleanValue SSLex::setTable( SSLexTable&);

 Parameters          Meaning

 const char*         A table name.

 SSLexTable&         A previously constructed SSLexTable.

 Returns

 Throws an SSException if an error occurs.

 Example

  SSLex      zLex;
  SSLexTable zTable( "table.dfa");

  zLex.setTable( "table.dfa");
  zLex.setTable( zTable);


ΓòÉΓòÉΓòÉ 6.2.2.12. setConsumer ΓòÉΓòÉΓòÉ

The setConsumer function sets the active consumer for the lexer.

Signature

SSBooleanValue SSLex::setConsumer( const char*);
SSBooleanValue SSLex::setConsumer( SSLexConsumer&);

 Parameters          Meaning

 const char*         A file name.

 SSLexConsumer&      A reference to a previously constructed SSLexConsumer.

 Returns

 Throws an SSException if an error occurs.

 Example

  SSLex             zLex;
  SSLexFileConsumer zConsumer( "file.name");

  zLex.setConsumer( "file.name");
  zLex.setConsumer( zConsumer);


ΓòÉΓòÉΓòÉ 6.2.2.13. tokenToConstChar ΓòÉΓòÉΓòÉ

The tokenToConstChar function takes a token number and returns a string
representing the token.  The string is either the name or alias of an entry in
an %expression list.  The alias overrides the name if it is present. See
%expression for more information.

This function is genertated in the '.yh' header file for each lexer. It's main
purpose is to format an error message.  SSYacc has a function which returns a
list of valid tokens given a state (validLookaheads).  When an error occurs you
can find the valid lookaheads and use this function to format a concise error
message. See SSYacc for more information.

Signature

const char* SSLex::tokenToConstChar( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The token number.

 Returns

 The string representing the token.  The string "SSLexTokenNotFound" is
 returned if an invalid token is passed.

 Example

  SSLex         zLex( "file.name", "table.dfa");
  SSYacc        zYacc( zLex, "table.llr");
  SSUnsigned32  zulCount;
  SSUnsigned32* zpTokens = validLookaheads( zulState, zulCount);

  string zMsg( "Expected ");
  zMsg.concatenate( zLex.tokenToConstChar( zpTokens[ 0]));
  for ( int i = 1; i < zulCount; i++)
      {
      zMsg.concatenate( ", ");
      zMsg.concatenate( zLex.tokenToConstChar( zpTokens[ i]));
      }


ΓòÉΓòÉΓòÉ 6.2.3. SSLexTable ΓòÉΓòÉΓòÉ

 Concepts
 Constructors
 expressionList


ΓòÉΓòÉΓòÉ 6.2.3.1. Concepts ΓòÉΓòÉΓòÉ

The SSLexTable class represents lex tables ('.dfa' files).

Tables can be shared.  The main use of SSLexTable is to define static
definitions of frequently used tables so the file will only be read once, when
the SSLexTable table is constructed.


ΓòÉΓòÉΓòÉ 6.2.3.2. Constructors ΓòÉΓòÉΓòÉ

Signature

SSLexTable::SSLexTable( const char*);

SSLexTable instances are constructed out of a file name.

Example

SSLexTable zTable( "table.dfa");


ΓòÉΓòÉΓòÉ 6.2.3.3. expressionList ΓòÉΓòÉΓòÉ

The expressionList function return a reference to an SSLexExpressionList.  The
reference is used on pushExpressionList and gotoExpressionList functions in
class SSLex.  An expression list is equivalent to an %expression list in a rule
file.

Signature

SSLexExpressionList* SSLexTable::expressionList( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        An expression list identifier defined in a '.yh' file. You
                     must use a valid #define generated by Visual Parse++.

 Returns

 A pointer to the specidied expression list.  An SSException is thrown if the
 expression list identifier is invalid.

 Example

  #define ALexExpressionListMain 0 /* Generated in header file '.yh' */

  SSLexTable     zTable( "table.dfa");
  SSLexExpressionList& zExpressionList( zTable.expressionList( ALexExpressionListMain));


ΓòÉΓòÉΓòÉ 6.2.4. SSLexLexeme ΓòÉΓòÉΓòÉ

 Concepts
 Constructors
 asChar
 asConstChar
 asConstUnicode
 asUnsigned32
 isEqualLexeme
 length
 line
 offset
 operator const char*
 operator const Unicode*
 operator delete
 operator new
 setBuffer
 setLength
 setLine
 setOffset
 setToken
 token
 type


ΓòÉΓòÉΓòÉ 6.2.4.1. Concepts ΓòÉΓòÉΓòÉ

The SSLexLexeme class represent the lexemes or tokens in your data that are
recognized by an instance of SSLex.

This class passes information between instances of the SSLex and SSYacc
classes.

You can access lexemes through SSYacc member functions, usually in your reduce
virtual function.

See also the SSLex functions complete and operator++.

Note: You must implement the refFree virtual function if you derive a class
from SSLexLexeme.  Reference counting is used to control the lifetime of
SSLexLexemes.  See SSRefCount and Reference Counting for more information.


ΓòÉΓòÉΓòÉ 6.2.4.2. Constructors ΓòÉΓòÉΓòÉ

Signature

SSLexLexeme::SSLexLexeme( void);
SSLexLexeme::SSLexLexeme( SSUnsigned32);
SSLexLexeme::SSLexLexeme( SSLexConsumer&,
   SSUnsigned32, SSLexMark&, SSBooleanValue = SSFalse);
SSLexLexeme::SSLexLexeme( SSUnsigned32, SSUnsigned32, const char*,
   SSUnsigned32, SSUnsigned32, SSBooleanValue = SSFalse);
SSLexLexeme::SSLexLexeme( SSUnsigned32, SSUnsigned32, const SSUnicode*,
   SSUnsigned32, SSUnsigned32, SSBooleanValue = SSFalse);

Instances of SSLexLexeme can be constructed in the following ways:

  1. With no parameters.

  2. From a token number.

  3. From an SSLexConsumer&, SSUnsigned32, an SSLexMark& and an SSBooleanValue
     which defaults to SSFalse.  Note that these parameters are the same as
     those passed on the SSLex virtual function complete. The SSBooleanValue is
     used to indicate if the overloaded new function, which accepts a length
     parameter, was used to allocate the instance.

  4. From a length, token number, data pointer (const char*), line number, line
     offset and an SSBooleanValue. The SSBooleanValue is used to indicate if
     the overloaded new function, which accepts a length parameter, was used to
     allocate the instance.

  5. From a length, token number, data pointer (const SSUnicode*), line number,
     line offset and an SSBooleanValue. The SSBooleanValue is used to indicate
     if the overloaded new function, which accepts a length parameter, was used
     to allocate the instance.

 Warning: If you use SSLexLexeme as a base class,  do not use the new operator
 accepting a length in conjunction with an SSLexLexeme constructor initializer
 with a SSTrue parameter.  In this case, the data will be copied to the end of
 what the base class considers the end of the SSLexLexeme.  This is not
 necessarily the correct offset and you may overlay a part of your new class.

 Example

  SSUnsigned32 zulLine = zConsumer.line();
  SSUnsigned32 zulOffset = zConsumer.offset();
  SSUnsigned32 zulToken = zFinal.token();
  SSUnsigned32 zulLength = strlen( "Test lexeme");
  SSUnsigned32 zpchData = "Test lexeme";

  SSLexLexeme zpLexeme = new( zulLength)
     SSLexLexeme( zulLength, zulToken, zpchData, zulLine, zulOffset, SSTrue);


ΓòÉΓòÉΓòÉ 6.2.4.3. asChar ΓòÉΓòÉΓòÉ

The asChar function returns the buffer pointer as a char*.

Signature

char* SSLexLexeme::asChar( void);

Returns

The buffer pointer.

Example

char* zpchLexeme = zLexeme.asChar();


ΓòÉΓòÉΓòÉ 6.2.4.4. asConstChar ΓòÉΓòÉΓòÉ

The asConstChar function returns the buffer pointer as a const char*.

Signature

const char* SSLexLexeme::asConstChar( void);

Returns

The buffer pointer.

Example

const char* zpchLexeme = zLexeme.asConstChar();


ΓòÉΓòÉΓòÉ 6.2.4.5. asConstUnicode ΓòÉΓòÉΓòÉ

The asConstUnicode function returns the buffer pointer as a const SSUnicode*.

Signature

const SSUnicode* SSLexLexeme::asChar( void);

Returns

The buffer pointer.

Example

const SSUnicode* zpLexeme = zLexeme.asConstUnicode();


ΓòÉΓòÉΓòÉ 6.2.4.6. asUnsigned32 ΓòÉΓòÉΓòÉ

The asUnsigned32 function converts the lexeme to an SSUnsigned32.

Signature

SSUnsigned32 SSLexLexeme::asUnsigned32( SSBooleanValue&);

 Parameters          Meaning

 SSBooleanValue&     A reference to an SSBooleanValue that is updated with an
                     overflow indication.  SSTrue means overflow occurred.

 Returns

 The converted value and an overflow indication.  The value is 0 if the lexeme
 is not numeric.

 Example

  SSBooleanValue zOverflow;
  SSUnsigned32   zulLexeme = zLexeme.asUnsigned32( zOverFlow);
  if ( zOverFlow)
     {
     /* Overflow occurred */
     }


ΓòÉΓòÉΓòÉ 6.2.4.7. isEqualLexeme ΓòÉΓòÉΓòÉ

The isEqualLexeme function tests the equality of the data portion of the
SSLexLexeme.

Signature

SSBooleanValue SSLexLexeme::isEqualLexeme( SSLexLexeme&);

 Parameters          Meaning

 SSLexLexeme&        A reference to an SSLexLexeme (the comparand).

 Returns

 The result of the comparison. SSTrue indicates the lexemes are equal.

 Example

  SSBooleanValue zResult = zLexeme.isEqualLexeme( zCompare);
  if ( zResult)
     {
     /* Lexemes are equal */
     }


ΓòÉΓòÉΓòÉ 6.2.4.8. length ΓòÉΓòÉΓòÉ

The length function returns the length of the lexeme.

Signature

SSUnsigned32 SSLexLexeme::length( void);

Returns

The lexeme length.

Example

SSUnsigned32 zulLength = zLexeme.length();


ΓòÉΓòÉΓòÉ 6.2.4.9. line ΓòÉΓòÉΓòÉ

The line function returns the line number of the lexeme.

Signature

SSUnsigned32 SSLexLexeme::line( void);

Returns

The line number.

Example

SSUnsigned32 zulLine = zLexeme.line();


ΓòÉΓòÉΓòÉ 6.2.4.10. offset ΓòÉΓòÉΓòÉ

The offset function returns the line offset of the lexeme.

Signature

SSUnsigned32 SSLexLexeme::offset( void);

Returns

The lexeme offset.

Example

SSUnsigned32 zulLength = zLexeme.offset();


ΓòÉΓòÉΓòÉ 6.2.4.11. operator const char* ΓòÉΓòÉΓòÉ

The conversion function operator const char*.

Signature

SSLexLexeme::operator const char*( void);

Returns

The lexeme as a const char*.

Example

const char* zpchLexeme = zLexeme;


ΓòÉΓòÉΓòÉ 6.2.4.12. operator const SSUnicode* ΓòÉΓòÉΓòÉ

The conversion function operator const SSUnicode*.

Signature

SSLexLexeme::operator const char*( void);

Returns

The lexeme as a const SSUnicode*.

Example

const SSUnicode* zpLexeme = zLexeme;


ΓòÉΓòÉΓòÉ 6.2.4.13. operator delete ΓòÉΓòÉΓòÉ

The overloaded delete function frees a lexeme allocated with one of the
overloaded new functions.

Signature

void SSLexLexeme::operator delete( void*);

Example

delete zpLexeme;


ΓòÉΓòÉΓòÉ 6.2.4.14. operator new ΓòÉΓòÉΓòÉ

The overloaded new function allocates an SSLexLexeme. The constructors of
SSLexLexeme accept a parameter indicating if the non-default new operator was
used to allocate the SSLexLexeme.  If so, no new buffer is allocated, the data
is copied to the preallocated space at the end of the returned area.

Warning: If you use SSLexLexeme as a base class,  do not use the new operator
accepting a length in conjunction with an SSLexLexeme constructor initializer
with a SSTrue parameter.  In this case, the data will be copied to the end of
what the base class considers the end of the SSLexLexeme.  This is not
necessarily the correct offset and you may overlay a part of your new class.

Signature

void* SSLexLexeme::operator new( size_t);
void* SSLexLexeme::operator new( size_t, SSUnsigned32);

 Parameters          Meaning

 size_t              The size of an SSLexLexeme.  Passed in by the run-time
                     system.

 SSUnsigned32        The size of the data portion of the lexeme.

 Example

  SSUnsigned32 zulLine = zConsumer.line();
  SSUnsigned32 zulOffset = zConsumer.offset();
  SSUnsigned32 zulToken = zFinal.token();
  SSUnsigned32 zulLength = strlen( "Test lexeme");
  SSUnsigned32 zpchData = "Test lexeme";

  SSLexLexeme zpLexeme = new( zulLength)
     SSLexLexeme( zulLength, zulToken, zpchData, zulLine, zulOffset, SSTrue);


ΓòÉΓòÉΓòÉ 6.2.4.15. setBuffer ΓòÉΓòÉΓòÉ

The setBuffer function sets the buffer pointer.

Signature

void SSLexLexeme::setBuffer( char*);

 Parameters          Meaning

 char*               A buffer pointer.

 Example

  char* zpchBuffer = "Buffer";
  zLexeme.setBuffer( zpchBuffer);


ΓòÉΓòÉΓòÉ 6.2.4.16. setLength ΓòÉΓòÉΓòÉ

The setLength function sets the lexeme length.

Signature

void SSLexLexeme::setLength( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The buffer length.

 Example

  char*        zpchBuffer = "Buffer";
  SSUnsigned32 zulLength = strlen( "Buffer");

  zLexeme.setLength( zulLength);
  zLexeme.setBuffer( zpchBuffer);


ΓòÉΓòÉΓòÉ 6.2.4.17. setLine ΓòÉΓòÉΓòÉ

The setLine function sets the lexeme line nnumber.

Signature

void SSLexLexeme::setLine( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The line number.

 Example

  zLexeme.setLine( 10);


ΓòÉΓòÉΓòÉ 6.2.4.18. setOffset ΓòÉΓòÉΓòÉ

The setOffset function sets the lexeme line offset.

Signature

void SSLexLexeme::setOffset( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The line offset.

 Example

  zLexeme.setOffset( 1);


ΓòÉΓòÉΓòÉ 6.2.4.19. setToken ΓòÉΓòÉΓòÉ

The setToken function sets the lexeme token.

Signature

void SSLexLexeme::setToken( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The token.

 Example

  zLexeme.setToken( 50);


ΓòÉΓòÉΓòÉ 6.2.4.20. token ΓòÉΓòÉΓòÉ

The token function returns the token.

Signature

SSUnsigned32 SSLexLexeme::setToken( void);

Returns

The token number.

Example

SSUnsigned32 zulToken = zLexeme.token();


ΓòÉΓòÉΓòÉ 6.2.4.21. type ΓòÉΓòÉΓòÉ

The type function returns the lexeme type.  The lexeme type is an embedded enum
SSLexLexemeType.  The possible values are character and unicode.

Signature

SSLexLexeme::SSLexLexemeType SSLexLexeme::type( void);

Returns

The lexeme type, character or unicode.

Example

SSLexLexeme::SSLexLexemeType zType = zLexeme.type();


ΓòÉΓòÉΓòÉ 6.2.5. SSLexExpressionList ΓòÉΓòÉΓòÉ

 Concepts
 Constructors


ΓòÉΓòÉΓòÉ 6.2.5.1. Concepts ΓòÉΓòÉΓòÉ

The SSLexExpressionList class represents an %expression list in a rule file.

The SSLex class maintains a stack of expression lists.  The top of the stack is
the current %expression list in use.

You can manipulate expression lists with the SSLex functions
pushExpressionList, gotoExpressionList, and popExpressionList.


ΓòÉΓòÉΓòÉ 6.2.5.2. Constructors ΓòÉΓòÉΓòÉ

Instances of this class are never contructed by the programmer.  The SSLexTable
class returns references to SSLexExpressionLists.


ΓòÉΓòÉΓòÉ 6.2.6. SSLexConsumer ΓòÉΓòÉΓòÉ

 Concepts
 Constructors
 addBuffer
 buffer
 bufferInc
 bufferLength
 expandBuffer
 flushLexeme
 lexemeBuffer
 lexemeLength
 lexemeToCurrent
 lexemeToMark
 line
 nextBuffer
 offset
 setBuffer
 setBufferInc
 setBufferLength
 setDataLength
 setEndOfData
 shiftBuffer
 type


ΓòÉΓòÉΓòÉ 6.2.6.1. Concepts ΓòÉΓòÉΓòÉ

The SSLexConsumer class is the base class for data consumers.  A consumer is
required for each instance of SSLex.

Two consumers are provided, SSLexFileConsumer and SSLexStringConsumer.

Use this class as your base class if you need to write a specialized consumer.
You must implement the pure virtual function nextBuffer.

An SSLexConsumer supports a buffer that can hold either 1 or 2 byte unsigned
integers.  Units of the specified length are consumed by an instance of SSLex.


ΓòÉΓòÉΓòÉ 6.2.6.2. Constructors ΓòÉΓòÉΓòÉ

Note: This is an abstract class.

SSLexConsumer::SSLexConsumer( SSLexConsumerType);

Instances of SSLexConsumer are contructed from the embedded enum
SSLexConsumerType.  Valid types are:

 binary              The buffer holds single byte units.  No DBCS checking is
                     done.

 character           The buffer holds single byte units.  DBCS checking is
                     performed.

 unicode             The buffer holds units interpreted as 16-bit unsigned
                     integers.


ΓòÉΓòÉΓòÉ 6.2.6.3. addBuffer ΓòÉΓòÉΓòÉ

The addBuffer function adds data to the consumer buffer. The shiftBuffer and
expandBuffer function are used to make room for the data. Do not use this
function from the nextBuffer virtual function.

Signature

void SSLexConsumer::addBuffer( char*, SSUnsigned32);

 Parameters          Meaning

 char*               The data pointer.

 SSUnsigned32        The data length.

 Example

  zConsumer.addBuffer( "Data", strlen( "Data"));


ΓòÉΓòÉΓòÉ 6.2.6.4. buffer ΓòÉΓòÉΓòÉ

The buffer function returns the buffer address as a char*.  It is set with the
setBuffer function.

Signature

char* SSLexConsumer::buffer( void);

Returns

The buffer pointer as a char*.

Example

char* zpchBuffer = zConsumer.buffer();


ΓòÉΓòÉΓòÉ 6.2.6.5. bufferInc ΓòÉΓòÉΓòÉ

The bufferInc function returns the buffer increment.  The increment is used to
expand the buffer if necessary.  It is set with the setBufferInc function.

Signature

SSUnsigned32 SSLexConsumer::bufferInc( void);

Returns

The buffer increment.

Example

SSUnsigned32 zulInc = zConsumer.bufferInc();


ΓòÉΓòÉΓòÉ 6.2.6.6. bufferLength ΓòÉΓòÉΓòÉ

The bufferLength function returns the buffer length. It is set with the
setBufferLength function.

Signature

SSUnsigned32 SSLexConsumer::bufferLength( void);

Returns

The buffer length.

Example

SSUnsigned32 zulLength = zConsumer.bufferLength();


ΓòÉΓòÉΓòÉ 6.2.6.7. expandBuffer ΓòÉΓòÉΓòÉ

The expandBuffer function expands the consumer buffer. Typically, this function
is used in your nextBuffer virtual function to make room for more data.  See
the shiftBuffer function also.

Signature

SSBooleanValue SSLexConsumer::expandBuffer( SSUnsigned32&,
   SSUnsigned32&);

 Parameters          Meaning

 SSUnsigned32&       A reference that is updated with the offset from the
                     beginning of the buffer (see buffer) of the area to fill.

 SSUnsigned32&       A reference that is updated with the length of the
                     available area.

 Returns

 A success indicator.  SSFalse indicates the expansion was successful.

 Example

 The following example assumes you are running in a nextBuffer virtual
 function.

  SSUnsigned32 zulFill;
  SSUnsigned32 zulStart;
  SSBooleanValue zResult = expandBuffer( zulStart, zulFill);
  if ( !zResult)
     {
     char* zpchStart = buffer() + zulStart;
     /* Read data into zpchBuffer with length zulFill */
     }


ΓòÉΓòÉΓòÉ 6.2.6.8. flushLexeme ΓòÉΓòÉΓòÉ

The flushLexeme flushes the current lexeme from the consumer buffer.  If you
don't supply a SSLexMark, all scanned data is flushed from the buffer, not just
the current lexeme.

Usually, the SSLex::complete function is the only place you will use this
function.

Signature

void SSLexConsumer::flushLexeme( void);
void SSLexConsumer::flushLexeme( SSLexMark&);

 Parameters          Meaning

 SSLexMark&          A reference to a SSLexMark.  A SSLexMark is passed in as a
                     parameter of the SSLex::complete virtual function.

 Example

 This examples assumes you are running in the SSLex::complete virtual function.

  flushLexeme( qMark);


ΓòÉΓòÉΓòÉ 6.2.6.9. lexemeBuffer ΓòÉΓòÉΓòÉ

The lexemeBuffer function returns the address of the start of the current
lexeme as a char*.

Signature

char* SSLexConsumer::lexemeBuffer( void);

Returns

A pointer to the lexeme.

Example

char* zpchBuffer = zConsumer.lexemeBuffer();


ΓòÉΓòÉΓòÉ 6.2.6.10. lexemeLength ΓòÉΓòÉΓòÉ

The lexemeLength function returns the length of the current lexeme.  Usually,
the only place you will use this function is in the SSLex::complete virtual
function. If the SSLexMark instance is not passed, the length of the scanned
data is returned.

Signature

SSUnsigned32 SSLexConsumer::lexemeLength( void);
SSUnsigned32 SSLexConsumer::lexemeLength( SSLexMark&);

 Parameters          Meaning

 SSLexMark&          A reference to an SSLexMark.

 Returns

 The length of the lexeme.

 Example

  SSLexLexeme* SSLex::complete( SSLexConsumer& qConsumer
     SSLexFinalState& qFinal, SSLexMark& qMark)
     {
     SSUnsigned32 zulMark = qConsumer.lexemeLength( qMark);
     /* rest of function */
     }


ΓòÉΓòÉΓòÉ 6.2.6.11. lexemeToCurrent ΓòÉΓòÉΓòÉ

The lexemeToCurrent returns an instance of SSLexLexeme.

This function is usually called in an SSLex error virtual function.

Signature

SSLexLexeme* SSLexLexeme::lexemeToCurrent( void);

Returns

A pointer to the lexeme.

Example

This is the default complete virtual function.

Example

This is the default SSLex::error virtual function:

SSLexLexeme* SSLex::error( SSLexConsumer& qConsumer)
   {
   SSLexLexeme* zpLexeme = qConsumer.lexemeToCurrent();
   throwException( SSExceptionLexError, SSLexMsgError, zpLexeme->.line(),
      zpLexeme->offset(), zpLexeme->asConstChar());
   return zpLexeme;
   }


ΓòÉΓòÉΓòÉ 6.2.6.12. lexemeToMark ΓòÉΓòÉΓòÉ

The lexemeToMark returns an instance of SSLexLexeme.

This function is usually called in an SSLex complete virtual function.

Signature

SSLexLexeme* SSLexLexeme::lexemeToMark( SSLexMark&, SSUnsigned32);

 Parameters          Meaning

 SSLexMark&          A reference to an SSLexMark.

 SSUnsigned32        The token identifier associated with the lexeme.

 Returns

 A pointer to the lexeme.

 Example

 This is the default complete virtual function.

  SSLexLexeme* SSLex::complete( SSLexConsumer& qConsumer
     SSUnsigned32 qulToken, SSLexMark& qMark)
     {
     return qConsumer.lexemeToMark( qMark, qulToken);
     }


ΓòÉΓòÉΓòÉ 6.2.6.13. line ΓòÉΓòÉΓòÉ

The line function returns the line number of the  beginning of the current
lexeme (see currentBuffer).

Signature

SSUnsigned32 SSLexConsumer::line( void);

Returns

The line number.

Example

SSUnsigned32 zulLine = zConsumer.line();


ΓòÉΓòÉΓòÉ 6.2.6.14. nextBuffer ΓòÉΓòÉΓòÉ

The nextBuffer pure virtual function is implemented by classes using
SSLexConsumer as a base class.  This function is called when more data is
needed for processing.

Signature

virtual SSUnsigned32 SSLexConsumer::nextBuffer( void) = 0;

Returns

The length of the new data.

Example

This is similar to the SSLexFileConsumer implementation. opFile is a FILE*.

SSUnsigned32 SSLexFileConsumer::nextBuffer( void)
   {
   SSUnsigned32 zulRead, zulFill;
   if ( shiftBuffer( zulRead, zulFill) && expandBuffer( zulRead, zulFill))
      return 0;

   return fread( buffer() + zulRead, 1, zulFill, opFile);
   }


ΓòÉΓòÉΓòÉ 6.2.6.15. offset ΓòÉΓòÉΓòÉ

The offset function returns the line offset of the  beginning of the current
lexeme (see currentBuffer).

Signature

SSUnsigned32 SSLexConsumer::offset( void);

Returns

The line offset.

Example

SSUnsigned32 zulOffset = zConsumer.offset();


ΓòÉΓòÉΓòÉ 6.2.6.16. setBuffer ΓòÉΓòÉΓòÉ

The setBuffer function sets the buffer pointer.  Typically, this function is
used once in the constructor of a class derived from SSLexConsumer.

Signature

void SSLexConsumer::setBuffer( char*);

 Parameters          Meaning

 char*               A buffer pointer.

 Example

 This example assumes you are running in a constructor of a class derived from
 SSLexConsumer.

  char* zpchBuffer = new char[ 4096];
  setBufferLength( 4096);
  setBuffer( zpchBuffer);


ΓòÉΓòÉΓòÉ 6.2.6.17. setBufferInc ΓòÉΓòÉΓòÉ

The setBufferInc function sets the buffer increment. The expandBuffer function
is used to expand the buffer.

Signature

void SSLexConsumer::setBufferInc( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The buffer increment.

 Example

 This example assumes you are running in a constructor of a class derived from
 SSLexConsumer.

  char* zpchBuffer = new char[ 4096];
  setBufferLength( 4096);
  setBuffer( zpchBuffer);
  setBufferInc( 4096);


ΓòÉΓòÉΓòÉ 6.2.6.18. setBufferLength ΓòÉΓòÉΓòÉ

The setBufferLength function sets the buffer length.

Signature

void SSLexConsumer::setBufferLength( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The buffer length.

 Example

 This example assumes you are running in a constructor of a class derived from
 SSLexConsumer.

  char* zpchBuffer = new char[ 4096];
  setLength( 4096);
  setBuffer( zpchBuffer);


ΓòÉΓòÉΓòÉ 6.2.6.19. setBufferLength ΓòÉΓòÉΓòÉ

The setBufferLength function sets the initial data length. Normally, this
function is used once in a constructor to set the initial data length.

Signature

void SSLexConsumer::setDataLength( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The data length.

 Example

 This example assumes you are running in a constructor of a class derived from
 SSLexConsumer.

  char* zpchBuffer = new char[ 4096];
  setLength( 4096);
  setBuffer( zpchBuffer);
  strcpy( zpchBuffer, "Test Data");
  setDataLength( strlen( "Test Data"));


ΓòÉΓòÉΓòÉ 6.2.6.20. setEndOfData ΓòÉΓòÉΓòÉ

The setEndOfData function sets the end of data indicator.  The end of data
indicator is also set when 0 is returned from nextBuffer.

Signature

void SSLexConsumer::setEndOfData( void);

Example

zConsumer.setEndOfData();


ΓòÉΓòÉΓòÉ 6.2.6.21. shiftBuffer ΓòÉΓòÉΓòÉ

The shiftBuffer function shifts the data in the buffer. Unprocessed data at the
end of the buffer is shifted over the processed data.  This will leave room at
the end of the buffer for your nextBuffer function.  See also expandBuffer.

Signature

SSBooleanValue SSLexConsumer::shiftBuffer( SSUnsigned32&,
   SSUnsigned32&);

 Parameters          Meaning

 SSUnsigned32&       A reference that is updated with the offset from the
                     beginning of the buffer (see buffer) of the area to fill.

 SSUnsigned32&       A reference that is updated with the length of the
                     available area.

 Returns

 A success indicator.  SSFalse indicates data was shifted.

 Example

 The following example assumes you are running in a nextBuffer virtual
 function.

  SSUnsigned32 zulFill;
  SSUnsigned32 zulStart;
  SSBooleanValue zResult = shiftBuffer( zulStart, zulFill);
  if ( !zResult)
     {
     char* zpchStart = buffer() + zulStart;
     /* Read data into zpchBuffer with length zulFill */
     }


ΓòÉΓòÉΓòÉ 6.2.6.22. type ΓòÉΓòÉΓòÉ

The type function returns the consumer type. The consumer type is a nested enum
SSLexConsumerType. Possible values are binary, character, or unicode.

Signature

SSLexConsumer::SSLexConsumerType SSLexConsumer::type( void);

Returns

The consumer type.

Example

SSLexConsumer::SSLexConsumerType zType = qConsumer.type();


ΓòÉΓòÉΓòÉ 6.2.7. SSLexFileConsumer ΓòÉΓòÉΓòÉ

 Concepts
 Constructors


ΓòÉΓòÉΓòÉ 6.2.7.1. Concepts ΓòÉΓòÉΓòÉ

The SSLexFileConsumer class is used to construct file consumers for use by
instances of SSLex.  See also SSLexStringConsumer.


ΓòÉΓòÉΓòÉ 6.2.7.2. Constructors ΓòÉΓòÉΓòÉ

Signature

SSLexFileConsumer::SSLexFileConsumer( const char*,
   SSLexConsumerType = character, SSUnsigned32 = SSLexConsumerDefaultSize,
   SSUnsigned32 = SSLexConsumerDefaultInc);

 const char*           A file name.

 SSLexConsumerType     A consumer type.  See SSLexConsumer.

 SSUnsigned32          The initial buffer length.  The default is the special
                       length SSLexConsumerAll which allocates a buffer large
                       enough for the entire file.

 SSUnsigned32          The buffer increment.  The default increment is 0.
 Example

  SSLexFileConsumer zFile( "file.name");


ΓòÉΓòÉΓòÉ 6.2.8. SSLexStringConsumer ΓòÉΓòÉΓòÉ

 Concepts
 Constructors


ΓòÉΓòÉΓòÉ 6.2.8.1. Concepts ΓòÉΓòÉΓòÉ

The SSLexStringConsumer class is used to construct string consumers for use by
instances of SSLex.  See also SSLexFileConsumer.


ΓòÉΓòÉΓòÉ 6.2.8.2. Constructors ΓòÉΓòÉΓòÉ

Signature

SSLexStringConsumer::SSLexStringConsumer( const char*,
   SSLexConsumerType = character);

 const char*           A string address.

 SSLexConsumerType     A consumer type.  See SSLexConsumer.

 Example

  SSLexStringConsumer zFile( "This is a consumer string");


ΓòÉΓòÉΓòÉ 6.2.9. SSYacc ΓòÉΓòÉΓòÉ

 Concepts
 Constructors
 accept
 elementFromProduction
 elementFromStack
 error
 errorToken
 lex
 lookahead
 nextLexeme
 parse
 pop
 push
 reduce
 reset
 setAbort
 setLex
 setTable
 shift
 shiftedSinceError
 stackElement
 validLookaheads
 wasAborted
 wasError


ΓòÉΓòÉΓòÉ 6.2.9.1. Concepts ΓòÉΓòÉΓòÉ

The SSYacc class controls the parsing process. SSYacc is an abstract class with
one pure virtual function, reduce.

A skeleton reduce function is generated by Visual Parse++ in the header file
('.yh') for each rule file.

An instance of SSYacc needs 2 pieces of data to function, a table and a lexer.
Each of these is represented by a class.

The table is the '.llr' file generated by Visual Parse++.  The associated class
is SSYaccTable. This controls the parser.

The lexer is an instance of SSLex.


ΓòÉΓòÉΓòÉ 6.2.9.2. Constructors ΓòÉΓòÉΓòÉ

Signature

SSYacc::SSYacc( const char* = 0);
SSYacc::SSYacc( SSLex&, const char*);
SSYacc::SSYacc( SSLex&, SSYaccTable&);

SSYacc instances are constructed in the following ways:

  1. From a const char*.  In this case, you must supply the lexer with setLex
     (and the table with setTable if the default is used).

  2. From a reference to an SSLex and a table name.

  3. From a previously constructed SSLex and SSYaccTable.

 Example

  SSLex       zLex( "file.name", "table.dfa");
  SSYaccTable zTable( "table.llr");

  SSYacc zYacc( "table.llr");
  zYacc.setLex( zLex);

  SSYacc zYacc( zLex, "table.llr");

  SSYacc zYacc( zLex, zTable);


ΓòÉΓòÉΓòÉ 6.2.9.3. accept ΓòÉΓòÉΓòÉ

The accept virtual function is called when parsing has completed.  The default
function returns SSFalse if no errors occurred.

The return value of this function is passed to the caller of parse.

Signature

virtual SSBooleanValue SSYacc::accept( void);

Returns

An error indication.  SSFalse indicates no errors were encountered.

Example

This is the default accept function.

SSBooleanValue SSYacc::accept( void)
   {
   return wasError();
   }


ΓòÉΓòÉΓòÉ 6.2.9.4. elementFromProduction ΓòÉΓòÉΓòÉ

The elementFromProduction function returns an element from the parse stack.

The element returned is relative to the current production being reduced.  This
is similar to the $1, $2, ..., variables in traditional yacc tools, except the
index starts from 0.

This function is only valid when called from the reduce virtual function.

Signature

SSYaccStackElement* SSYacc::elementFromProduction( SSSigned32);

 Parameters          Meaning

 SSSigned32          The element index. Can be a negative number.

 Returns

 A pointer to the stack element associated with the index.

 Example

 The following example assumes you are in a case statement in a reduce virtual
 function.

  case AMyYaccProdSample:
     // Prod -> Symbol0 Symbol1 Symbol2
     {
     SSYaccStackElement* zpElement0 = elementFromProduction( 0);
     SSYaccStackElement* zpElement1 = elementFromProduction( 1);
     SSYaccStackElement* zpElement2 = elementFromProduction( 2);
     }


ΓòÉΓòÉΓòÉ 6.2.9.5. elementFromStack ΓòÉΓòÉΓòÉ

The elementFromStack function returns an element from the parse stack.

The element returned is relative to the top of the parsing stack. Zero is the
top of the stack.

Signature

SSYaccStackElement* SSYacc::elementFromStack( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The element index.

 Returns

 A pointer to the stack element associated with the index.


ΓòÉΓòÉΓòÉ 6.2.9.6. error ΓòÉΓòÉΓòÉ

The error virtual function is called when a parsing error occurs.  The default
function calls errorToken to resolve the error.

Signature

virtual SSBooleanValue SSYacc::error( SSUnsigned32,
   SSLexLexeme&);

 Parameters          Meaning

 SSUnsigned32        The state number.

 SSLexLexeme&        The lookahead lexeme.

 Returns

 A continuation indication.  SSFalse means keep processing, SSTrue to exit the
 parsing process.

 Example

 This is the default error function.

  SSBooleanValue SSYacc::error( SSUnsigned32 qulState,
     SSLexLexeme& qLookahead)
     {
     return errorToken();
     }


ΓòÉΓòÉΓòÉ 6.2.9.7. errorToken ΓòÉΓòÉΓòÉ

The errorToken function performs error recovery.  Error recovery is described
in Error Recovery.

Signature

SSBooleanValue SSYacc::errorToken( void);

Returns

Throws an SSException if recovery fails.

Example

This is the default error function.

SSBooleanValue SSYacc::error( SSUnsigned32 qulState,
   SSLexLexeme& qLookahead)
   {
   return errorToken();
   }


ΓòÉΓòÉΓòÉ 6.2.9.8. lex ΓòÉΓòÉΓòÉ

The lex function returns a pointer to the SSLex instance.

Signature

SSLex* SSYacc::lex( void);

Returns

A pointer to the SSLex instance or 0.

Example

SSLex zLex( "file.name", "table.dfa");
SSYacc zYacc( zLex, "table.llr");

SSLex* zpLex = zYacc.lex();


ΓòÉΓòÉΓòÉ 6.2.9.9. lookahead ΓòÉΓòÉΓòÉ

The lookahead function returns the current lookahead lexeme.

Signature

SSLexLexeme& SSYacc::lookahead( void);

Returns

The current lookahead lexeme.

Example

SSLex zLex( "file.name", "table.dfa");
SSYacc zYacc( zLex, "table.llr");

SSLexLexeme& zLexeme = zYacc.lookahead();


ΓòÉΓòÉΓòÉ 6.2.9.10. nextLexeme ΓòÉΓòÉΓòÉ

The nextLexeme virtual function returns the next lexeme. Override this function
if you want to supply lexemes from a source other than an SSLex instance.

Signature

virtual SSLexLexeme* SSYacc::nextLexeme( void);

Returns

The next lexeme.  0 indicates end of data.

Example

This is the default nextLexeme function.

SSLexLexeme* SSYacc::nextLexeme( void)
   {
   return ( *lex())++;
   }


ΓòÉΓòÉΓòÉ 6.2.9.11. parse ΓòÉΓòÉΓòÉ

The parse function starts the parsing process.

Signature

SSBooleanValue SSYacc::parse( void);

Returns

An error indication.  SSTrue indicates an error occurred. Can also throw an
SSException.

Example

SSLex  zLex( "file.name", "table.dfa");
SSYacc zYacc( zLex, "table.llr");

zYacc.parse();


ΓòÉΓòÉΓòÉ 6.2.9.12. pop ΓòÉΓòÉΓòÉ

The pop function pops elements off the parsing stack. Extreme caution should be
used when using this function. It is only intended to be used for customized
error recovery. You must have extensive knowledge of LR parsing theory to use
this function.

Signature

SSBooleanValue SSYacc::pop( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The stack offset. Zero represents the top of the stack.

 Returns

 Throws an instance of SSException if an error occurs.


ΓòÉΓòÉΓòÉ 6.2.9.13. push ΓòÉΓòÉΓòÉ

The push function pushes an element on the parsing stack. Extreme caution
should be used when using this function. It is only intended to be used for
customized error recovery. You must have extensive knowledge of LR parsing
theory to use this function.

Signature

SSBooleanValue SSYacc::push( SSYaccStackElement&);

 Parameters          Meaning

 SSYaccStackElement  A stack element.

 Returns

 Throws an instance of SSException if an error occurs.


ΓòÉΓòÉΓòÉ 6.2.9.14. reduce ΓòÉΓòÉΓòÉ

The reduce pure virtual function is called when a reduction occurrs.  Visual
Parse++ generates a skeleton reduce function for each rule file.

Classes derived from SSYacc must supply a reduce function.

Signature

SSYaccStackElement* SSYacc::reduce( SSUnsigned32, SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The production number.

 SSUnsigned32        The production size.

 Returns

 A stack element.  This is pushed on top of the stack after the right hand side
 of the production is popped.  0 will terminate the parsing process.

 Example

  SSLex  zLex( "file.name", "table.dfa");
  SSYacc zYacc( zLex, "table.llr");
  zYacc.parse();
    ┬╖
    ┬╖
  SSYaccStackElement* MyYaccClass::reduce( SSUnsigned32 qProd,
     SSUnsigned32 qSize);
     {
     switch( qProd)
       {
       case MyYaccProduction0:
       // Prod -> ...

       case MyYaccProduction1:
       // Prod -> ...

       case MyYaccProduction2:
       // Prod -> ...

       ┬╖
       ┬╖
       ┬╖
       default:
          break;
       }

     return stackElement();
     }


ΓòÉΓòÉΓòÉ 6.2.9.15. reset ΓòÉΓòÉΓòÉ

The reset function resets the parser to its initial state. This function is
provided to reuse a parser (after a parse  has been issued) without deleting
and reconstructing the parser.

Signature

void SSYacc::reset( void);

Example

zYacc.reset();


ΓòÉΓòÉΓòÉ 6.2.9.16. setAbort ΓòÉΓòÉΓòÉ

The setAbort function aborts the parsing process.

Signature

void SSYacc::setAbort( void);

Example

This example assumes you are running in an SSYacc virtual function.

setAbort();


ΓòÉΓòÉΓòÉ 6.2.9.17. setLex ΓòÉΓòÉΓòÉ

The setLex function sets the lexer for the SSYacc instance.

Signature

void SSYacc::setLex( SSLex&);

 Parameters          Meaning

 SSLex&              An SSLex instance.

 Example

  SSLex  zLex( "file.name", "table.dfa");
  SSYacc zYacc( "table.llr");
  zYacc.setLex( zLex);


ΓòÉΓòÉΓòÉ 6.2.9.18. setTable ΓòÉΓòÉΓòÉ

The setTable function sets the table for the SSYacc instance.

Signature

void SSYacc::setTable( const char*);
void SSYacc::setTable( SSYaccTable&);

 Parameters          Meaning

 const char*         A table name.

 SSYaccTable&        An SSYaccTable instance.

 Example

  SSLex  zLex( "file.name", "table.dfa");
  SSYacc zYacc;
  zYacc.setLex( zLex);
  zYacc.setTable( "table.llr");


ΓòÉΓòÉΓòÉ 6.2.9.19. shift ΓòÉΓòÉΓòÉ

The shift virtual function is called each time a token is shifted.

Signature

virtual SSYaccStackElement* SSYacc::shift( SSLexLexeme&);

 Parameters          Meaning

 SSLexLexeme&        The lexeme about to be shifted.

 Returns

 A stack element that is pushed on the stack.  0 will terminate the parsing
 process.

 Example

 This is the default shift virtual function.

  SSYaccStackElement* SSYacc::shift( SSLexLexeme& qLexeme)
     {
     return stackElement();
     }


ΓòÉΓòÉΓòÉ 6.2.9.20. shiftedSinceError ΓòÉΓòÉΓòÉ

The shiftedSinceError function returns the number of tokens shifted since the
last error.

Signature

SSUnsigned32 SSYacc::shiftedSinceError( void);

Returns

A number of tokens shifted since the last error.

Example

This example assumes you are in an SSYacc virtual function.

SSUnsigned32 zulError = shiftedSinceError();


ΓòÉΓòÉΓòÉ 6.2.9.21. stackElement ΓòÉΓòÉΓòÉ

The stackElement virtual function is called each time a stack element is
needed.  The default function returns an SSYaccStackElement.  Override this
function if you want to use customized stack elements derived from
SSYaccStackElement.

Signature

virtual SSYaccStackElement* SSYacc::stackElement( void);

Returns

A stack element. 0 terminates the parsing process.

Example

This is the default stackElement virtual function. The refDec function is used
to set the use count to 0 before returning.  See Reference Counting and refDec
for more information.

SSYaccStackElement* SSYacc::stackElement( void)
   {
   SSYaccStackElement* zpElement = new SSYaccStackElement;
   zpElement->refDec( SSFalse);
   return zpElement;
   }


ΓòÉΓòÉΓòÉ 6.2.9.22. validLookaheads ΓòÉΓòÉΓòÉ

The validLookaheads function returns an array of tokens containing the valid
lookaheads for the given state.  You must delete the array returned (delete
[]).  See also SSLex::tokenToConstChar.

Signature

SSUnsigned32* SSYacc::validLookaheads( SSUnsigned32,
   SSUnsigned32&);

 Parameters          Meaning

 SSUnsigned32        The state.

 SSUnsigned32&       A reference that will be updated with the number of tokens
                     in the array.

 Returns

 An array containing the lookahead tokens.

 Example

  SSLex         zLex( "file.name", "table.dfa");
  SSYacc        zYacc( zLex, "table.llr");
  SSUnsigned32  zulCount;
  SSUnsigned32* zpTokens = validLookaheads( zulState, zulCount);

  string zMsg( "Expected ");
  zMsg.concatenate( zLex.tokenToConstChar( zpTokens[ 0]));
  for ( int i = 1; i < zulCount; i++)
      {
      zMsg.concatenate( ", ");
      zMsg.concatenate( zLex.tokenToConstChar( zpTokens[ i]));
      }

  delete [] zpTokens;


ΓòÉΓòÉΓòÉ 6.2.9.23. wasAborted ΓòÉΓòÉΓòÉ

The wasAborted function is used to determine if the parsing process was aborted
with setAbort.

Signature

SSBooleanValue SSYacc::wasAborted( void);

Returns

SSTrue if setAbort was used to abort the parsing process.

Example

SSLex zLex( "file.name", "table.dfa");
SSYacc zYacc( zLex, "table.llr");
zYacc.parse();
if ( zYacc.wasAborted())
   {
   /* Aborted */
   }


ΓòÉΓòÉΓòÉ 6.2.9.24. wasError ΓòÉΓòÉΓòÉ

The wasError function is used to determine if an error occurred while parsing.

Signature

SSBooleanValue SSYacc::wasError( void);

Returns

SSTrue if an error occurred.

Example

SSLex zLex( "file.name", "table.dfa");
SSYacc zYacc( zLex, "table.llr");
zYacc.parse();
if ( zYacc.wasError())
   {
   /* Error occurred */
   }


ΓòÉΓòÉΓòÉ 6.2.10. SSYaccTable ΓòÉΓòÉΓòÉ

 Concepts
 Constructors


ΓòÉΓòÉΓòÉ 6.2.10.1. Concepts ΓòÉΓòÉΓòÉ

The SSYaccTable class represents a parsing table.

Tables can be shared.  The main use of SSYaccTable is to define static
definitions of frequently used tables so the file will only be read once, when
the SSYaccTable instance is constructed.


ΓòÉΓòÉΓòÉ 6.2.10.2. Constructors ΓòÉΓòÉΓòÉ

Signature

SSYaccTable::SSYaccTable( const char*);

SSYaccTable instances are constructed out of a file name.

Example

SSYaccTable zTable( "table.llr");


ΓòÉΓòÉΓòÉ 6.2.11. SSYaccStackElement ΓòÉΓòÉΓòÉ

 Concepts
 Constructors
 lexeme
 state


ΓòÉΓòÉΓòÉ 6.2.11.1. Concepts ΓòÉΓòÉΓòÉ

Items put on the parsing stack are made out of the SSYaccStackElement class.
SSYaccStackElements contain a field for a lexeme and state information.  If you
need extra information in a stack element, derive a class from
SSYaccStackElement and override the SSYacc member function stackElement.

SSYaccStackElements can be accessed with the SSYacc member function
elementFromProduction.

Note: You must implement the refFree virtual function if you derive a class
from SSYaccStackElement.  Reference counting is used to control the lifetime of
SSYaccStackElements.  See SSRefCount and Reference Counting for more
information.


ΓòÉΓòÉΓòÉ 6.2.11.2. Constructors ΓòÉΓòÉΓòÉ

Signature

SSYaccStackElement::SSYaccStackElement( void);

The constructor accepts no parameters.

Example

SSYaccStackElement zElement;


ΓòÉΓòÉΓòÉ 6.2.11.3. lexeme ΓòÉΓòÉΓòÉ

The lexeme function returns the lexeme associated with the stack element.

Signature

SSLexLexeme* YaccStackElement::lexeme( void);

Returns

The lexeme pointer or 0.

Example

The following example assumes you are in a case statement in a reduce virtual
function.

case AMyYaccProdSample:
   // Prod -> Symbol0 Symbol1 Symbol2
   {
   SSYaccStackElement* zpElement0 = elementFromProduction( 0);
   SSLexLexeme* zpLexeme = zpElement0->lexeme();
   }


ΓòÉΓòÉΓòÉ 6.2.11.4. state ΓòÉΓòÉΓòÉ

The state function returns the state associated with the stack element.

Signature

SSUnsigned32 YaccStackElement::lexeme( void);

Returns

The state number.

Example

The following example assumes you are in a case statement in a reduce virtual
function.

case AMyYaccProdSample:
   // Prod -> Symbol0 Symbol1 Symbol2
   {
   SSYaccStackElement* zpElement0 = elementFromProduction( 0);
   SSUnsigned32 zulState = zpElement0->state();
   }


ΓòÉΓòÉΓòÉ 6.2.12. SSException ΓòÉΓòÉΓòÉ

 Concepts
 Constructors
 errorId
 setText
 text


ΓòÉΓòÉΓòÉ 6.2.12.1. Concepts ΓòÉΓòÉΓòÉ

Visual Parse++ classes throw objects of this class when errors occur.


ΓòÉΓòÉΓòÉ 6.2.12.2. Constructors ΓòÉΓòÉΓòÉ

Signature

SSException::SSException( const char*, SSUnsigned32 = 0);
SSException::SSException( const SSException&);

SSException objects can be constructed in one of the following ways:

  1. From a const char* containing a message and an error id that defaults to
     0.

  2. From another SSException.

 Example

  SSException zExcept( "Error message", 100);


ΓòÉΓòÉΓòÉ 6.2.12.3. errorId ΓòÉΓòÉΓòÉ

The errorId function returns the error id.  Possible error ids are listed in
ssexcept.h.

Signature

SSUnsigned32 SSException::errorId( void);

Returns

The error id.

Example

try
   {
   SSLex zLex( "file.name", "table.dfa");
   SSYacc zYacc( zLex, "table.llr");
   zYacc.parse();
   }
catch ( SSException zExcept)
   {
   SSUnsigned32 zulError = zExcept.errorId();
   }


ΓòÉΓòÉΓòÉ 6.2.12.4. setText ΓòÉΓòÉΓòÉ

The setText function sets the text associated with the SSException object.  The
length is truncated to SSExceptionTextLength, defined in ssexcept.hpp.

Signature

void SSException::setText( const char*);

 Parameters          Meaning

 const char*         The text.

 Example

  SSException zpExcept = new SSException( "");
  zpExcept->setText( "New message text");


ΓòÉΓòÉΓòÉ 6.2.12.5. text ΓòÉΓòÉΓòÉ

The text function returns the text.

Signature

const char* SSException::text( void);

Returns

The text.

Example

try
   {
   SSLex zLex( "file.name", "table.dfa");
   SSYacc zYacc( zLex, "table.llr");
   zYacc.parse();
   }
catch ( SSException zExcept)
   {
   cout << zExcept.text();
   }


ΓòÉΓòÉΓòÉ 6.2.13. Reference Counting ΓòÉΓòÉΓòÉ

Because of the proliferation and sharing of some objects, the lifetime of the
object instances is indeterminate to the component creating the objects. The
question "When do I delete the object instance ?" cannot be answered when the
object is created. Two or more completely seperate components have access to
the object, so how do I control object cleanup ?

One answer is to use a reference counting scheme.  Each component increments a
reference count when accessing the shared object.  While the reference count is
non-zero, the object is in use by some component. When processing has been
completed, the reference count is decremented. If and only if it is 0, the
object is deleted.

The classes SSRef and SSRefCount implement reference counting.  SSRef is a
template class.  The template argument is a class derived from SSRefCount.

Instances of the template class SSRef control the reference count contained in
the SSRefCount class.  It acts as a smart pointer.  You use the SSRef class
exactly as you would use a pointer.

When an SSRef instance is assigned a pointer or reference, the reference count
is incremented (refInc). When the SSRef instance is destroyed or reassigned,
the reference count is decremented (refDec). If it is 0, the virtual member
function refFree is called to delete the object associated with the reference.

The classes SSLexLexeme and SSYaccStackElement are derived from SSRefCount
since they are shared between your application code and the SSLex and SSYacc
classes. To ensure integrity, you should use the SSLexLexemeRef and
SSYaccStackElementRef classes to control access to these objects.

An example should help clarify some of these points.  The main virtual function
of interest to your application is the reduce member function in the SSYacc
class.  The reduce function is called each time a production is reduced.  This
is the driver for your parser, where all the activity occurs.

In this function,  you have access to SSLexLexemes and SSYaccStackElements. A
common requirement would be to use these objects in your application code
during the parsing process.  All you need to do is use the SSLexLexemeRef and
SSYaccStackElementRef classes to refer to these objects and cleanup is
automatic.

Examine the following code:

class MySymbolClass : public SomeListElementClass
   {
   public:
                     MySymbolClass( SSLexLexeme*);
   SSLexLexeme*      lexeme( void);

   private:
      SSLexLexemeRef orLexeme;
   };

MySymbolClass::MySymbolClass( SSLexLexeme* qpLexeme) : orLexeme( qpLexeme)
   {
   }

SSLexLexeme* MySymbolClass::lexeme( void)
   {
   return orLexeme;
   }

class MyYaccClass : public SSYacc
   {
   public:
      ┬╖
      ┬╖
   private:
      SomeListClass oList;
   };

SSYaccStackElement* MyYaccClass::reduce( SSUnsigned32 qulProd,
   SSUnsigned32 qulSize)
   {
   switch ( qulProd)
      {
      case MyYaccProd0:
      // Prod -> Symbol0
         {
         SSYaccStackElement* zpElement0 = elementFromProduction( 0);
         MySymbolClass* zpMySymbol = new MySymbolClass( zpElement0->lexeme());
         oList.add( zpMySymbol);

      ┬╖
      ┬╖
      }
   return stackElement();
   }

The intention is to keep a list (SomeListClass) of a new class, MySymbolClass,
which contains lexeme objects. I embed the SSLexLexemeRef in the new class to
ensure that the lexeme is not deleted. The reference causes the use count to be
incremented, extending the lifetime of the object.  The lexeme will not be
deleted until the MySymbolClass instance is deleted.


ΓòÉΓòÉΓòÉ 6.2.14. SSRef ΓòÉΓòÉΓòÉ

 Concepts
 Constructors
 operator=
 operator*
 operator->
 operator T*


ΓòÉΓòÉΓòÉ 6.2.14.1. Concepts ΓòÉΓòÉΓòÉ

The SSRef class is essentially a smart pointer template class. The template
argument is a class derived from SSRefCount. See Reference Counting for a
complete discussion.


ΓòÉΓòÉΓòÉ 6.2.14.2. Constructors ΓòÉΓòÉΓòÉ

The constructors assume a template argument T.

Signature

SSRef::SSRef( T*);
SSRef::SSRef( T&);
SSRef::SSRef( void);
SSRef::SSRef( SSRef< T>&);

You can construct an SSRef in one of the following ways:

  1. From a pointer to a T.

  2. From a reference to a T.

  3. With no parameters.

  4. From another SSRef< T>.

 Example

 Assume you are passed a C++ reference to a SSLexLexeme object in qLexeme.

  typedef SSRef< SSLexLexeme> SSLexLexemeRef;

  SSLexLexemeRef zpLexeme0( &qLexeme);
  SSLexLexemeRef zpLexeme1( qLexeme);


ΓòÉΓòÉΓòÉ 6.2.14.3. operator= ΓòÉΓòÉΓòÉ

The overloaded assignment operator accepts 3 types, a pointer, a C++ reference,
or a reference to another SSRef.

Signature

SSRef< T>& SSRef::operator=( T*);
SSRef< T>& SSRef::operator=( T&);
SSRef< T>& SSRef::operator=( SSRef< T>&);

Returns

The SSRef object.

Example

Assume you are passed a C++ reference to a SSLexLexeme object in qLexeme.

typedef SSRef< SSLexLexeme> SSLexLexemeRef;

SSLexLexemeRef zRef0;
SSLexLexemeRef zRef1;
zRef0 = &qLexeme;
zRef1 = qLexeme;


ΓòÉΓòÉΓòÉ 6.2.14.4. operator* ΓòÉΓòÉΓòÉ

The dereference operator returns a reference to the underlying template
argument object instance.

Signature

SSRef::operator*( void);

Returns

The SSRef template argument object instance.

Example

Assume you are passed a C++ reference to a SSLexLexeme object in qLexeme.

typedef SSRef< SSLexLexeme> SSLexLexemeRef;

SSLexLexemeRef zRef( qLexeme);
SSLexLexeme&   zLexeme( *zRef);


ΓòÉΓòÉΓòÉ 6.2.14.5. operator-> ΓòÉΓòÉΓòÉ

This overloaded operator accesses members of the underlying template argument
object instance.

Signature

T* SSRef::operator->( void);

Returns

A pointer to the template argument object instance.

Example

Assume you are passed a C++ reference to a SSLexLexeme object in qLexeme.

typedef SSRef< SSLexLexeme> SSLexLexemeRef;

SSLexLexemeRef zRef( qLexeme);
SSUnsigned32 zulToken = zRef->token();


ΓòÉΓòÉΓòÉ 6.2.14.6. operator T* ΓòÉΓòÉΓòÉ

The T* conversion operator.  Converts an SSRef< T> to a T*.

Signature

SSRef::operator T*( void);

Returns

A pointer to the template argument object instance.

Example

Assume you are passed a C++ reference to a SSLexLexeme object in qLexeme.

typedef SSRef< SSLexLexeme> SSLexLexemeRef;

SSLexLexemeRef zRef( qLexeme);
SSLexLexeme*   zpLexeme = zRef;


ΓòÉΓòÉΓòÉ 6.2.15. SSRefCount ΓòÉΓòÉΓòÉ

 Concepts
 Constructors
 refInc
 refDec
 refFree


ΓòÉΓòÉΓòÉ 6.2.15.1. Concepts ΓòÉΓòÉΓòÉ

The SSRefCount class implements reference counting for classes derived from it.
See Reference Counting for a complete discussion.

You must implement the refFree virtual function for all classes derived from
SSRefCount, either directly or indirectly.


ΓòÉΓòÉΓòÉ 6.2.15.2. Constructors ΓòÉΓòÉΓòÉ

The constructor initializes the reference count to 1.

Signature

SSRefCount::SSRefCount( void);

Example

class MyRefCountedClass : public SSRefCount
   {
   ┬╖
   ┬╖
   ┬╖
   };

MyRefCountClass zMyClass; /* Reference count is 1 */


ΓòÉΓòÉΓòÉ 6.2.15.3. refInc ΓòÉΓòÉΓòÉ

The refInc virtual function increments the use count.

Signature

virtual void SSRefCount::refInc( void);

Example

Assume you are passed a C++ reference to a SSLexLexeme object in qLexeme.

typedef SSRef< SSLexLexeme> SSLexLexemeRef;

SSLexLexemeRef zRef( qLexeme);
zRef.refInc();


ΓòÉΓòÉΓòÉ 6.2.15.4. refDec ΓòÉΓòÉΓòÉ

The refDec virtual function decrements the use count.  If the count is 0 and
the parameter is SSTrue, refFree is called to delete the object.

Signature

virtual void SSRefCount::refDec( SSBooleanValue = SSTrue);

 Parameters          Meaning

 SSBooleanValue      A boolean value used to control deleting the object.  The
                     refFree function is only called if the count is 0 and the
                     boolean value is SSTrue.  This is useful for initializing
                     a use count to 0, without deleting the object.

 Example

 This is the default SSYacc::stackElement virtual function.  Note that the use
 count is set to 0 with refDec before returning.  This essentially passes
 ownership of the object to the caller of stackElement.

  SSYaccStackElement* SSYacc::stackElement( void)
     {
     SSYaccStackElement* zpElement = new SSYaccStackElement; /* Count is 1 */
     zpElement->refDec( SSFalse); /* Count is now 0 */
     return zpElement;
     }


ΓòÉΓòÉΓòÉ 6.2.15.5. refFree ΓòÉΓòÉΓòÉ

The refFree virtual function is called to delete an object. Usually, the only
statement in the function is delete this. You must supply a refFree function
for each class derived from SSRefCount, either directly or through another base
class.

Signature

virtual void SSRefCount::refFree( void);

Example

This is the default SSYaccStackElement::refFree virtual function.

void SSYaccStackElement::refFree( void)
   {
   delete this;
   }


ΓòÉΓòÉΓòÉ 6.3. C ΓòÉΓòÉΓòÉ

 Concepts
 SSLex
 SSLexTable
 SSLexLexeme
 SSLexConsumer
 SSYacc
 SSYaccTable
 SSYaccStackElement
 SSException


ΓòÉΓòÉΓòÉ 6.3.1. Concepts ΓòÉΓòÉΓòÉ

The C functions are architecturally similar to their C++ cousins. Instead of
calling virtual functions to process actions, the C functions invoke callbacks
to do the work. There is an equivalent C callback for almost every C++ virtual
function. Usually, the only code you need to write is in the the reduce
function generated by Visual Parse++, as with the C++ bindings.

Perhaps the main difference lies in the application setup. For C++, application
setup is trivial, the constructors do most of the work. For C, you call Create
type functions to create the various pieces (consumer, lexer, etc.). Create
functions return a correlator or handle, which is required on other functions.
For instance, SSYaccCreate creates a parser, and returns a parser correlator.
Functions related to the parser require this correlator.  If a bad correlator
is detected, the default behavior is to abort. The
SSExceptionSetBadCorrelatorCallback function is provided to set a user supplied
bad correlator callback. This is useful during development. Your bad correlator
callback can issue some kind of diagnostic message before aborting. See
SSExceptionSetBadCorrelatorCallback for more information.


ΓòÉΓòÉΓòÉ 6.3.2. SSLex ΓòÉΓòÉΓòÉ

 Concepts
 SSLexClearLastException
 SSLexCreate
 SSLexDestroy
 SSLexGetNextLexeme
 SSLexGetLastException
 SSLexGotoExpressionList
 SSLexIsCurrentExpressionList
 SSLexPopExpressionList
 SSLexPushExpressionList
 SSLexReset
 SSLexSetLexemeExtra
 SSLexSetCompleteCallback
 SSLexSetErrorCallback


ΓòÉΓòÉΓòÉ 6.3.2.1. Concepts ΓòÉΓòÉΓòÉ

The SSLex functions create and control lexical analyzers. A lexical analyzer
requires two things to operate, a consumer correlator, and a lex table
correlator. The consumer correlator is created with the SSLexConsumerCreate or
SSLexFileConsumerCreate function. The table is created with the
SSLexTableCreate function.

There are two callbacks associated with a lexical analyzer, a
SSLexErrorCallback (error callback) and a SSLexCompleteCallback (complete
callback). Neither callback is required.

The error callback is invoked when an invalid lexeme is detected. It can ignore
the lexeme and continue, or repair and use the lexeme. The default callback
discards the lexeme and continues. Typically, the error callback will issue
some kind of diagnostic message and continue by ignoring the lexeme.

The complete callback is called each time a lexeme is recognized. You can
modify the lexeme, or terminate the lexical analyzer by returning SSFalse from
the complete callback. The main use of the complete callback is to examine
and/or modify a lexeme before it is passed to the parser. The default complete
callback returns SSTrue.


ΓòÉΓòÉΓòÉ 6.3.2.2. SSLexClearLastException ΓòÉΓòÉΓòÉ

The SSLexClearLastException clears any pending exceptions.

Signature

void SSLexClearLastException( void*);

 Parameters          Meaning

 void*               A lex correlator.

 Example

  SSLexClearLastException( zpLex);


ΓòÉΓòÉΓòÉ 6.3.2.3. SSLexCreate ΓòÉΓòÉΓòÉ

The SSLexCreate function creates a lexical analyzer.

Signature

void* SSLexCreate( void*, void*, void**);

 Parameters          Meaning

 void*               A consumer correlator.

 void*               A lex table correlator.

 void**              An address that is updated with an exception correlator if
                     an error occurs.

 Returns

 A lex correlator or 0. Zero indicates an error occurred, examine the returned
 exception correlator.

 Example

 Assume that zpTable contains a lex table correlator, and zpConsumer contains a
 consumer correlator.

  void* zpLex;
  void* zpException;

  zpLex = SSLexCreate( zpConsumer, zpTable, &zpException);
  if ( !zpLex)
     printf( "LexCreate failed %s", SSExceptionGetMessage( zpException));


ΓòÉΓòÉΓòÉ 6.3.2.4. SSLexDestroy ΓòÉΓòÉΓòÉ

The SSLexDestroy destroys a lexical analyzer.

Signature

void SSLexDestroy( void*);

 Parameters          Meaning

 void*               A lex correlator.

 Example

  SSLexDestroy( zpLex);


ΓòÉΓòÉΓòÉ 6.3.2.5. SSLexGetNextLexeme ΓòÉΓòÉΓòÉ

The SSLexGetNextLexeme function retrieves the next lexeme. This function is
used by standalone lexical analyzers to get lexemes, normally the parser
fetches lexemes.

Signature

void* SSLexGetNextLexeme( void*);

 Parameters          Meaning

 void*               A lex correlator.

 Returns

 A lexeme correlator or 0. Zero indicates end of data.

 Example

  void* zpLexeme;
  while ( zpLexeme = SSLexGetNextLexeme( zpLex))
     {
     /* Process lexeme */
     }


ΓòÉΓòÉΓòÉ 6.3.2.6. SSLexGetLastException ΓòÉΓòÉΓòÉ

The SSLexGetLastException function retrieves the last exception. This function
should be used when a lexer has terminated, to determine if an exception caused
the termination. SSException... functions can be used to get the error code and
error message associated with the exception.

Signature

void* SSLexGetNextLexeme( void*);

 Parameters          Meaning

 void*               A lex correlator.

 Returns

 An exception correlator or 0. Zero indicates that no exception occurred.

 Example

  void* zpLexeme;
  void* zpException;

  while ( zpLexeme = SSLexGetNextLexeme( zpLex))
     {
     /* Process lexeme */
     }

  if ( zpException = SSLexGetLastException( zpLex))
     {
     /* Process exception */
     }


ΓòÉΓòÉΓòÉ 6.3.2.7. SSLexGotoExpressionList ΓòÉΓòÉΓòÉ

The SSLexGotoExpressionList function pops and then pushes an expression list on
the expression list stack. It performs the exact same function as %goto does in
a rule file.

Signature

SSBooleanValue SSLexGotoExpressionList( void*, SSUnsigned32);

 Parameters          Meaning

 void*               A lex correlator.

 SSUnsigned32        An expression list identifier generated by Visual Parse++.

 Returns

 A success indication. SSTrue means the function failed, use
 SSLexGetLastException to determine the reason.

 Example

  #define SSLexExpressionListMain 0 /* Defined in header file */
  void* zpException;

  if ( SSLexGotoExpressionList( zpLex, SSLexExpressionListMain))
     {
     zpException = SSLexGetLastException( zpLex);
     printf( "Goto error, %s\n", SSExceptionGetMessage( zpException));
     }


ΓòÉΓòÉΓòÉ 6.3.2.8. SSLexIsCurrentExpressionList ΓòÉΓòÉΓòÉ

The SSLexIsCurrentExpressionList function queries the top of the expression
list stack.

Signature

SSBooleanValue SSLexIsCurrentExpressionList( void*, SSUnsigned32);

 Parameters          Meaning

 void*               A lex correlator.

 SSUnsigned32        An expression list identifier generated by Visual Parse++.

 Returns

 A success indication. SSTrue means the expression list is on top of the stack.

 Example

  #define SSLexExpressionListMain 0 /* Defined in header file */
  if ( SSLexIsCurrentExpressionList( zpLex, SSLexExpressionListMain))
     {
     /* Expression list Main is on top of the expression list stack */
     }


ΓòÉΓòÉΓòÉ 6.3.2.9. SSLexPopExpressionList ΓòÉΓòÉΓòÉ

The SSLexPopExpressionList function pops the top expression list of the
expression list stack. It performs the exact same function as %pop does in a
rule file.

Signature

SSBooleanValue SSLexPopExpressionList( void*);

 Parameters          Meaning

 void*               A lex correlator.

 Returns

 A success indication. SSTrue means the pop failed, use SSLexGetLastException
 to determine the reason.

 Example

  #define SSLexExpressionListMain 0 /* Defined in header file */
  void* zpException;

  if ( SSLexGotoExpressionList( zpLex, SSLexExpressionListMain))
     {
     zpException = SSLexGetLastException( zpLex);
     printf( "Pop error, %s\n", SSExceptionGetMessage( zpException));
     }


ΓòÉΓòÉΓòÉ 6.3.2.10. SSLexPushExpressionList ΓòÉΓòÉΓòÉ

The SSLexPushExpressionList function pushes an expression list on the
expression list stack. It performs the exact same function as %push does in a
rule file.

Signature

SSBooleanValue SSLexPushExpressionList( void*, SSUnsigned32);

 Parameters          Meaning

 void*               A lex correlator.

 SSUnsigned32        An expression list identifier generated by Visual Parse++.

 Returns

 A success indication. SSTrue means the function failed, use
 SSLexGetLastException to determine the reason.

 Example

  #define SSLexExpressionListMain 0 /* Defined in header file */
  void* zpException;

  if ( SSLexPushExpressionList( zpLex, SSLexExpressionListMain))
     {
     zpException = SSLexGetLastException( zpLex);
     printf( "Push error, %s\n", SSExceptionGetMessage( zpException));
     }


ΓòÉΓòÉΓòÉ 6.3.2.11. SSLexReset ΓòÉΓòÉΓòÉ

SSLexReset resets the lexer to its initial state.

Signature

void SSLexPushExpressionList( void*);

 Parameters          Meaning

 void*               A lex correlator.

 Example

  SSLexReset( zpLex);


ΓòÉΓòÉΓòÉ 6.3.2.12. SSLexSetLexemeExtra ΓòÉΓòÉΓòÉ

The SSLexSetLexemeExtra function sets the size of the area reserved for the
programmer's use in a lexeme, for lexemes that Visual Parse++ allocates. You
can access this area with the SSLexLexemeGetExtraLength and
SSLexLexemeGetExtraBuffer functions.

Signature

void SSLexSetLexemeExtra( void*, SSUnsigned32);

 Parameters          Meaning

 void*               A lex correlator.

 SSUnsigned32        The extra length.

 Example

  SSLexSetLexemeExtra( 16);


ΓòÉΓòÉΓòÉ 6.3.2.13. SSLexSetCompleteCallback ΓòÉΓòÉΓòÉ

The SSLexSetCompleteCallback function sets the complete callback. The complete
callback is called each time a lexeme is recognized. You can examine and/or
modify the lexeme and continue or terminate processing. The prototype of the
callback is discussed below.

Signature

void SSLexSetCompleteCallback( void*, SSLexCompleteCallback, void*);

 Parameters          Meaning

 void*               A lex correlator.

 SSLexCompleteCallback The callback address.

 void*               A parameter to pass to the callback.

 The callback function prototype looks like:

  SSBooleanValue callback( void*, void*, void*);

 Parameters          Meaning

 void*               A lex correlator.

 void*               A lexeme correlator.

 void*               The parameter specified on SSLexSetCompleteCallback.

 Returns

 A success indication. SSTrue means continue processing, SSFalse to terminate
 processing. If the parser invoked the lexer terminating processing will cause
 an end of data indication to be sent to the parser.

 Example

 Assume zpConsumer and zpTable contain a consumer and table correlator,
 respectively.

  void* zpLex = SSLexCreate( zpConsumer, zpTable);
  SSLexSetCompleteCallback( zpLex, MyCallback, 0);
  ┬╖
  ┬╖
  ┬╖
  SSRetBool MyCallback( void* qpLex, void* qpLexeme, void* qpParm)
     {
     /* examine and/or modify lexeme */
     return SSTrue; /* Continue normally */
     }


ΓòÉΓòÉΓòÉ 6.3.2.14. SSLexSetErrorCallback ΓòÉΓòÉΓòÉ

The SSLexSetErrorCallback function sets the error callback. The error callback
is called when an invalid lexeme is detected. You can examine and/or modify the
lexeme and continue processing or ignore the lexeme. The prototype of the
callback is discussed below.

Signature

void SSLexSetErrorCallback( void*, SSLexErrorCallback, void*);

 Parameters          Meaning

 void*               A lex correlator.

 SSLexErrorCallback  The callback address.

 void*               A parameter to pass to the callback.

 The callback function prototype looks like:

  SSBooleanValue callback( void*, void*, void*);

 Parameters          Meaning

 void*               A lex correlator.

 void*               The correlator of the invalid lexeme.

 void*               The parameter specified on SSLexSetErrorCallback.

 Returns

 A success indication. SSTrue means continue processing, SSFalse to ignore the
 lexeme and continue.

 Example

 Assume zpConsumer and zpTable contain a consumer and table correlator,
 respectively.

  void* zpLex = SSLexCreate( zpConsumer, zpTable);
  SSLexSetErrorCallback( zpLex, MyCallback, 0);
  ┬╖
  ┬╖
  ┬╖
  SSRetBool MyCallback( void* qpLex, void* qpLexeme, void* qpParm)
     {
     char* zpchBuff = ( char*) SSLexLexemeGetBuffer( qpLexeme);
     SSUnsigned32 zulLine = SSLexLexemeGetLine( qpLexeme);
     SSUnsigned32 zulOffset = SSLexLexemeGetOffset( qpLexeme);
     printf( "Invalid lexeme %s, on line %d at offset %d\n", zpchBuff,
        zulLine, zulOffet);
     return SSFalse; /* Ignore lexeme */
     }


ΓòÉΓòÉΓòÉ 6.3.3. SSLexTable ΓòÉΓòÉΓòÉ

 Concepts
 SSLexTableCreate
 SSLexTableDestroy


ΓòÉΓòÉΓòÉ 6.3.3.1. Concepts ΓòÉΓòÉΓòÉ

The SSLexTable functions create and destroy lexical analyzer tables. They
correspond to the C++ SSLexTable class.


ΓòÉΓòÉΓòÉ 6.3.3.2. SSLexTableCreate ΓòÉΓòÉΓòÉ

The SSLexTableCreate function creates a lexical analyzer table.

Signature

void* SSLexTableCreate( const char*, void**);

 Parameters          Meaning

 const char*         The table name.

 void**              An address that is updated with an exception correlator if
                     an exception occurs.

 Returns

 A lex table correlator or 0. If zero is returned, examine the exception
 correlator to determine the cause of the error.

 Example

  void* zpTable;
  void* zpException;

  zpTable = SSLexTableCreate( "table.dfa", &zpException);
  if ( !zpTable)
     printf( "SSLexTableCreate failed %s", SSExceptionGetMessage( zpException));


ΓòÉΓòÉΓòÉ 6.3.3.3. SSLexTableDestroy ΓòÉΓòÉΓòÉ

SSLexTableDestroy destroys a lexical analyzer table.

Signature

void SSLexTableDestroy( void*);

 Parameters          Meaning

 void*               A lex table correlator.

 Example

  SSLexTableDestroy( zpTable);


ΓòÉΓòÉΓòÉ 6.3.4. SSLexLexeme ΓòÉΓòÉΓòÉ

 Concepts
 SSLexLexemeCreate
 SSLexLexemeDestroy
 SSLexLexemeGetBuffer
 SSLexLexemeGetExtraBuffer
 SSLexLexemeGetExtraLength
 SSLexLexemeGetLength
 SSLexLexemeGetLine
 SSLexLexemeGetOffset
 SSLexLexemeGetToken
 SSLexLexemeGetType
 SSLexLexemeRefInc
 SSLexLexemeRefDec
 SSLexLexemeSetBuffer
 SSLexLexemeSetLength
 SSLexLexemeSetLine
 SSLexLexemeSetOffset
 SSLexLexemeSetToken
 SSLexLexemeSetType


ΓòÉΓòÉΓòÉ 6.3.4.1. Concepts ΓòÉΓòÉΓòÉ

The SSLexLexeme functions create and operate on lexemes. They correspond to the
C++ SSLexLexeme class.


ΓòÉΓòÉΓòÉ 6.3.4.2. SSLexLexemeCreate ΓòÉΓòÉΓòÉ

The SSLexLexemeCreate function creates a lexeme. The data specified is copied
to the lexeme (and null terminated for your convenience). The SSLexLexemeSet...
functions can be used to update the lexeme parameters (type, token, etc.). This
function is mainly supplied for programmers using the SSYaccNextLexemeCallback.
Normally, you let Visual Parse++ allocate lexemes for you.

Signature

void* SSLexLexemeCreate( void*, SSUnsigned32, SSUnsigned32, void**);

 Parameters          Meaning

 void*               A data pointer.

 SSUnsigned32        The data length.

 SSUnsigned32        The extra length allocated in the lexeme, but reserved for
                     the programmer's use.

 void**              An address that is updated with an exception correlator if
                     an exception occurs.

 Returns

 A lexeme correlator or 0. If zero is returned, examine the exception
 correlator to determine the cause of the error.

 Example

  void* zpLexeme;
  void* zpException;

  zpLexeme = SSLexLexemeCreate( "Data", strlen( "Data"), 0, &zpException);
  if ( !zpLexeme)
     printf( "SSLexLexemeCreate failed %s", SSExceptionGetMessage( zpException));


ΓòÉΓòÉΓòÉ 6.3.4.3. SSLexLexemeDestroy ΓòÉΓòÉΓòÉ

The SSLexLexemeDestroy function destroys a lexeme. If you are using a parser,
use this function with extreme caution, if at all. Reference counting is used
to control the lifetimes of lexemes, issuing this function could free a lexeme
that is in use by Visual Parse++. This function is only required for standalone
lexical analyzers.

Signature

void SSLexLexemeCreate( void*);

 Parameters          Meaning

 void*               A lexeme correlator.


ΓòÉΓòÉΓòÉ 6.3.4.4. SSLexLexemeGetBuffer ΓòÉΓòÉΓòÉ

The SSLexLexemeGetBuffer returns the buffer pointer. Lexeme buffers are null
terminated, so C string functions can be used.

Signature

void* SSLexLexemeGetBuffer( void*);

 Parameters          Meaning

 void*               A lexeme correlator.

 Returns

 The buffer pointer.

 Example

  void* zpBuff = SSLexLexemeGetBuffer( zpLexeme);


ΓòÉΓòÉΓòÉ 6.3.4.5. SSLexLexemeGetExtraBuffer ΓòÉΓòÉΓòÉ

The SSLexLexemeGetExtraBuffer returns the extra buffer pointer. This is the
area reserved in the lexeme for the programmer's use.

Signature

void* SSLexLexemeGetExtraBuffer( void*);

 Parameters          Meaning

 void*               A lexeme correlator.

 Returns

 The buffer pointer.

 Example

  void* zpBuff = SSLexLexemeGetExtraBuffer( zpLexeme);


ΓòÉΓòÉΓòÉ 6.3.4.6. SSLexLexemeGetExtraLength ΓòÉΓòÉΓòÉ

The SSLexLexemeGetExtraLength function returns the extra buffer length. It was
set on SSLexLexemeCreate or SSLexSetLexemeExtra function.

Signature

SSUnsigned32 SSLexLexemeGetExtraLength( void*);

 Parameters          Meaning

 void*               A lexeme correlator.

 Returns

 The extra buffer length.

 Example

  SSUnsigned32 zulLen = SSLexLexemeGetExtraLength( zpLexeme);


ΓòÉΓòÉΓòÉ 6.3.4.7. SSLexLexemeGetLength ΓòÉΓòÉΓòÉ

The SSLexLexemeGetLength function returns the buffer length.

Signature

SSUnsigned32 SSLexLexemeGetLength( void*);

 Parameters          Meaning

 void*               A lexeme correlator.

 Returns

 The buffer length.

 Example

  SSUnsigned32 zulLen = SSLexLexemeGetLength( zpLexeme);


ΓòÉΓòÉΓòÉ 6.3.4.8. SSLexLexemeGetLine ΓòÉΓòÉΓòÉ

The SSLexLexemeGetLine function returns the line number.

Signature

SSUnsigned32 SSLexLexemeGetLine( void*);

 Parameters          Meaning

 void*               A lexeme correlator.

 Returns

 The line number.

 Example

  SSUnsigned32 zulLine = SSLexLexemeGetLine( zpLexeme);


ΓòÉΓòÉΓòÉ 6.3.4.9. SSLexLexemeGetOffset ΓòÉΓòÉΓòÉ

The SSLexLexemeGetOffset function returns the line offset.

Signature

SSUnsigned32 SSLexLexemeGetLength( void*);

 Parameters          Meaning

 void*               A lexeme correlator.

 Returns

 The line offset.

 Example

  SSUnsigned32 zulOffset = SSLexLexemeGetOffset( zpLexeme);


ΓòÉΓòÉΓòÉ 6.3.4.10. SSLexLexemeGetToken ΓòÉΓòÉΓòÉ

The SSLexLexemeGetToken function returns the token number.

Signature

SSUnsigned32 SSLexLexemeGetToken( void*);

 Parameters          Meaning

 void*               A lexeme correlator.

 Returns

 The token number.

 Example

  SSUnsigned32 zulToken = SSLexLexemeGetToken( zpLexeme);


ΓòÉΓòÉΓòÉ 6.3.4.11. SSLexLexemeGetType ΓòÉΓòÉΓòÉ

The SSLexLexemeGetType function returns the lexeme type, either
SSLexLexemeTypeDBCS or SSLexLexemeTypeUnicode. These symbols are defined in
sslexc.h.

Signature

SSUnsigned32 SSLexLexemeGetType( void*);

 Parameters          Meaning

 void*               A lexeme correlator.

 Returns

 The type.

 Example

  SSUnsigned32 zulType = SSLexLexemeGetType( zpLexeme);


ΓòÉΓòÉΓòÉ 6.3.4.12. SSLexLexemeRefInc ΓòÉΓòÉΓòÉ

SSLexLexemeRefInc increments the reference count for the lexeme. The lexeme
will not be released until the reference count is 0. This function is useful
for extending the lifetime of a lexeme. Normally, lexemes are deleted after a
reduce has been performed by the parser, use this function if you want access
to the lexeme after this point. When you are through with the lexeme, use
SSLexLexemeRefDec to release the lexeme.

Signature

void SSLexLexemeRefInc( void*);

 Parameters          Meaning

 void*               A lexeme correlator.

 Example

  SSLexLexemeRefInc( zpLexeme);


ΓòÉΓòÉΓòÉ 6.3.4.13. SSLexLexemeRefDec ΓòÉΓòÉΓòÉ

SSLexLexemeRefDec decrements the reference count for the lexeme. The lexeme
will not be released until the reference count is 0. Only use SSLexLexemeRefDec
if SSLexLexemeRefInc was used to increment the lexeme.

Signature

SSBooleanValue SSLexLexemeRefDec( void*);

 Parameters          Meaning

 void*               A lexeme correlator.

 Returns

 SSTrue indicates that the reference count was already 0. You didn't issue a
 SSLexLexemeRefInc for this lexeme.

 Example

  SSLexLexemeRefDec( zpLexeme);


ΓòÉΓòÉΓòÉ 6.3.4.14. SSLexLexemeSetBuffer ΓòÉΓòÉΓòÉ

The SSLexLexemeSetBuffer sets the buffer pointer. This function is rarely
required, SSLexLexemeCreate or Visual Parse++ usually handles lexeme buffers.

Signature

void SSLexLexemeSetBuffer( void*);

 Parameters          Meaning

 void*               The buffer pointer.


ΓòÉΓòÉΓòÉ 6.3.4.15. SSLexLexemeSetLength ΓòÉΓòÉΓòÉ

The SSLexLexemeSetLength function sets the buffer length. This function is
rarely required, SSLexLexemeCreate or Visual Parse++ usually sets the buffer
length.

Signature

void SSLexLexemeSetLength( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The length.


ΓòÉΓòÉΓòÉ 6.3.4.16. SSLexLexemeSetLine ΓòÉΓòÉΓòÉ

The SSLexLexemeSetLine function sets the line number.

Signature

void SSLexLexemeSetLine( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        A line number.

  SSLexLexemeSetLine( 15);


ΓòÉΓòÉΓòÉ 6.3.4.17. SSLexLexemeSetOffset ΓòÉΓòÉΓòÉ

The SSLexLexemeSetOffset function sets the line offset.

Signature

void SSLexLexemeSetOffset( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        The line offset.

 Example

  SSLexLexemeSetOffset( 55);


ΓòÉΓòÉΓòÉ 6.3.4.18. SSLexLexemeSetToken ΓòÉΓòÉΓòÉ

The SSLexLexemeSetToken function sets the token number.

Signature

void SSLexLexemeSetToken( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        A token number.

 Example

  SSLexLexemeSetToken( 2);


ΓòÉΓòÉΓòÉ 6.3.4.19. SSLexLexemeSetType ΓòÉΓòÉΓòÉ

The SSLexLexemeSetType function sets the lexeme type, either
SSLexLexemeTypeDBCS or SSLexLexemeTypeUnicode. These symbols are defined in
sslexc.h.

Signature

void SSLexLexemeSetType( SSUnsigned32);

 Parameters          Meaning

 SSUnsigned32        Either SSLexLexemeTypeDBCS or SSLexLexemeTypeUnicode.

 Example

  SSLexLexemeSetType( SSLexLexemeTypeDBCS);


ΓòÉΓòÉΓòÉ 6.3.5. SSLexConsumer ΓòÉΓòÉΓòÉ

 Concepts
 SSLexConsumerCreate
 SSLexFileConsumerCreate
 SSLexFileConsumerGetFile
 SSLexFileConsumerCloseFile
 SSLexConsumerDestroy
 SSLexConsumerSetNextBufferCallback


ΓòÉΓòÉΓòÉ 6.3.5.1. Concepts ΓòÉΓòÉΓòÉ

Consumers represent data that is processed by lexical analyzers. Each lexical
analyzer requires a consumer to operate. SSLexConsumer functions provide access
to consumers.

There is one callback of interest to the programmer, a next buffer callback.
The next buffer callback is not required, either a file consumer can be used,
or all the data can be passed on SSLexConsumerCreate.

The next buffer callback is set with SSLexConsumerSetNextBufferCallback
function. The next buffer callback is invoked when more data is needed. It is
passed a buffer address and length as parameters, and fills in the specified
area with data. When end of data is reached, the next buffer callback returns
0.


ΓòÉΓòÉΓòÉ 6.3.5.2. SSLexConsumerCreate ΓòÉΓòÉΓòÉ

The SSLexConsumerCreate function creates a consumer. The data supplied is
copied to the consumer buffer.

Signature

void* SSLexConsumerCreate( void*, SSUnsigned32, SSUnsigned32,
   SSUnsigned32, void**);

 Parameters          Meaning

 void*               A buffer pointer.

 SSUnsigned32        The buffer length.

 SSUnsigned32        The consumer type, either SSLexConsumerTypeBinary,
                     SSLexConsumerTypeUnicode, or SSLexConsumerTypeCharacter.
                     The binary type doesn't check for DBCS characters.

 SSUnsigned32        The buffer increment. A value that will be used to expand
                     the buffer, if necessary. If this value is 0, the largest
                     lexeme that will be excepted is determined by the initial
                     buffer length.

 void**              An address that is updated with an exception correlator if
                     an exception occurs.

 Returns

 A consumer correlator or 0. If zero is returned, examine the exception
 correlator to determine the cause of the error.

 Example

  void* zpConsumer;
  void* zpException;

  zpConsumer = SSLexConsumerCreate( "Data", strlen( "Data"),
     SSLexConsumerTypeBinary, 0, &zpException);
  if ( !zpConsumer)
     printf( "SSLexConsumerCreate failed %s", SSExceptionGetMessage( zpException));


ΓòÉΓòÉΓòÉ 6.3.5.3. SSLexFileConsumerCreate ΓòÉΓòÉΓòÉ

The SSLexFileConsumerCreate function creates a file consumer.

Signature

void* SSLexConsumerFileCreate( const char*, SSUnsigned32, SSUnsigned32,
   SSUnsigned32, void**);

 Parameters          Meaning

 const char*         A file name.

 SSUnsigned32        The buffer size that is allocated. SSLexConsumerAll
                     allocates a buffer the same size as the file.

 SSUnsigned32        The buffer increment. A value that will be used to expand
                     the buffer, if necessary. If this value is 0, the largest
                     lexeme that will be excepted is determined by the initial
                     buffer length.

 SSUnsigned32        The consumer type, either SSLexConsumerTypeBinary,
                     SSLexConsumerTypeUnicode, or SSLexConsumerTypeCharacter.
                     The binary type doesn't check for DBCS characters and the
                     file is opened rb.

 void**              An address that is updated with an exception correlator if
                     an exception occurs.

 Returns

 A consumer correlator or 0. If zero is returned, examine the exception
 correlator to determine the cause of the error.

 Example

  void* zpConsumer;
  void* zpException;

  zpConsumer = SSLexFileConsumerCreate( "file.name", SSLexConsumerAll, 0,
     SSLexConsumerTypeCharacter, &zpException);
  if ( !zpConsumer)
     printf( "SSLexFileConsumerCreate failed %s", SSExceptionGetMessage( zpException));


ΓòÉΓòÉΓòÉ 6.3.5.4. SSLexFileConsumerGetFile ΓòÉΓòÉΓòÉ

SSLexFileConsumerGetFile returns the file pointer as a FILE*.

Signature

FILE* SSLexFileConsumerGetFile( void*);

 Parameters          Meaning

 void*               A consumer correlator.

 Returns

 The file pointer.

 Example

  FILE* zpFile = SSLexFileConsumerGetFile( zpConsumer);


ΓòÉΓòÉΓòÉ 6.3.5.5. SSLexFileConsumerCloseFile ΓòÉΓòÉΓòÉ

SSLexFileConsumerCloseFile closes the file associated with the consumer. Do not
close a file that is currently in use.

Signature

void SSLexFileConsumerCloseFile( void*);

 Parameters          Meaning

 void*               A consumer correlator.

 Example

  SSLexFileConsumerCloseFile( zpConsumer);


ΓòÉΓòÉΓòÉ 6.3.5.6. SSLexConsumerDestroy ΓòÉΓòÉΓòÉ

SSLexConsumerDestroy destroys a consumer. Do not destroy a consumer that is
currently in use.

Signature

void SSLexConsumerDestroy( void*);

 Parameters          Meaning

 void*               A consumer correlator.

 Example

  SSLexConsumerDestroy( zpConsumer);


ΓòÉΓòÉΓòÉ 6.3.5.7. SSLexConsumerSetNextBufferCallback ΓòÉΓòÉΓòÉ

SSLexConsumerSetNextBufferCallback sets the next buffer callback. The next
buffer callback is invoked when more data is needed by the lexical analyzer.
The prototype is described below.

Signature

void SSLexConsumerSetNextBufferCallback( void*,
   SSLexConsumerNextBufferCallback, void*);

 Parameters          Meaning

 void*               A consumer correlator.

 SSLexConsumerNextBufferCallback The callback address.

 void*               A parameter that is passed to the callback.

 The callback fills in a buffer passed by Visual Parse++, and returns the
 length of the data. The callback prototype looks like:

  SSUnsigned32 callback( void*, void*, SSUnsigned32, void*);

 Parameters          Meaning

 void*               The consumer correlator.

 void*               The buffer pointer.

 SSUnsigned32        The buffer length.

 void*               The parameter specified when setting the callback.

 Returns

 The length of the data put in the buffer. Zero means end of data.

 Example

  SSLexConsumerSetNextBufferCallback( zpConsumer, MyCallback, 0);
  ┬╖
  ┬╖
  ┬╖
  SSRetUnsigned32 MyCallback( void* qpConsumer, void* qpBuff,
     SSUnsigned32 qulLen, void* qpParm)
     {
     /* Fill qpBuff with up to qpLen bytes */
     return /* Filled length or 0 for end of data */
     }


ΓòÉΓòÉΓòÉ 6.3.6. SSYacc ΓòÉΓòÉΓòÉ

 Concepts
 SSYaccClearLastException
 SSYaccCreate
 SSYaccDestroy
 SSYaccFreeValidLookaheads
 SSYaccGetAbort
 SSYaccGetElementFromProduction
 SSYaccGetElementFromStack
 SSYaccGetError
 SSYaccGetLastException
 SSYaccGetShiftedSinceError
 SSYaccGetValidLookaheads
 SSYaccParse
 SSYaccProcessError
 SSYaccReset
 SSYaccSetAbort
 SSYaccSetErrorCallback
 SSYaccSetNextLexemeCallback
 SSYaccSetShiftCallback


ΓòÉΓòÉΓòÉ 6.3.6.1. Concepts ΓòÉΓòÉΓòÉ

The SSYacc functions create and control parsers. A parser requires two things
to operate, a lexer (created with SSLexCreate), and a parse table (created with
SSYaccTableCreate).

There are four callback functions that you can use when writing a parser, the
next lexeme callback, the shift callback, the reduce callback, and the error
callback.

The next lexeme callback (set with SSYaccSetNextLexemeCallback) is called when
a lexeme is needed. The default callback gets the next lexeme from the lexer.
Use this callback if you want to supply lexemes from your own source. The next
lexeme callback is not required.

The shift callback (set with SSYaccSetShiftCallback) is called when a lexeme is
shifted on the stack. The default callback returns a stack element. The shift
callback is not required.

The reduce callback is called each time a production is reduced. A skeleton
reduce callback is generated in the C header file for each rule file. This is
where you put the application code for your parser. This callback is required
on the SSYaccCreate function.

The error callback (set with SSYaccSetErrorCallback) is called when a parsing
error occurs. The default callback invokes the Visual Parse++ error recovery
procedure (described in Error Recovery). Typically you will supply an error
callback that will issue some type of diagnostic message, and then invoke
SSYaccProcessError to attempt to recover from the error.


ΓòÉΓòÉΓòÉ 6.3.6.2. SSYaccTableClearLastException ΓòÉΓòÉΓòÉ

The SSYaccClearLastException function clears any pending exceptions.

Signature

void SSYaccTableCreate( void*);

 Parameters          Meaning

 void*               A parser correlator.

 Example

  SSYaccClearLastException( zpYacc);


ΓòÉΓòÉΓòÉ 6.3.6.3. SSYaccCreate ΓòÉΓòÉΓòÉ

The SSYaccCreate function creates a parser. Parsing is initiated with the
SSYaccParse function.

Signature

void* SSYaccTableCreate( void*, void*, SSYaccReduceCallback,
   void*, SSUnsigned32, void**);

 Parameters          Meaning

 void*               A lex correlator.

 void*               A parse table correlator.

 SSYaccReduceCallback The reduce callback address. The prototype is described
                     below.

 void*               A user parameter to pass to the reduce callback.

 SSUnsigned32        The size of the user defined area that will be reserved in
                     stack elements created by Visual Parse++.

 void**              An address that is updated with an exception correlator if
                     an exception occurs.

 Returns

 A parser correlator or 0. If zero is returned, examine the exception
 correlator to determine the cause of the error.

 The prototype of the reduce callback is:

  void* reduce( void*, SSUnsigned32, SSUnsigned32, void*);

 Parameters          Meaning

 void*               The parse correlator.

 SSUnsigned32        The production number.

 SSUnsigned32        The production size.

 void*               The user parameter specified on SSYaccCreate.

 Returns

 A stack element correlator allocated with the SSYaccStackElementCreate
 function.

 Example

 Assume zpLex and zpTable contain a lex correlator and a parse table
 correlator, respectively.

  void* zpYacc;
  void* zpException;

  zpYacc = SSYaccCreate( zpLex, zpTable, AReduceFunction, 0, 0, &zpException);
  if ( !zpYacc)
     {
     printf( "SSYaccCreate failed %s", SSExceptionGetMessage( zpException));
     return
  ┬╖
  ┬╖
  ┬╖
  SSRetVoidP AReduceFunction( void* qpYacc, SSUnsigned32 qulProd,
     SSUnsigned32 qulSize)
     {
     /* Process reduce */
  ┬╖
  ┬╖
  ┬╖
     return SSYaccStackElementCreate( 0, 0);
     }


ΓòÉΓòÉΓòÉ 6.3.6.4. SSYaccDestroy ΓòÉΓòÉΓòÉ

SSYaccDestroy destroys a parser.

Signature

void SSYaccDestroy( void*);

 Parameters          Meaning

 void*               A parser correlator.

 Example

  SSYaccDestroy( zpYacc);


ΓòÉΓòÉΓòÉ 6.3.6.5. SSYaccFreeValidLookaheads ΓòÉΓòÉΓòÉ

SSYaccFreeValidLookaheads frees the valid lookahead array returned by
SSYaccGetValidLookaheads

Signature

void SSYaccFreeValidLookaheads( SSUnsigned32*);

 Parameters          Meaning

 SSUnsigned32*       A lookahead array address.

 Example

  SSYaccFreeValidLookaheads( zpulLook);


ΓòÉΓòÉΓòÉ 6.3.6.6. SSYaccGetAbort ΓòÉΓòÉΓòÉ

SSYaccGetAbort gets the abort code. The abort code is set with SSYaccSetAbort.

Signature

SSBooleanValue SSYaccGetAbort( void*);

 Parameters          Meaning

 void*               A parse correlator.

 Returns

 SSTrue indicates that the parsing process was aborted with SSYaccSetAbort.

 Example

  SSBooleanValue zAbort = SSYaccGetAbort( zpYacc);
  if ( zAbort)
     {
     /* Parser aborted */
     }


ΓòÉΓòÉΓòÉ 6.3.6.7. SSYaccGetElementFromProduction ΓòÉΓòÉΓòÉ

SSYaccGetElementFromProduction gets a stack element. This function is only
valid in a reduce callback. The element retrieved is relative to the current
production being reduced. The index is 0 based, i.e., 0 will get the stack
element associated with the first symbol on the right hand side of the
production.

Note

A negative index can be used.

Signature

void* SSYaccGetElementFromProduction( void*, SSSigned32);

 Parameters          Meaning

 void*               A parse correlator.

 SSUnsigned32        The index.

 Returns

 A stack element correlator or 0. If zero, an invalid index was passed.

 Example

 Assume that the following example is a case statement in a reduce function,
 and qpYacc contains a parse correlator.

  case MyProd0:
  /* MyProd0 -> Symbol0 Symbol1 */
     {
     void* zpElement0;
     void* zpElement1;

     zpElement0 = SSYaccGetElementFromProduction( qpYacc, 0);
     zpElement1 = SSYaccGetElementFromProduction( qpYacc, 1);
     }


ΓòÉΓòÉΓòÉ 6.3.6.8. SSYaccGetElementFromStack ΓòÉΓòÉΓòÉ

SSYaccGetElementFromStack gets a stack element. The element retrieved is
relative to the top of the stack. The top of the stack is index 0.

Signature

void* SSYaccGetElementFromStack( void*, SSUnsigned32);

 Parameters          Meaning

 void*               A parse correlator.

 SSUnsigned32        The index.

 Returns

 A stack element correlator or 0. If zero, an invalid index was passed.

 Example

 Assume that qpYacc contains a parse correlator.

     void* zpElement0 = SSYaccGetElementFromStack( qpYacc, 0);
     /* Get the top stack element */
     }


ΓòÉΓòÉΓòÉ 6.3.6.9. SSYaccGetError ΓòÉΓòÉΓòÉ

SSYaccGetError gets the error code. The error code is set to SSTrue if a
parsing error occurs.

Note

This is the same value returned by the SSYaccParse function.

Signature

SSBooleanValue SSYaccGetError( void*);

 Parameters          Meaning

 void*               A parse correlator.

 Returns

 SSTrue indicates that the an error occurred.

 Example

  SSBooleanValue zError = SSYaccGetError( zpYacc);
  if ( zError)
     {
     /* Parser aborted */
     }


ΓòÉΓòÉΓòÉ 6.3.6.10. SSYaccGetLastException ΓòÉΓòÉΓòÉ

SSYaccGetLastException gets the last exception associated with the parser.
Functions such as SSYaccParse and SSYaccProcessError can terminate and allocate
an exception correlator which you can retrieve with this function.

Note

It is a good idea to check for pending exceptions after SSYaccParse has
completed.

Signature

void* SSYaccGetLastException( void*);

 Parameters          Meaning

 void*               A parse correlator.

 Returns

 An exception correlator or 0. Zero indicates there is no pending exception.

 Example

  void* zpException;
  SSYaccParse( zpYacc);
  zpException = SSYaccGetLastException( zpYacc);
  if ( zpException)
     printf( "Parse exception: %s\n", SSExceptionGetMessage( zpException));


ΓòÉΓòÉΓòÉ 6.3.6.11. SSYaccGetShiftedSinceError ΓòÉΓòÉΓòÉ

SSYaccGetShiftedSinceError gets the number of tokens shifted since the last
error. It can be useful to check the number in your error callback to prevent
cascading errors. If the number is not greater than say, three, you can abort
the parse with SSYaccSetAbort.

Signature

SSUnsigned32 SSYaccGetShiftedSinceError( void*);

 Parameters          Meaning

 void*               A parse correlator.

 Returns

 The number of tokens shifted since the last error.

 Example

  SSUnsigned32 zulShift = SSYaccGetShiftedSinceError( zpYacc);


ΓòÉΓòÉΓòÉ 6.3.6.12. SSYaccGetValidLookaheads ΓòÉΓòÉΓòÉ

SSYaccGetValidLookaheads returns an array of valid tokens given a state. This
function, along with the xxxTokenToConstChar function generated in the header
file, is useful for generating an error message. When an error occurs, the
valid lookaheads for the error state can be obtained with this function. The
token strings can be accessed with the xxxTokenToConstChar function to create
an accurate diagnostic message.

Signature

SSUnsigned32* SSYaccGetValidLookaheads( void*, SSUnsigned32,
   SSUnsigned32*);

 Parameters          Meaning

 void*               A parse correlator.

 SSUnsigned32        A state.

 SSUnsigned32*       A pointer to a value that will be updated with the number
                     of tokens in the returned array.

 Returns

 The token array.

 Example Assume qulState contains the state, and qpYacc contains the parser
 correlator. The TokenToConstChar function name is prefixed with a user
 specified string in the header file, but here, the name TokenToConstChar will
 be used.

  char achMsg[ 256];
  strcpy( achMsg, "Expected ");
  SSSigned32 zulLen = 255;
  zulLen -= strlen( "Expected ");
  SSUnsigned32 zulNum;
  SSUnsigned32* zpValid = SSYaccGetValidLookaheads( qpYacc, qulState, &zulNum);
  for ( int i = 0; i < zulNum; i++)
     {
     char* zpchToken = TokenToConstChar( zpValid[ i]);
     zlLen -= strlen( zpchToken);
     if ( zlLen <= 0) break;
     strcat( achMsg, zpchToken);
     if ( i < zulNum - 1)
        strcat( achMsg, ",");
     }
  SSYaccFreeValidLookaheads( zpValid);


ΓòÉΓòÉΓòÉ 6.3.6.13. SSYaccParse ΓòÉΓòÉΓòÉ

SSYaccParse starts the parsing process. The data is parsed, and the appropriate
callbacks are invoked as events occur.

Note

It is a good idea to check for exceptions after parsing has completed.

Signature

SSBooleanValue SSYaccParse( void*);

 Parameters          Meaning

 void*               A parse correlator.

 Returns

 SSTrue if an error occured while parsing.

 Example

  void* zpException;
  SSBooleanValue zParse = SSYaccParse( zpYacc);
  zpException = SSYaccGetLastException( zpYacc);
  if ( zParse || zpException)
     {
     printf( "Error during parse: %d\n", zParse);
     if ( zpException)
        printf( "Exception: %s\n", SSExceptionGetMessage( zpException));
     }


ΓòÉΓòÉΓòÉ 6.3.6.14. SSYaccProcessError ΓòÉΓòÉΓòÉ

SSYaccProcessError invokes Error Recovery. Usually, this function is called in
the error callback after the error has been recorded.

Signature

SSBooleanValue SSYaccProcessError( void*);

 Parameters          Meaning

 void*               A parse correlator.

 Returns

 SSTrue if an error occured while parsing. You can use SSYaccGetLastException
 to get more information about the error.

 Example

 This is what a typical error callback looks like:

  SSBooleanValue error( void* qpYacc, SSUnsigned32 qulState, void* qpLexeme)
     {
     /* Record error */
     return SSYaccProcessError( qpYacc);
     }


ΓòÉΓòÉΓòÉ 6.3.6.15. SSYaccReset ΓòÉΓòÉΓòÉ

SSYaccProcessReset resets the parser to its initial state.

Signature

void SSYaccReset( void*);

 Parameters          Meaning

 void*               A parse correlator.


ΓòÉΓòÉΓòÉ 6.3.6.16. SSYaccSetAbort ΓòÉΓòÉΓòÉ

SSYaccSetAbort aborts the parsing process. Use this function in a shift, error,
or reduce callback to terminate parsing.

Signature

void SSYaccSetAbort( void*);

 Parameters          Meaning

 void*               A parse correlator.

 Example

  SSYaccSetAbort( zpYacc);


ΓòÉΓòÉΓòÉ 6.3.6.17. SSYaccSetErrorCallback ΓòÉΓòÉΓòÉ

SSYaccSetErrorCallback sets the error callback. The error callback is invoked
when a parsing error occurs.

Signature

void SSYaccSetErrorCallback( void*, SSYaccErrorCallback, void*);

 Parameters          Meaning

 void*               A parse correlator.

 SSYaccErrorCallback The callback address. The prototype is described below.

 void*               A user parameter to pass to the callback.

 This is the error callback prototype:

  void* callback( void*, void*, SSUnsigned32, void*);

 Parameters          Meaning

 void*               The parser correlator.

 void*               The lexeme correlator of the lookahead symbol.

 SSUnsigned32        The state.

 void*               A user parameter specified on SSYaccSetErrorCallback.

 Returns

 SSTrue indicates that recovery failed, and parsing is to terminate. Usually,
 you return the value of SSYaccProcessError, see the example below.

 Example

  SSYaccSetErrorCallback( zpYacc, MyCallback, 0);
  ┬╖
  ┬╖
  ┬╖
  SSRetVoidP MyCallback( void* qpYacc, void* qpLexeme,
     SSUnsigned32 qulState, void* qpParm)
     {
     /* Record error */
     return SSYaccProcessError( qpYacc);
     }


ΓòÉΓòÉΓòÉ 6.3.6.18. SSYaccSetNextLexemeCallback ΓòÉΓòÉΓòÉ

SSYaccSetNextLexemeCallback sets the next lexeme callback. The next lexeme
callback is invoked when a lexeme is needed. This callback is only required if
you want to get lexemes from a source other than a lexer.

Signature

void SSYaccSetNextLexemeCallback( void*, SSYaccNextLexemeCallback, void*);

 Parameters          Meaning

 void*               A parse correlator.

 SSYaccNextLexemeCallback The callback address. The prototype is described
                     below.

 void*               A user parameter to pass to the callback.

 This is the next lexeme callback prototype:

  void* callback( void*, void*);

 Parameters          Meaning

 void*               The parser correlator.

 void*               A user parameter specified on SSYaccSetNextLexemeCallback.

 Returns

 A lexeme correlator allocated with SSLexLexemeCreate. Zero indicates end of
 data.

 Example

  SSYaccSetNextLexemeCallback( zpYacc, MyCallback, 0);
  ┬╖
  ┬╖
  ┬╖
  SSRetVoidP MyCallback( void* qpYacc, void* qpParm)
     {
     /* Set up SSLexLexemeCreate */
     if ( endOfData)
        return 0;
     else
        return SSLexLexemeCreate( ...
     }


ΓòÉΓòÉΓòÉ 6.3.6.19. SSYaccSetShiftCallback ΓòÉΓòÉΓòÉ

SSYaccSetShiftCallback sets the shift callback. The shift callback is invoked
before each lexeme is shifted on the stack.

Signature

void SSYaccSetShiftCallback( void*, SSYaccShiftCallback, void*);

 Parameters          Meaning

 void*               A parse correlator.

 SSYaccShiftCallback The callback address. The prototype is described below.

 void*               A user parameter to pass to the callback.

 This is the shift callback prototype:

  void* callback( void*, void*, void*);

 Parameters          Meaning

 void*               The parser correlator.

 void*               The lexeme correlator of the lexeme about to get shifted.

 void*               A user parameter specified on SSYaccSetShiftCallback.

 Returns

 A stack element correlator allocated with SSYaccStackElementCreate. Zero
 indicates that parsing should terminate.

 Example

  SSYaccSetShiftCallback( zpYacc, MyCallback, 0);
  ┬╖
  ┬╖
  ┬╖
  SSRetVoidP MyCallback( void* qpYacc, void* qpLexeme, void* qpParm)
     {
     void* zpElement = SSYaccStackElementCreate( 0, 0);
     /* Set up stack element */
     return zpElement;
     }


ΓòÉΓòÉΓòÉ 6.3.7. SSYaccTable ΓòÉΓòÉΓòÉ

 Concepts
 SSYaccTableCreate
 SSYaccTableDestroy


ΓòÉΓòÉΓòÉ 6.3.7.1. Concepts ΓòÉΓòÉΓòÉ

The SSYaccTable functions create and destroy parser tables. They correspond to
the C++ SSYaccTable class.


ΓòÉΓòÉΓòÉ 6.3.7.2. SSYaccTableCreate ΓòÉΓòÉΓòÉ

The SSYaccTableCreate function creates a parser table.

Signature

void* SSYaccTableCreate( const char*, void**);

 Parameters          Meaning

 const char*         The table name.

 void**              An address that is updated with an exception correlator if
                     an exception occurs.

 Returns

 A parse table correlator or 0. If zero is returned, examine the exception
 correlator to determine the cause of the error.

 Example

  void* zpTable;
  void* zpException;

  zpTable = SSYaccTableCreate( "table.llr", &zpException);
  if ( !zpTable)
     printf( "SSYaccTableCreate failed %s", SSExceptionGetMessage( zpException));


ΓòÉΓòÉΓòÉ 6.3.7.3. SSYaccTableDestroy ΓòÉΓòÉΓòÉ

SSYaccTableDestroy destroys a parse table.

Signature

void SSYaccTableDestroy( void*);

 Parameters          Meaning

 void*               A parse table correlator.

 Example

  SSYaccTableDestroy( zpTable);


ΓòÉΓòÉΓòÉ 6.3.8. SSYaccStackElement ΓòÉΓòÉΓòÉ

 Concepts
 SSYaccStackElementCreate
 SSYaccStackElementDestroy
 SSYaccStackElementGetExtra
 SSYaccStackElementGetLexeme
 SSYaccStackElementGetState
 SSYaccStackElementSetLexeme
 SSYaccStackElementSetState


ΓòÉΓòÉΓòÉ 6.3.8.1. Concepts ΓòÉΓòÉΓòÉ

The SSYaccStackElement functions create and provide access to parse stack
elements.


ΓòÉΓòÉΓòÉ 6.3.8.2. SSYaccStackElementCreate ΓòÉΓòÉΓòÉ

The SSYaccStackElementCreate function creates a stack element. This function is
used in the shift or reduce callback to allocate and return a stack element.

Signature

void* SSYaccStackElementCreate( SSUnsigned32, void**);

 Parameters          Meaning

 SSUnsigned32        The size of an area to reserve for the programmer's use.
                     This area is retrieved with the SSYaccStackElementGetExtra
                     function.

 void**              An address that is updated with an exception correlator if
                     an exception occurs.

 Returns

 A stack element correlator or 0. If zero is returned, examine the exception
 correlator to determine the cause of the error.

 Example

  void* zpElement;
  void* zpException;

  /* Reserve 16 bytes in element */
  zpElement = SSYaccTableCreate( 16, &zpException);
  if ( !zpElement)
     printf( "SSYaccStackElementCreate failed %s",
        SSExceptionGetMessage( zpException));


ΓòÉΓòÉΓòÉ 6.3.8.3. SSYaccStackElementDestroy ΓòÉΓòÉΓòÉ

SSYaccStackElementDestroy destroys a stack element. Use this function with
extreme caution, if at all. Stack elements are shared between Visual Parse++
and your application code, destroying a stack element may release an element
that is currently in use. Normally, Visual Parse++ destroys stack elements.

Signature

void SSYaccStackElementDestroy( void*);

 Parameters          Meaning

 void*               A stack element correlator.


ΓòÉΓòÉΓòÉ 6.3.8.4. SSYaccStackElementGetExtra ΓòÉΓòÉΓòÉ

SSYaccStackElementGetExtra returns the address of the area in the stack element
reserved for the programmer's use. This size of this area was specified with
SSYaccStackElementCreate.

Signature

void* SSYaccStackElementGetExtra( void*);

 Parameters          Meaning

 void*               A stack element correlator.

 Returns

 A pointer to the reserved area.

 Example

  void* zpArea = SSYaccStackElementGetExtra( zpElement);


ΓòÉΓòÉΓòÉ 6.3.8.5. SSYaccStackElementGetLexeme ΓòÉΓòÉΓòÉ

SSYaccStackElementGetLexeme returns the lexeme correlator associated with the
stack element.

Signature

void* SSYaccStackElementGetLexeme( void*);

 Parameters          Meaning

 void*               A stack element correlator.

 Returns

 A lexeme correlator or 0. Zero indicates that there is no lexeme associated
 with this stack element.

 Example

  void* zpLexeme = SSYaccStackElementGetLexeme( zpElement);


ΓòÉΓòÉΓòÉ 6.3.8.6. SSYaccStackElementGetState ΓòÉΓòÉΓòÉ

SSYaccStackElementGetState returns the state associated with the stack element.

Signature

SSUnsigned32 SSYaccStackElementGetState( void*);

 Parameters          Meaning

 void*               A stack element correlator.

 Returns

 A state associated with the lexeme.

 Example

  SSUnsigned32 zulState = SSYaccStackElementGetState( zpElement);


ΓòÉΓòÉΓòÉ 6.3.8.7. SSYaccStackElementSetLexeme ΓòÉΓòÉΓòÉ

SSYaccStackElementSetLexeme sets the lexeme associated with the stack element.

Signature

void SSYaccStackElementSetLexeme( void*, void*);

 Parameters          Meaning

 void*               A stack element correlator.

 void*               A lexeme correlator.

 Example

  SSYaccStackElementSetLexeme( zpElement, zpLexeme);


ΓòÉΓòÉΓòÉ 6.3.8.8. SSYaccStackElementSetState ΓòÉΓòÉΓòÉ

SSYaccStackElementSetState sets the state associated with the stack element.
Use this function with extreme caution, if at all. The state contained in a
stack element is crucial to the parsing process.

Signature

void SSYaccStackElementSetState( void*, SSUnsigned32);

 Parameters          Meaning

 void*               A stack element correlator.

 SSUnsigned32        The state.


ΓòÉΓòÉΓòÉ 6.3.9. SSException ΓòÉΓòÉΓòÉ

 Concepts
 SSExceptionDestroy
 SSExceptionGetErrorId
 SSExceptionGetMessage
 SSExceptionSetBadCorrelatorCallback


ΓòÉΓòÉΓòÉ 6.3.9.1. Concepts ΓòÉΓòÉΓòÉ

The SSException functions get information related to exception correlators.
Exception correlators are created by Visual Parse++ when errors occur.

The function SSExceptionSetBadCorrelatorCallback sets a user defined function
that is invoked when a bad correlator is detected. The default bad correlator
callback issues an abort. Override this function if you want to issue a
disgnostic message before aborting.


ΓòÉΓòÉΓòÉ 6.3.9.2. SSExceptionDestroy ΓòÉΓòÉΓòÉ

SSExceptionDestroy destroys an exception correlator.

Signature

void SSExceptionDestroy( void*);

 Parameters          Meaning

 void*               An exception correlator.

  SSExceptionDestroy( zpException);


ΓòÉΓòÉΓòÉ 6.3.9.3. SSExceptionGetErrorId ΓòÉΓòÉΓòÉ

SSExceptionGetErrorId returns the error id for the exception.

Signature

SSUnsigned32 SSExceptionGetErrorId( void*);

 Parameters          Meaning

 void*               An exception correlator.

 Returns

 The error id.

 Example

  SSUnsigned32 zulId = SSExceptionGetErrorId( zpException);


ΓòÉΓòÉΓòÉ 6.3.9.4. SSExceptionGetMessage ΓòÉΓòÉΓòÉ

SSExceptionGetMessage returns the message for the exception.

Signature

const char* SSExceptionGetMessage( void*);

 Parameters          Meaning

 void*               An exception correlator.

 Returns

 The error message.

 Example

  const char* zpszMsg = SSExceptionGetMessage( zpException);


ΓòÉΓòÉΓòÉ 6.3.9.5. SSExceptionSetBadCorrelatorCallback ΓòÉΓòÉΓòÉ

SSExceptionSetBadCorrelatorCallback sets the bad correlator callback. The
callback is invoked when a bad correlator is detected.

Signature

void SSExceptionSetBadCorrelatorCallback(
   SSExceptionBadCorrelatorCallback, void*);

 Parameters          Meaning

 SSExceptionBadCorrelatorCallback The function address. The prototype is:

  void callback( void*, const char*, void*);

 Parameters          Meaning

 void*               The bad correlator.

 const char*         A 4 character correlator id, indicating which correlator
                     was invalid. These are the valid id's:

    SSEX  An exception correlator.

    SSLT  An lex table correlator.

    SSCO  An consumer correlator.

    SSLM  An lexeme correlator.

    SSLX  An lex correlator.

    SSYT  An parse table correlator.

    SSSE  An stack element correlator.

    SSYC  An parse correlator.

 void*               The user parameter passed when setting the callback.

 Example

  SSExceptionSetBadCorrelatorCallback( MyCallback, 0);
  ┬╖
  ┬╖
  ┬╖
  SSRetVoid MyCallback( void* qpCorr, const char* qpchId, void* qpParm)
     {
     printf( "Bad correlator: %.4s\n", qpchId);


ΓòÉΓòÉΓòÉ 6.4. REXX ΓòÉΓòÉΓòÉ

 Concepts
 SSLex
 SSYacc


ΓòÉΓòÉΓòÉ 6.4.1. Concepts ΓòÉΓòÉΓòÉ

The REXX functions allow you to write a complete parser in REXX. This can be
very useful, due to the string-oriented nature of REXX, and the fact that the
REXX supplied parsing functions are very weak.

The REXX bindings depart from the parser/callback or object/virtual function
architecture of the C and C++ bindings. This is beacuse of some limitations in
REXX related to variable pools, i.e., they are not shared.

What this means to you, the programmer, is nothing. Instead of the common code
being hidden in a library as in C or C++, you see and have access to the REXX
code that performs the same function. Except under unusual circumstances, you
should never have to concern yourself with the details.

As usual, the main function of interest is the reduce function generated by
Visual Parse++. This is where you put your application code to process the
reductions as they occur, and is about the only area in the REXX file that you
will make any changes (other than on SSLexCreate, which specifies the data that
is to be parsed).

Like the C functions, the REXX Create functions return a correlator or handle
which is used on subsequent function calls to request services. A bad
correlator will cause a return code 40, which drives the 'on syntax' signal.
The skeleton parser generated by Visual Parse++ contains appropriate signal
handling to catch this case and issue an error message. Other errors are
indicated in the same way. For all errors, the SSRESULT variable is updated
with a detailed error message.


ΓòÉΓòÉΓòÉ 6.4.2. SSLex ΓòÉΓòÉΓòÉ

 Concepts
 SSLexAddData
 SSLexCreate
 SSLexGetNextLexeme
 SSLexDestroy


ΓòÉΓòÉΓòÉ 6.4.2.1. Concepts ΓòÉΓòÉΓòÉ

The SSLex functions create and control lexical analyzers.


ΓòÉΓòÉΓòÉ 6.4.2.2. SSLexAddData ΓòÉΓòÉΓòÉ

SSLexAddData adds data to a lexical analyzer. This function is only valid when
SSMORE is returned by either the SSLexGetNextLexeme or SSYaccParse function.
The data specified is added to the lexer's internal buffer. If you do not add
data in response to SSMORE, end of data is assumed.

Signature

ok SSLexAddData( lexCorrelator, data)

 Parameters          Meaning

 lexCorrelator       The lex correlator returned by SSLexCreate.

 data                The data to add to the buffer.

 Returns

 Normally, SSOK. The syntax signal handler is driven if an error occurs. The
 variable SSRESULT is updated with the reason for the failure.

 Example

  ret = SSLexAddData( lexCorr, 'new data')


ΓòÉΓòÉΓòÉ 6.4.2.3. SSLexCreate ΓòÉΓòÉΓòÉ

SSLexCreate creates a lexical analyzer.

Signature

lexCorr SSLexCreate( varTable, varConsumer, type)

 Parameters          Meaning

 varTable            The lex table name.

 varConsumer         Either a file name or data, see the type parameter.

 type                The consumer type, one of SSFILE, SSQUERY, or SSBUFFER.
                     SSFILE indicates that varConsumer contains a file name.
                     SSQUERY means that varConsumer contains data, and that the
                     SSMORE return code is to br returned from SSYaccParse when
                     more data is needed. SSBUFFER indicates that varConsumer
                     contains a single string of data. The SSMORE return code
                     is never returned if SSBUFFER or SSFILE is specified.

 Returns

 The lex correlator. The syntax signal handler is driven if an error occurs.
 The variable SSRESULT is updated with the reason for the failure.

 Example

  lexCorr = SSLexCreate( 'table.dfa', 'file.name', SSFILE)


ΓòÉΓòÉΓòÉ 6.4.2.4. SSLexGetNextLexeme ΓòÉΓòÉΓòÉ

SSLexGetNextLexeme retrieves lexemes. This function is used as the driver for
standalone lexical analyzers, similar to the way SSYaccParse is used. The
driver code is generated by Visual Parse++ for rule files that do not contain a
%production section. The driver code looks like:

do forever
   SSRet = SSLexGetNextLexeme( lexCorr, SSParm)
   select
      when SSRet = SSOK then
         /* Lexeme returned */
      when SSRet = SSDONE then
         /* Finished */
         leave
      when SSRet = SSMORE then
         /* Get more data */
      when SSRet = SSLEXERROR
         /* Invalid lexeme */
   end
end

SSOK indicates that a lexeme has been recognized. The stem variable (SSParm in
this case) is used as a compound variable stem to return the lexeme parameters.
A lexeme has four parameters:

 var.0     The lexeme.

 var.1     The token number.

 var.2     The line number.

 var.3     The line offset.

 SSDONE means lexing is finished, and the do loop is exited.

 SSMORE indicates that more data is needed. If you reissue SSLexGetNextLexeme
 without issuing the SSLexAddData function, end of data is assumed.

 SSLEXERROR indicates an invalid lexeme was detected. The lexeme parameters are
 returned, but the token index (index 1) is invalid, because the token could
 not be determined. If you continue, the lexeme is discarded.

 Signature

  ret SSLexGetNextLexeme( lexCorrelator, stem)

 Parameters          Meaning

 lexCorrelator       The lex correlator returned by SSLexCreate.

 stem                The stem used to construct the returned compound
                     variables.

 Returns

 Normally, SSOK. The syntax signal handler is driven if an error occurs. The
 variable SSRESULT is updated with the reason for the failure.


ΓòÉΓòÉΓòÉ 6.4.2.5. SSLexDestroy ΓòÉΓòÉΓòÉ

SSLexDestroy destroys a lexical analyzer.

Signature

ok SSLexDestroy( lexCorrelator)

 Parameters          Meaning

 lexCorrelator       The lex correlator.

 Returns

 Normally SSOK. The syntax signal handler is driven if an error occurs. The
 variable SSRESULT is updated with the reason for the failure.

 Example

  ret = SSLexDestroy( lexCorr)


ΓòÉΓòÉΓòÉ 6.4.3. SSYacc ΓòÉΓòÉΓòÉ

 Concepts
 SSYaccChangeToken
 SSYaccCreate
 SSYaccDestroy
 SSYaccGetStackParmsFromProduction
 SSYaccParse
 SSYaccSetStackParm


ΓòÉΓòÉΓòÉ 6.4.3.1. Concepts ΓòÉΓòÉΓòÉ

The SSYacc functions create and control parsers.


ΓòÉΓòÉΓòÉ 6.4.3.2. SSYaccChangeToken ΓòÉΓòÉΓòÉ

SSYaccChangeToken is used to change a token number in a lexeme before it is
passed to the parser for processing. This function is only valid when SSOK is
returned from SSYaccParse. SSOK is returned when a lexeme is recognized, but
before it is passed to the parser.

Signature

ok SSYaccChangeToken( parseCorrelator, token)

 Parameters          Meaning

 parseCorrelator     The parser correlator returned by SSYaccCreate.

 token               The new token number.

 Returns

 Normally, SSOK. The syntax signal handler is driven if an error occurs. The
 variable SSRESULT is updated with the reason for the failure.

 Example

  ret = SSYaccChangeToken( parseCorr, 23)


ΓòÉΓòÉΓòÉ 6.4.3.3. SSYaccCreate ΓòÉΓòÉΓòÉ

SSYaccCreate creates a parser.

Signature

parseCorr SSYaccCreate( lexCorr, table)

 Parameters          Meaning

 lexCorr             A lex correlator.

 varTable            The parse table name.

 Returns

 The parse correlator. The syntax signal handler is driven if an error occurs.
 The variable SSRESULT is updated with the reason for the failure.

 Example

  parseCorr = SSYaccCreate( lexCorr, 'table.llr')


ΓòÉΓòÉΓòÉ 6.4.3.4. SSYaccDestroy ΓòÉΓòÉΓòÉ

SSYaccDestory destroys a parser.

Signature

ok SSYaccDestroy( parseCorr)

 Parameters          Meaning

 parseCorr           A parse correlator.

 Returns

 Normally, SSOK. The syntax signal handler is driven if an error occurs. The
 variable SSRESULT is updated with the reason for the failure.

 Example

  ret = SSYaccDestroy( parseCorr)


ΓòÉΓòÉΓòÉ 6.4.3.5. SSYaccGetStackParmsFromProduction ΓòÉΓòÉΓòÉ

SSYaccGetStackParmsFromProduction retrieves the stack parameters associated
with the supplied production index. This function is only valid in the reduce
internal function generated by Visual Parse++.

The index refers to a symbol in the production, and is 0 based (0 is the first
symbol on the righthand side).

The variable stem is used to construct compound variables containing the stack
parameters. The variables are:

 var.0     The lexeme.

 var.1     The token number.

 var.2     The line number.

 var.3     The line offset.

 var.4     The stack parameter.

 Note that indices 0-3 are the lexeme parameters returned on the SSYaccParse
 and SSLexGetNextLexeme functions. The stack parameter is passed from a
 previous reduction and is set with the SSYaccSetStackParm function.

 Signature

  ok SSYaccGetStackParmsFromProduction( parseCorr, index, stem)

 Parameters          Meaning

 parseCorr           A parser correlator.

 index               The production index.

 stem                The variable stem used to construct the returned compound
                     variables.

 Returns

 Normally SSOK. The syntax signal handler is driven if an error occurs. The
 variable SSRESULT is updated with the reason for the failure.

 Example

 For a detailed example, see sscalcrx.cmd in \SAMPLES\SSCALC.

  ret = SSYaccGetStackParmsFromProduction( parseCorr, 0, SSParm)


ΓòÉΓòÉΓòÉ 6.4.3.6. SSYaccParse ΓòÉΓòÉΓòÉ

SSYaccParse invokes the parser. This function is the driver for the parsing
process. The return values from SSYaccParse indicate which action to take. You
can view parser drivers in any Visual Parse++ generated REXX file. The parser
driver looks like:

do forever
   SSRet = SSYaccParse( parseCorr, SSParm)
   select
      when SSRet = SSOK then
         /* Lexeme recognized */
      when SSRet = SSMORE then
         /* Get more data */
      when SSRet = SSSHIFT then
         /* Shift occurred */
      when SSRet = SSREDUCE then
         /* Process reduce */
      when SSRet = SSACCEPT then
         /* Accepted */
      when SSRet = SSLEXERROR then
         /* Lexeme error */
      when SSRet = SSYACCERROR then
         /* Parse error */
   end
end

SSOK indicates that a lexeme has been recognized. The stem is used to construct
compound variables that contain the lexeme parameters. The variables are:

 var.0     The lexeme.

 var.1     The token number.

 var.2     The line number.

 var.3     The line offset.

 SSMORE indicates that more data is needed. You will only get this return value
 if the SSLexCreate function used the SSQUERY parameter. You can add data with
 the SSLexAddData function. If no data is added, end of data is assumed.

 SSSHIFT is returned when a token is shifted on the stack. The lexeme
 parameters are returned as with SSOK.

 SSREDUCE is returned when a reduction is taking place. The internal reduce
 subroutine, generated by Visual Parse++, is called to process the reduction.

 SSLEXERROR indicates that an invalid lexeme was detected. The variables
 mentioned in the SSOK section are updated with the lexeme parameters, but the
 token number is not valid, because it could not be determined. If you
 continue, the lexeme is ignored.

 SSYACCERROR is returned when a parsing error occurs. If you continue, an
 attempt to recover is made. If recovery fails, SSPERMERROR is returned.

 SSPERMERROR indicates that a permanent error has occurred. Usually, this is
 the result of an unrecoverable parsing error. Any additional processing
 results in SSPERMERROR return values.

 Signature

  ret SSYaccParse( parseCorr, stem)

 Parameters          Meaning

 parseCorr           A parse correlator.

 stem                A compound variable stem.

 Returns

 See the description above for possible return values. The syntax signal
 handler is driven if an error occurs. The variable SSRESULT is updated with
 the reason for the failure.

 Example

 See any Visual Parse++ generated file.


ΓòÉΓòÉΓòÉ 6.4.3.7. SSYaccSetStackParm ΓòÉΓòÉΓòÉ

SSYaccSetStackParm sets the stack parameter that is pushed on the stack as a
result of a reduction. This function is only valid when SSREDUCE is returned by
SSYaccParse, in the reduce internal function generated by Visual Parse++. The
stack parameter is pushed on the stack after the righthand side of the
production is popped (this is what a reduction does). The stack parameter is
retrieved with the SSYaccGetStackParmsFromProduction function.

Signature

ok SSYaccSetStackParm( parseCorr, parm)

 Parameters          Meaning

 parseCorr           A parse correlator.

 parm                The parameter.

 Returns

 Normally, SSOK. The syntax signal handler is driven if an error occurs. The
 variable SSRESULT is updated with the reason for the failure.

 Example

 For a detailed example, see sscalcrx.cmd in \SAMPLES\SSCALC.

  ret = SSYaccSetStackParm( parseCorr, 'some parameter')


ΓòÉΓòÉΓòÉ 7. Command Line Parser ΓòÉΓòÉΓòÉ

 Concepts
 C++ Bindings
 C Bindings


ΓòÉΓòÉΓòÉ 7.1. Concepts ΓòÉΓòÉΓòÉ

The command line parser provides a set of easy to use services to parse a
command line. C and C++ bindings are provided. The syntax of a command line
accepted by the supplied bindings is:

command [ options ] list, ...

 Parameter      Meaning

 command        The command name.

 options        The options.

 parameter      A list of parameters.

 Each option has syntax:

  (-|/)option[ (+|-) ][ ]parameter

 In words, options are preceded by either a '-' or a '/' and followed by an
 optional '+' or '-'.  If the '+' or '-' is missing, '+' is assumed. If the
 parameter is optional, it must be concatenated on the end of the option string
 (without the '+' sign). If it is required, there can be intervening white
 space.

 An arbitrary number of parameters can follow the options.

 Note This is the same syntax that the Visual Parse++ commands accept.

 Two options are added by the bindings, the /H and /P options.

 The /H (help)  option prints a list of valid options based on information
 supplied through the bindings. As you specify options with the bindings
 (described later), you supply a description. The /H option writes this
 information to either stdout or a programmer supplied file name. The output
 looks like:

  command [options] parms

     -Opt1   Opt1 Description
     -Opt2   Opt2 Description
     -Opt3   Opt3 Description
     ┬╖
     ┬╖
     ┬╖

 The /P (print) option prints a list of the options that were specified on the
 command line. The output goes to stdout or a programmer supplied file name.
 The output looks like:

  command

     -Opt1  Opt(0 or 1) Parm(parm)
     -Opt2  Opt(0 or 1) Parm(parm)
     -Opt3  Opt(0 or 1) Parm(parm)
     ┬╖
     ┬╖
     ┬╖
     Parm(parm1)
     Parm(parm2)
     Parm(parm3)
     ┬╖
     ┬╖
     ┬╖

 The Opt field gives the - (0) or + (1) information, and the Parm field shows
 the parameters associated with the option (if any). The options list is
 followed by the list of parameters specified on the command.


ΓòÉΓòÉΓòÉ 7.2. C++ Bindings ΓòÉΓòÉΓòÉ

 Concepts
 SSComlin
 SSComlinOption


ΓòÉΓòÉΓòÉ 7.2.1. Concepts ΓòÉΓòÉΓòÉ

The command line C++ bindings provide an easy to use interface for parsing a
command line. There are two classes of interest, SSComlin and SSComlinOption.

SSComlin is the command line anchor to which SSComlinOption instances are
attached. After attaching all the options, the parse member function is invoked
to process the command line. SSComlin and SSComlinOption member functions are
provided to retrieve the paramters associated with the options, and determining
option characteristics (like if the option was specified).

Here is a small example that parses a command line expecting options 'A', 'B',
and 'C':

#include<sscomlin.hpp>
int main( int qiArg, char** qapszArg)
   {
   SSComlin zCom( "Command", qiArg, qapszArg, "Desc", 0, 0);
   SSComlinOption zOptA( zCom, "A", "A Desc", SSFalse, SSComlinOption::none);
   SSComlinOption zOptB( zCom, "B", "B Desc", SSFalse, SSComlinOption::required);
   SSComlinOption zOptC( zCom, "C", "C Desc", SSFalse, SSComlinOption::optional);

   try
      {
      zCom.parse();
      }
   catch ( SSException zExcept)
      {
      /* Command line error */
      }

   cout << "Option A(" << zOptA.isPlus() << ") Parm(" << zOptA.parm() << ")\n";
   cout << "Option B(" << zOptB.isPlus() << ") Parm(" << zOptB.parm() << ")\n";
   cout << "Option C(" << zOptC.isPlus() << ") Parm(" << zOptC.parm() << ")\n";
   return 0;
   }

The header file is sscomlin.hpp.


ΓòÉΓòÉΓòÉ 7.2.2. SSComlin ΓòÉΓòÉΓòÉ

 Constructors
 getParms
 parse
 printFormat
 printParms


ΓòÉΓòÉΓòÉ 7.2.2.1. Constructors ΓòÉΓòÉΓòÉ

Signature

SSComlin::SSComlin( const char*, int, const char**,
   const char*, const char* = 0, const char* = 0)

 Parameters          Meaning

 const char*         The command name.

 int                 The number of parameters passed on the command line. This
                     is the same parameter passed to the main function.

 const char**        The array of command line parameters. This is the same
                     parameter passed to the main function.

 const char*         The description. Shown if the /H option is specified.

 const char*         A file name or 0. Zero indicates that the output from the
                     /H option, the /P option, and any error messages are
                     written to stdout. Otherwise, this parameter is
                     interpreted as a file name in which the output is written.

 const char*         The path containing the sscomlin.dfa and sscomlin.llr
                     tables. The path name must end in a '\' character.
                     Internally, Visual Parse++ just appends the table names on
                     this string.

 Example

  int main( int qiArg, char** qapszArg)
     {
     SSComlin zComlin( "Command", qiArg, qapszArg, "Description",
        0, "\\mypath\\");


ΓòÉΓòÉΓòÉ 7.2.2.2. getParms ΓòÉΓòÉΓòÉ

The getParms functions gets the list of parameters specified on the command
line. These are the parameters not associated with an option. Use this function
after the parse function to retrieve the command line parameters.

Signature

const char** SSComlin::getParms( SSUnsigned32&)

 Parameters          Meaning

 SSUnsigned32&       A reference that is updated with the number of parameters
                     in the returned array.

 Returns

 An array of pointers to the parameters.

 Example

  SSUnsigned32 zCount;
  const char** zppParms = qComlin.getParms( zCount);


ΓòÉΓòÉΓòÉ 7.2.2.3. parse ΓòÉΓòÉΓòÉ

The parse functions parses the command line. Use this function after you have
add your options with the SSComlinOption class.

Signature

void SSComlin::parse( void)

Returns

Throws an SSException if an error occurs.

Example

SSComlin zComlin( ...
┬╖
┬╖
┬╖
try
   {
   zComlin.parse();
   }
catch ( SSException zExcept)
   {
   ┬╖
   ┬╖
   ┬╖
   }


ΓòÉΓòÉΓòÉ 7.2.2.4. printFormat ΓòÉΓòÉΓòÉ

The printFormat functions prints the command line format. The /H option prints
the same output.

Signature

void SSComlin::printFormat( SSBooleanValue = SSFalse)

 Parameters          Meaning

 SSBooleanValue      SSTrue means to unconditionally print the help
                     information, SSFalse to print the information only if the
                     /H option was specified.

 Example

  int main( int qiArg, const char** qapszArg)
     {
     SSComlin zComlin( ...
     ┬╖
     ┬╖
     ┬╖
     if ( qiArg < xxxxx)
        {
        zComlin.printFormat( SSTrue);
        return 1;
        }


ΓòÉΓòÉΓòÉ 7.2.2.5. printParms ΓòÉΓòÉΓòÉ

The printParms functions prints the command parameters. The /P option prints
the same output.

Signature

void SSComlin::printParms( SSBooleanValue = SSFalse)

 Parameters          Meaning

 SSBooleanValue      SSTrue means to unconditionally print the information,
                     SSFalse to print the information only if the /P option was
                     specified.

 Example

  int main( int qiArg, const char** qapszArg)
     {
     SSComlin zComlin( ...
     ┬╖
     ┬╖
     ┬╖
     zComlin.parse();
  #  if degugging
     zComlin.printParms( SSTrue);
  #  endif


ΓòÉΓòÉΓòÉ 7.2.3. SSComlinOption ΓòÉΓòÉΓòÉ

 Constructors
 isMinus
 isPlus
 parm


ΓòÉΓòÉΓòÉ 7.2.3.1. Constructors ΓòÉΓòÉΓòÉ

Signature

SSComlinOption::SSComlinOption( SSComlin&, const char*,
   const char*, SSBooleanValue, SSComlinOptionType)

 Parameters          Meaning

 SSComlin&           The SSComlin anchor.

 const char*         The option.

 const char*         The option description printed with the /H option.

 SSBooleanValue      The default value. The value is retrieved with the isPlus
                     and isMinus functions. The default value is returned when
                     the option is not specified.

 SSComlinOptionType  The type, either none, required, or optional. The type
                     specifies whether a parameter is not required, required,
                     or optional, respectively.

 An SSException is thrown if an error occurs, like a duplicate option.

 Example

  SSComlin zCom;
  SSComlinOption zOptA( zCom, "A", "A Desc", SSFalse, SSComlinOption::none);
  SSComlinOption zOptB( zCom, "B", "B Desc", SSFalse, SSComlinOption::optional);
  SSComlinOption zOptC( zCom, "C", "C Desc", SSFalse, SSComlinOption::required);

  try
     {
     zCom.parse();
     }
  catch ( SSException zExcept)
     {
     /* Error parsing command */
     }

  /* Get parameters */


ΓòÉΓòÉΓòÉ 7.2.3.2. isMinus ΓòÉΓòÉΓòÉ

The isMinus functions returns the option value.

Signature

SSBooleanValue SSComlinOption::isMinus( void)

Returns

SSTrue if the value was '-', SSFalse if the valus was '+'.

Example

if ( zOptA.isMinus())
   /* Option A is '-' */


ΓòÉΓòÉΓòÉ 7.2.3.3. isPlus ΓòÉΓòÉΓòÉ

The isPlus functions returns the option value.

Signature

SSBooleanValue SSComlinOption::isPlus( void)

Returns

SSTrue if the value was '+', SSFalse if the valus was '-'.

Example

if ( zOptA.isPlus())
   /* Option A is '+' */


ΓòÉΓòÉΓòÉ 7.2.3.4. parm ΓòÉΓòÉΓòÉ

The parm functions returns the parameter associated with the option.

Signature

const char* SSComlinOption::parm( void)

Returns

The parameter or 0.

Example

const char* zpParm = zOptA.parm();


ΓòÉΓòÉΓòÉ 7.3. C Bindings ΓòÉΓòÉΓòÉ

 Concepts
 SSComlinCreate
 SSComlinDestroy
 SSComlinGetParms
 SSComlinParse
 SSComlinPrintFormat
 SSComlinPrintParms
 SSComlinOptionCreate
 SSComlinOptionGetParm
 SSComlinOptionGetValue


ΓòÉΓòÉΓòÉ 7.3.1. Concepts ΓòÉΓòÉΓòÉ

The command line C bindings provide a set of services for specifying the
options, parsing, and retrieving parameters on an arbitrary command line. Here
is a small example:

#include<sscomlin.h>
int main( int qiArg, char** qapszArg)
   {
   void* zpCom;
   void* zpOptA;
   void* zpOptB;
   void* zpOptC;
   void* zpExcept = 0;

   zpCom = SSComlinCreate( "Command", qiArg, qapszArg, "Desc",
      0, 0, &zpExcept);

   zpOptA = SSComlinOptionCreate( zpCom, "A", "A Desc", SSTrue,
      SSComlinOptionNone, &zpExcept);
   zpOptB = SSComlinOptionCreate( zpCom, "B", "B Desc", SSTrue,
      SSComlinOptionRequired, &zpExcept);
   zpOptC = SSComlinOptionCreate( zpCom, "C", "C Desc", SSTrue,
      SSComlinOptionOptional, &zpExcept);

   zpExcept = SSComlinParse( zpCom);
   if ( zpExcept)
      /* Command line error */

   printf( "OptA(%d) Parm(%s)\n", SSComlinOptionGetValue( zpOptA),
      SSComlinOptionGetParm( zpOptA));
   printf( "OptB(%d) Parm(%s)\n", SSComlinOptionGetValue( zpOptB),
      SSComlinOptionGetParm( zpOptB));
   printf( "OptC(%d) Parm(%s)\n", SSComlinOptionGetValue( zpOptC),
      SSComlinOptionGetParm( zpOptC));

   SSComlinDestroy( zpCom);
   return 0;
   }

The header file is sscomlin.h.


ΓòÉΓòÉΓòÉ 7.3.2. SSComlinCreate ΓòÉΓòÉΓòÉ

SSComlinCreate creates the command line anchor. Command line options created
with the SSComlinOptionCreate function are attached to the command line, then
the SSComlinParse function is called to process the command line.

Signature

void* SSComlinCreate( const char*, int, const char**, const char*,
   const char*, const char*, void**);

 Parameters          Meaning

 const char*         The command name.

 int                 The number of parameters. This is the same parameter
                     passed on the main function.

 const char**        The parameter array. This is the same parameter passed on
                     the main function.

 const char*         The command description.

 const char*         A file name or 0. This parameter indicates where output
                     from the /H option, the /P option, or error messages are
                     written. Zero specifies stdout, otherwise the data is
                     written to the file name specified.

 const char*         The path name containing the sscomlin.dfa and sscomlin.llr
                     files. The path name must end with a '\' character (if it
                     is supplied). Internally, Visual Parse++ concatentates the
                     table names on the end of the path name. If 0, the tables
                     must be in the current directory.

 void**              A pointer that will be updated with an exception
                     correlator if an exception occurs.

 Returns

 A command line correlator or 0. If zero, examine the exception correlator to
 determine the cause of the error.

 Example

  void* zpExcept;
  void* zpCom = SSComlinCreate( "Command", qiArg, qapszArg, "Desc",
     0, 0, &zpExcept);


ΓòÉΓòÉΓòÉ 7.3.3. SSComlinDestroy ΓòÉΓòÉΓòÉ

SSComlinDestroy destroys a command line correlator.

Signature

void SSComlinDestroy( void*);

 Parameters          Meaning

 void*               The command line correlator.

 Example

  SSComlinDestory( zpCom);


ΓòÉΓòÉΓòÉ 7.3.4. SSComlinGetParms ΓòÉΓòÉΓòÉ

SSComlinGetParms retrieves the parameters specified after the options. Use this
function after SSComlinParse.

Signature

const char** SSComlinDestroy( void*, SSUnsigned32*);

 Parameters          Meaning

 void*               The command line correlator.

 SSUnsigned32*       The address of a variable that is updated with the number
                     of parameters in the returned array.

 Returns

 The parameter array.

 Example

  SSUnsigned32 zulCount;
  const char** zppParms = SSComlinGetParms( zpCom, &zulCount);


ΓòÉΓòÉΓòÉ 7.3.5. SSComlinParse ΓòÉΓòÉΓòÉ

SSComlinParse parses the command line.

Signature

void* SSComlinParse( void*);

 Parameters          Meaning

 void*               The command line correlator.

 Returns

 An exception correlator or 0. Zero indicates success. If non-zero, examine the
 exception correlator to determine the cause of the error.

 Example

  void* zpExcept = SSComlinParse( zpCom);


ΓòÉΓòÉΓòÉ 7.3.6. SSComlinPrintFormat ΓòÉΓòÉΓòÉ

SSComlinPrintFormat prints the command line format. The /H option prints the
same output.

Signature

void SSComlinPrintFormat( void*)

 Parameters          Meaning

 void*               A command line correlator.

 Example

  int main( int qiArg, const char** qapszArg)
     {
     void* zpCom = SSComlinCreate( ...
     ┬╖
     ┬╖
     ┬╖
     if ( qiArg < xxxxx)
        {
        SSComlinPrintFormat( zpCom);
        return 1;
        }


ΓòÉΓòÉΓòÉ 7.3.6.1. SSComlinPrintParms ΓòÉΓòÉΓòÉ

SSComlinPrintParms prints the command parameters. The /P option prints the same
output.

Signature

void SSComlinPrintParms( void*)

 Parameters          Meaning

 void*               A command line correlator.

 Example

  int main( int qiArg, const char** qapszArg)
     {
     void* zpCom = SSComlinCreate( ...
     ┬╖
     ┬╖
     ┬╖
     SSComlinParse( zpCom);
  #  if degugging
     SSComlinPrintParms( zpCom);
  #  endif


ΓòÉΓòÉΓòÉ 7.3.7. SSComlinOptionCreate ΓòÉΓòÉΓòÉ

SSComlinOptionCreate creates a command line option and attaches it to the
command line.

Signature

void* SSComlinOptionCreate( void*, const char*, const char*,
   SSBooleanValue, SSUnsigned32, void**);

 Parameters          Meaning

 void*               A command line correlator.

 const char*         The option.

 const char*         The option description.

 SSBooleanValue      The defautl value for the option. The value is returned by
                     SSComlinOptionGetValue. This value is returned if the
                     option is not specified.

 SSUnsigned32        The option parameter type, specifying whether the option
                     accepts a parameter. Can be either SSComlinOptionNone,
                     SSComlinOptionRequired, or SSComlinOptionOptional.

 void**              A pointer that will be updated with an exception
                     correlator if an exception occurs.

 Returns

 An option correlator or 0. If zero, examine the exception correlator to
 determine the cause of the error.

 Example

  void* zpCom;
  void* zpOpt;
  void* zpExcept;

  zpCom = SSComlinCreate( "Command", qiArg, qapszArg, "Desc",
     0, 0, &zpExcept);

  zpOpt = SSComlinOptionCreate( zpCom, "Opt", "Opt Desc", SSFalse,
     SSComlinOptionNone, &zpExcept);


ΓòÉΓòÉΓòÉ 7.3.8. SSComlinOptionGetParm ΓòÉΓòÉΓòÉ

SSComlinOptionGetParm retrieves the parameter associated with the option.

Signature

const char* SSComlinOptionGetParm( void*);

 Parameters          Meaning

 void*               The option correlator.

 Returns

 The parameter string or 0.

 Example

  const char* zpParms = SSComlinOptionGetParm( zpOpt);


ΓòÉΓòÉΓòÉ 7.3.9. SSComlinOptionGetValue ΓòÉΓòÉΓòÉ

SSComlinOptionGetValue retrieves the option value.

Signature

SSBooleanValue SSComlinOptionGetValue( void*);

 Parameters          Meaning

 void*               The option correlator.

 Returns

 The value, either SSTrue '+', or SSFalse '-'.

 Example

  SSBooleanValue zVal = SSComlinOptionGetValue( zpOpt);


ΓòÉΓòÉΓòÉ 8. Validators ΓòÉΓòÉΓòÉ

 Concepts
 C++ Class
 C Functions


ΓòÉΓòÉΓòÉ 8.1. Concepts ΓòÉΓòÉΓòÉ

Validators are useful for things like verifying edit field data, or filtering
list box data. You can easily use any lexical analyzer specified in a rule file
to validate or filter strings of data. Some class libraries supply limited
validator or filtering classes, with the Visual Parse++ validator class (or C
function interface), you have the full power of regular expressions to verify a
string of data. Any lexical analyzer table, no matter how complicated, can be
used with the interfaces provided (currently C and C++).


ΓòÉΓòÉΓòÉ 8.2. C++ SSLexValidator Class ΓòÉΓòÉΓòÉ

 Concepts
 Constructors
 test


ΓòÉΓòÉΓòÉ 8.2.1. Concepts ΓòÉΓòÉΓòÉ

The SSLexValidator class is used to validate or verify null terminated strings
of data using an arbitrary lexical analyzer table.

The header file is sslexval.hpp.


ΓòÉΓòÉΓòÉ 8.2.2. Constructors ΓòÉΓòÉΓòÉ

Signature

SSLexValidator::SSLexValidator( const char*);

 Parameters          Meaning

 const char*         The lex table name.

 Returns

 Throws an exception if an error occurs.

 Example

  SSLexValidator zVal( "table.dfa");


ΓòÉΓòÉΓòÉ 8.2.3. test ΓòÉΓòÉΓòÉ

The test function tests the specified data.

Signature

SSBooleanValue SSLexValidator::test( const char*);

 Parameters          Meaning

 const char*         The data to test.

 Returns

 SSTrue indicates the data was accepted by the validator.

 Example

  SSLexValidator zVal( "table.dfa");
  SSBooleanValue zTest = zVal.test( "Test string");


ΓòÉΓòÉΓòÉ 8.3. C SSLexValidator Functions ΓòÉΓòÉΓòÉ

 Concepts
 SSLexValidatorCreate
 SSLexValidatorDestroy
 SSLexValidatorTest


ΓòÉΓòÉΓòÉ 8.3.1. Concepts ΓòÉΓòÉΓòÉ

The SSLexValidator C functions are used to validate or verify null terminated
strings of data using an arbitrary lexical analyzer table.

The header file is sslexval.h.


ΓòÉΓòÉΓòÉ 8.3.2. SSLexValidatorCreate ΓòÉΓòÉΓòÉ

The SSLexValidatorCreate function creates a validator.

Signature

void* SSLexValidatorCreate( const char*, void**);

 Parameters          Meaning

 const char*         The lex table name.

 void**              An area that is updated with an exception correlator if an
                     error occurs.

 Returns

 The validator correlator or 0. Zero indicates an error occurred, examine the
 returned exception correlator.

 Example

  void* zpExcept;
  void* zpVal = SSLexValidatorCreate( "table.dfa", &zpExcept);


ΓòÉΓòÉΓòÉ 8.3.3. SSLexValidatorDestroy ΓòÉΓòÉΓòÉ

The SSLexValidatorDestroy function destroys a validator.

Signature

void SSLexValidatorDestroy( void*);

 Parameters          Meaning

 void*               A validator correlator.

 Example

  SSLexValidatorDestroy( zpVal);


ΓòÉΓòÉΓòÉ 8.3.4. SSLexValidatorTest ΓòÉΓòÉΓòÉ

The SSLexValidatorTest function verifies the specified string.

Signature

SSBooleanValue SSLexValidatorTest( void*, const char*);

 Parameters          Meaning

 void*               A validator correlator.

 const char*         A null terminated test string.

 Returns

 SSTrue indicates a match.

 Example

  SSBooleanValue zTest = SSLexValidatorTest( zpVal, "Test data");


ΓòÉΓòÉΓòÉ 9. Commands ΓòÉΓòÉΓòÉ

 Concepts
 Options
 C File
 C++ File
 REXX File
 Symbol File
 Lex Table File
 Lex Machine File
 Yacc Table File
 Yacc Machine File
 Error Messages


ΓòÉΓòÉΓòÉ 9.1. Concepts ΓòÉΓòÉΓòÉ

To compile and test your rule file, use the SSPARSE and SSVPARSE commands.

SSPARSE is the command line compiler used to compile rule files and generate
language bindings and other information files.

SSVPARSE invokes the graphical rule file debugger.  It has all the capabilities
of the SSPARSE command plus the ability to completely debug your rule file.
See the Visual Parse++ User's Guide for more information.

There are several files which can be generated by using the SSPARSE command or
the Visual Parse++ debugger.  These files supply the language bindings
necessary for application development plus additional files to aid the
development process.

The parameters for both commands are identical with 1 exception. (The SSVPARSE
command has a /T parameter.)  Note: The SSVPARSE command opens an output file
in the current directory called ssvparse.out.  This file will contain any error
messages generated by the SSVPARSE command if an error occurs.


ΓòÉΓòÉΓòÉ 9.2. Options ΓòÉΓòÉΓòÉ

The command line syntax is as follows:

command [ options ] rulefile

 Parameter      Meaning

 command        Either SSPARSE or SSVPARSE.

 options        The options.

 rulefile       A rule file.

 Each option has syntax:

  (-|/)option[ (+|-) ][ ]parameter

 In words, options are preceded by either a '-' or a '/' and followed by an
 optional '+' or '-'.  If the '+' or '-' is missing, '+' is assumed. If the
 parameter is optional, it must be concatenated on the end of the option string
 (without the '+' sign). If it is required, there can be intervening white
 space.

 Option         Meaning

 /C             Generate the C header file.  The default is '-'. The optional
                parameter is a file name which defaults to the rule file name
                with a '.yh' extension. See C File for more information.

 /Cpp           Generate the C++ header file.  The default is '-'. The optional
                parameter is a file name which defaults to the rule file name
                with a '.yhh' extension. See C++ File for more information.

 /Fs            Generate a symbol file.  The default is '-' if there are no
                errors in the rule file, else '+'. The optional parameter is
                the file name which defaults to the rule file name with a
                '.sym' extension.  See Symbol File for more information.

 /H             Print a list of the options. For the SSVPARSE command, the
                printout goes to the file ssvparse.out in the current
                directory.

 /Lc            For C++, the SSLex derived class name. For C, the prefix used
                on function related to the lexical analyzer. For REXX, the
                prefix used on function and variable names related to the
                lexical analyzer.  The default is '+'.  The optional parameter
                defaults to 'ALexClass'.

 /Le            The prefix used on the %expression list identifier constants.
                The default is '+'.  The optional parameter is the prefix which
                defaults to 'ALexExpressionList'.

 /Lm            Print the lex machine. The default is '-'.  The optional
                parameter is the file name which defaults to the rule file name
                with a '.dfx' extension. See Lex Machine File for more
                information.

 /Lp            The prefix used on the %expression list token constants. The
                default is '+'.  The optional parameter is the prefix which
                defaults to 'ALex'.

 /Lt            Generate a lexical analyzer table.  The default is '+'. The
                optional parameter is the file name which defaults to the rule
                file name with a '.dfa' extension. See Lex Table File for more
                information.

 /P             Print a list of the parameters that were specified.  This is
                useful for debugging a command line that is not behaving as
                expected.  For the SSVPARSE command, the printout goes to the
                file ssvparse.out in the current directory.

 /Rx            Generate the REXX file.  The default is '-'. The optional
                parameter is a file name which defaults to the rule file name
                with a '.cmd' extension. See REXX File for more information.

 /Yc            For C++, the SSYacc derived class name. For C, the prefix used
                on functions related to the parser. For REXX, a prefix used on
                function and variable names related to the parser. The default
                is '+'.  The optional parameter defaults to 'AYaccClass'.

 /Ym            Print the parsing machine. The default is '-'.  The optional
                parameter is the file name which defaults to the rule file name
                with a '.llx' extension. See Yacc Machine File for more
                information.

 /Yp            The prefix used on the %production labels. The default is '+'.
                The optional parameter is the prefix which defaults to 'AYacc'.

 /Yt            Generate a parser table.  The default is '+'. The optional
                parameter is the file name which defaults to the rule file name
                with a '.llr' extension. See Yacc Table File for more
                information.

 /T             The tab amount.  Valid only on the SSVPARSE command. The
                parameter is a numeric argument. See the Visual Parse++ User's
                Guide for more information on the tab amount.


ΓòÉΓòÉΓòÉ 9.3. C File ΓòÉΓòÉΓòÉ

The C header file (with default extension '.yh') contains the language bindings
for C.  You can tailor this file with either command line options or the Visual
Parse++ debugger.

A small example will be used to illustrate the concepts. Compile the ssexpr.ycc
sample with these parameters:

SSPARSE /C /LcALex /LpALexToken /YcAYacc /YpAYaccProd ssexpr.ycc

The file ssexpr.yh will look like the following:

#if !defined( SSEXPRSSH)
#  define SSEXPRSSH
#  include<sslexc.h>
#  include<ssyaccc.h>

#  define ALexExpressionListMain       0

#  define ALexTokenEnd                 2
#  define ALexTokenPlus                3
#  define ALexTokenMinus               4
#  define ALexTokenDiv                 5
#  define ALexTokenMult                6
#  define ALexTokenPower               7
#  define ALexTokenOParen              8
#  define ALexTokenCParen              9
#  define ALexTokenNumber              10
#  define ALexTokenName                11

#  define AYaccProdStart               1
#  define AYaccProdStartList           2
#  define AYaccProdExprSingle          3
#  define AYaccProdExprPlus            4
#  define AYaccProdExprMinus           5
#  define AYaccProdExprMult            6
#  define AYaccProdExprDiv             7
#  define AYaccProdExprPower           8
#  define AYaccProdExprNested          9
#  define AYaccProdExprName            10
#  define AYaccProdExprNumber          11

   SSRetConstChar ALexTokenToConstChar( SSUnsigned32 qulToken)
      {
      const char* zpchToken;
      switch ( qulToken)
         {
         case ALexTokenEnd:
            zpchToken = ";";
            break;

         case ALexTokenPlus:
            zpchToken = "+";
            break;

         case ALexTokenMinus:
            zpchToken = "-";
            break;

         case ALexTokenDiv:
            zpchToken = "/";
            break;

         case ALexTokenMult:
            zpchToken = "*";
            break;

         case ALexTokenPower:
            zpchToken = "**";
            break;

         case ALexTokenOParen:
            zpchToken = "(";
            break;

         case ALexTokenCParen:
            zpchToken = ")";
            break;

         case ALexTokenNumber:
            zpchToken = "n";
            break;

         case ALexTokenName:
            zpchToken = "name";
            break;

         case SSYaccErrorToken:
            zpchToken = "%error";
            break;

         case SSYaccEofToken:
            zpchToken = "eof";
            break;

         default:
            zpchToken = SSLexTokenNotFound;
         }
      return zpchToken;
      }

   SSRetVoidP AYaccReduce( SSUnsigned32 qulProd, SSUnsigned32 qulSize, void* qpParm)
      {
      switch ( qulProd)
         {
         case AYaccProdStart:
         /* start -> expressionStatement */
            break;

         case AYaccProdStartList:
         /* start -> start expressionStatement */
            break;

         case AYaccProdExprSingle:
         /* expressionStatement -> expression ; */
            break;

         case AYaccProdExprPlus:
         /* expression -> expression + expression */
            break;

         case AYaccProdExprMinus:
         /* expression -> expression - expression */
            break;

         case AYaccProdExprMult:
         /* expression -> expression * expression */
            break;

         case AYaccProdExprDiv:
         /* expression -> expression / expression */
            break;

         case AYaccProdExprPower:
         /* expression -> expression ** expression */
            break;

         case AYaccProdExprNested:
         /* expression -> ( expression ) */
            break;

         case AYaccProdExprName:
         /* expression -> name */
            break;

         case AYaccProdExprNumber:
         /* expression -> n */
            break;

         }

      return SSYaccStackElementCreate( 0, 0);
      }

#endif


ΓòÉΓòÉΓòÉ 9.4. C++ File ΓòÉΓòÉΓòÉ

The C++ header file (with default extension '.yhh') contains the language
bindings for C++.  You can tailor this file with either command line options or
the Visual Parse++ debugger.

Complile the ssexpr.ycc sample with the following parameters:

SSPARSE /Cpp /LcALex /LpALexToken /YcAYacc /YpAYaccProd ssexpr.ycc

The file ssexpr.yh will look like the following.

#if !defined( SSEXPRSSHH)
#  define SSEXPRSSHH
#  include<sslex.hpp>
#  include<ssyacc.hpp>

#  define ALexExpressionListMain       0

#  define ALexTokenEnd                 2
#  define ALexTokenPlus                3
#  define ALexTokenMinus               4
#  define ALexTokenDiv                 5
#  define ALexTokenMult                6
#  define ALexTokenPower               7
#  define ALexTokenOParen              8
#  define ALexTokenCParen              9
#  define ALexTokenNumber              10
#  define ALexTokenName                11

#  define AYaccProdStart               1
#  define AYaccProdStartList           2
#  define AYaccProdExprSingle          3
#  define AYaccProdExprPlus            4
#  define AYaccProdExprMinus           5
#  define AYaccProdExprMult            6
#  define AYaccProdExprDiv             7
#  define AYaccProdExprPower           8
#  define AYaccProdExprNested          9
#  define AYaccProdExprName            10
#  define AYaccProdExprNumber          11

   class ALex : public SSLex
      {
      public:
         SSConstr            ALex( const char*);
         const char*         tokenToConstChar( SSUnsigned32);
      };

   ALex::ALex( const char* qpszFile) :
      SSLex( qpszFile, "ssexpr.dfa")
      {
      }

   const char* ALex::tokenToConstChar( SSUnsigned32 qulToken)
      {
      const char* zpchToken;
      switch ( qulToken)
         {
         case ALexTokenEnd:
            zpchToken = ";";
            break;

         case ALexTokenPlus:
            zpchToken = "+";
            break;

         case ALexTokenMinus:
            zpchToken = "-";
            break;

         case ALexTokenDiv:
            zpchToken = "/";
            break;

         case ALexTokenMult:
            zpchToken = "*";
            break;

         case ALexTokenPower:
            zpchToken = "**";
            break;

         case ALexTokenOParen:
            zpchToken = "(";
            break;

         case ALexTokenCParen:
            zpchToken = ")";
            break;

         case ALexTokenNumber:
            zpchToken = "n";
            break;

         case ALexTokenName:
            zpchToken = "name";
            break;

         case SSYaccErrorToken:
            zpchToken = "%error";
            break;

         case SSYaccEofToken:
            zpchToken = "eof";
            break;

         default:
            zpchToken = SSLexTokenNotFound;
         }
      return zpchToken;
      }

   class AYacc : public SSYacc
      {
      public:
         SSConstr            AYacc( const char*);
         SSYaccStackElement* reduce( SSUnsigned32, SSUnsigned32);

      protected:
         SSLex               oLex;
      };

   AYacc::AYacc( const char* qpszFile) :
      SSYacc("ssexpr.llr"),
      oLex( qpszFile, "ssexpr.dfa")
      {
      setLex( oLex);
      }

   SSYaccStackElement* AYacc::reduce( SSUnsigned32 qulProd,
      SSUnsigned32 qulSize)
      {
      switch ( qulProd)
         {
         case AYaccProdStart:
         // start -> expressionStatement
            break;

         case AYaccProdStartList:
         // start -> start expressionStatement
            break;

         case AYaccProdExprSingle:
         // expressionStatement -> expression ;
            break;

         case AYaccProdExprPlus:
         // expression -> expression + expression
            break;

         case AYaccProdExprMinus:
         // expression -> expression - expression
            break;

         case AYaccProdExprMult:
         // expression -> expression * expression
            break;

         case AYaccProdExprDiv:
         // expression -> expression / expression
            break;

         case AYaccProdExprPower:
         // expression -> expression ** expression
            break;

         case AYaccProdExprNested:
         // expression -> ( expression )
            break;

         case AYaccProdExprName:
         // expression -> name
            break;

         case AYaccProdExprNumber:
         // expression -> n
            break;

         }

      return stackElement();
      }

#endif


ΓòÉΓòÉΓòÉ 9.5. REXX File ΓòÉΓòÉΓòÉ

The REXX file (with default extension '.cmd') contains the language bindings
for REXX.  You can tailor this file with either command line options or the
Visual Parse++ debugger.

Complile the ssexpr.ycc sample with the following parameters:

SSPARSE /Rx /LcALex /LpALexToken /YcAYacc /YpAYaccProd ssexpr.ycc

The file ssexpr.cmd will look like the following.

/* Visual Parse++ REXX function*/

SSDll = 'c:\ss\bin\SSVYREXX.DLL'
call RxFuncAdd 'SSLoadRexxFunctions', SSDll, 'SSLoadRexxFunctions'
call SSLoadRexxFunctions SSDll

signal on error name SSTerminate
signal on syntax name SSTerminate
signal on failure name SSTerminate

ALexTokenEnd        = 2
ALexTokenPlus       = 3
ALexTokenMinus      = 4
ALexTokenDiv        = 5
ALexTokenMult       = 6
ALexTokenPower      = 7
ALexTokenOParen     = 8
ALexTokenCParen     = 9
ALexTokenNumber     = 10
ALexTokenName       = 11

AYaccProdStart      = 1
AYaccProdStartList  = 2
AYaccProdExprSingle = 3
AYaccProdExprPlus   = 4
AYaccProdExprMinus  = 5
AYaccProdExprMult   = 6
AYaccProdExprDiv    = 7
AYaccProdExprPower  = 8
AYaccProdExprNested = 9
AYaccProdExprName   = 10
AYaccProdExprNumber = 11

ALexTable = 'ssexpr.dfa'
ALexConsumer = 'Visual Parse++ Consumer'
ALex = SSLexCreate( ALexTable, ALexConsumer, SSFile)
AYaccTable = 'ssexpr.llr'
AYacc = SSYaccCreate( ALex, AYaccTable)

do forever
   SSRet = SSYaccParse( AYacc, SSParm)
   select
      when SSRet = SSOK then
         say 'Lexeme 'SSParm.0' at' SSParm.2','SSParm.3' Token = 'SSParm.1
      when SSRet = SSMORE then do
         SSRet = ALexProcessMore()
         if SSRet <>  then
            SSRet = SSLexAddData( ALex, SSRet)
         end
      when SSRet = SSSHIFT then
         say 'Shift 'SSParm.0' at' SSParm.2','SSParm.3' Token = 'SSParm.1
      when SSRet = SSREDUCE then
         call AYaccReduce
      when SSRet = SSACCEPT then do
         say 'Accept'
         leave
         end
      when SSRet = SSLEXERROR then do
         SSRet = ALexProcessError()
         if SSRet < 0 then leave
         end
      when SSRet = SSYACCERROR then do
         SSRet = AYaccProcessError()
         if SSRet < 0 then leave
         end
      otherwise
         say 'Unprocessed parse 'SSRet
   end
end

call SSUnloadRexxFunctions
return 0



AYaccProcessError:
   say 'Parse error on line 'SSParm.2' at offset 'SSParm.3': 'SSParm.0','SSResult
   return -1

ALexProcessMore:
   return ''

ALexProcessError:
   say 'Invalid lexeme on line 'SSParm.2' at offset 'SSParm.3': 'SSParm.0
   return -1

AYaccReduce:
   say 'Reduce 'SSParm.0
   select
      when SSParm.0 = AYaccProdStart then do
      /* start -> expressionStatement */
         end

      when SSParm.0 = AYaccProdStartList then do
      /* start -> start expressionStatement */
         end

      when SSParm.0 = AYaccProdExprSingle then do
      /* expressionStatement -> expression ; */
         end

      when SSParm.0 = AYaccProdExprPlus then do
      /* expression -> expression + expression */
         end

      when SSParm.0 = AYaccProdExprMinus then do
      /* expression -> expression - expression */
         end

      when SSParm.0 = AYaccProdExprMult then do
      /* expression -> expression * expression */
         end

      when SSParm.0 = AYaccProdExprDiv then do
      /* expression -> expression / expression */
         end

      when SSParm.0 = AYaccProdExprPower then do
      /* expression -> expression ** expression */
         end

      when SSParm.0 = AYaccProdExprNested then do
      /* expression -> ( expression ) */
         end

      when SSParm.0 = AYaccProdExprName then do
      /* expression -> name */
         end

      when SSParm.0 = AYaccProdExprNumber then do
      /* expression -> n */
         end

   end
   return

SSTerminate:
   say 'Error on line 'sigl': 'SSResult
   call SSUnloadRexxFunctions
   exit 1


ΓòÉΓòÉΓòÉ 9.6. Symbol File ΓòÉΓòÉΓòÉ

The symbol file (with default extension '.sym')  contains information about the
terminal and nonterminal symbols in your rule file.

If errors are detected, you may need to view this file to determine the cause
of the error.

An entry in the file has the following format:

Symbol Alias Type Assoc Prec

 Column         Meaning

 Symbol         The symbol name.

 Alias          The alias, if one was specified.

 Type           Either terminal or nonterminal.

 Assoc          The associativity, either left, right, of nonassoc.

 Prec           The precedence.


ΓòÉΓòÉΓòÉ 9.7. Lex Table File ΓòÉΓòÉΓòÉ

The lex table file (with default extension '.dfa') contains the lexical
analyzer.  You can access this file with the SSLex and SSLexTable classes.


ΓòÉΓòÉΓòÉ 9.8. Lex Machine File ΓòÉΓòÉΓòÉ

The lex machine file (with default extension '.dfx') contains a printout of the
lexical analyzer.  Examining this file can be helpful for diagnosing lexical
analyzers that aren't behaving as expected. The file has the following format:

*
* Lex machine for name
*

State(nnn)

   start  end   Next(nnn)
   ┬╖      ┬╖     ┬╖
   ┬╖      ┬╖     ┬╖
   ┬╖      ┬╖     ┬╖
   start  end   Next(nnn)
   ┬╖      ┬╖     ┬╖
   ┬╖      ┬╖     ┬╖
   ┬╖      ┬╖     ┬╖

The name is the %expression list name. Each entry is a range of code points
that transition to the state indicated.


ΓòÉΓòÉΓòÉ 9.9. Yacc Table File ΓòÉΓòÉΓòÉ

The yacc table file (with default extension '.llr') contains the parser.  You
can access this file with the SSYacc and SSYaccTable classes.


ΓòÉΓòÉΓòÉ 9.10. Yacc Machine File ΓòÉΓòÉΓòÉ

The yacc machine file (with default extension '.llx') contains a printout of
the parser.  Examining this file can be helpful for diagnosing parsers that
aren't behaving as expected. The file has the following format:

State(nnn)
   Kernel Items
-------------------------------------------------------------
   Other Items

State(nnn)
   Kernel Items
-------------------------------------------------------------
   Other Items

   ┬╖
   ┬╖
   ┬╖

Items look like:

leftside -> rightside [ lookaheads ]

where the item is listed followed by the valid lookaheads for this item.
Lookaheads are only listed for items that will cause a reduce.


ΓòÉΓòÉΓòÉ 10. Error Messages ΓòÉΓòÉΓòÉ

The following is a list of error messages that you may receive.

 Error               Meaning

 SSCmd0001e          A command line parameter was too long for the buffer.

 SSCmd0002e          A command line argument was too long.

 SSCmd0003e          An invalid option was specified.

 SSCmd0004e          A parameter on an option was required but not specified.

 SSCmd0005e          A parameter on an option was not allowed, but one was
                     supplied.

 SSCmd0006e          A duplicate option was specified.

 SSComlin0001e       An invalid option was specified.

 SSComlin0002e       A parameter was expected but not supplied.

 SSComlin0003e       A parameter was not expected, but one was supplied.

 SSComlin0004e       A duplicate option was specified.

 SSComlin0005e       A syntax error was detected.

 SSFLex0001e         An invalid token was detected in a regular expression.

 SSFLex0002e         Either the macro was not found or there is a series of
                     macro definitions that are circular.

 SSFLex0003e         A syntax error was detected in a regular expression.

 SSFLex0004e         A macro was encountered in a regular expression, but there
                     are no macro definitions.

 SSFLex0005e         An empty character class ([]) was detected in a regular
                     expression.

 SSFLex0006e         The \d, \o, or \x numeric constant cannot fit in a 32 bit
                     unsigned integer.

 SSFLex0007e         An invalid range was detected on the {n,n} operator in a
                     regular expression.  The first number must be greater than
                     or equal to 0, and less than the second number.

 SSFLex0008e         The table is too big for the platform.

 SSFile0001e         The file could not be opened. 'errno' is displayed in the
                     message.

 SSFile0002e         An invalid file name was specified.

 SSFile0005e         A read failed for a file.

 SSLex0001e          The file could not be opened. 'errno' is displayad in the
                     message.

 SSLex0002e          The file length could not be retrieved.

 SSLex0003e          An invalid consumer type was specified.

 SSLex0004e          The lexeme could not fit in the consumer buffer, and the
                     buffer could not be expanded.

 SSLex0006e          An invalid lexeme was detected.

 SSLex0101e          The file could not be opened.

 SSLex0102e          The file length could not be retrieved, or a read error
                     occurred.

 SSLex0103e          A lexeme could not fit in the consumer buffer, and the
                     buffer could not be expanded.

 SSLex0104e          An invalid table was detected.

 SSLex0105e          An invalid token was detected.

 SSLex0106e          An invalid expression list index was specified.

 SSLex0107e          A lexer requires a table and a consumer to function, one
                     of them is missing.

 SSLifo0001e         A stack full condition was detected.

 SSLifo0002e         A stack is empty and a query was performed.

 SSLifo0003e         An invalid index was specified on a stack probe.

 SSLifo0004e         An attempt was made to pop an empty stack.

 SSLlr0015e          A parse table is too big.

 SSVP0001e           You selected Debug/Animate from the menubar, but the timer
                     could not be started. There are too many system timers,
                     try again later.

 SSVP0002e           Visual Parse++ was unable to register a required class.

 SSVP0003e           Visual Parse++ was unable to create a window.

 SSVP0004e           An expression list could not be located.

 SSVP0006e           The tab amount must be between 0 and 32.

 SSVP0007e           A failure occurred while lexing. You probably popped the
                     last lexer on the expression list stack.

 SSYacc0001e         The parse table could not be opened.

 SSYacc0002e         An invalid parse table was detected.

 SSYacc0003e         An invalid parse table was detected.

 SSYacc0004e         An invalid index was specified on elementFromProduction.

 SSYacc0005e         Unexpected end of input detected.

 SSYacc0006e         Error recovery failed, no usable state could be located.

 SSYacc0007e         Error recovery failed, no recovery token could be located.

 SSYacc0008e         Error panic recovery procedure could not locate a valid
                     token in the current context.

 SSYacc0009e         The rule file name was missing on the SSPARSE command.

 SSYacc0010e         The start symbol was not a nonterminal symbol. Use the
                     Symbol File to help resolve the error.

 SSYacc0011e         The leftside symbol was not a nonterminal symbol. Use the
                     Symbol File to help resolve the error.

 SSYacc0012e         The production label name was duplicated.  Production
                     label names must be unique.

 SSYacc0013e         The regular expression was invalid.  A preceding message
                     describes the error in more detail.

 SSYacc0014e         No %expression lists were included in the rule file.  A
                     rule file must have at least 1 %expression list.

 SSYacc0015e         A syntax error was detected.  The valid lookahead symbols
                     are listed in the message.  Very often, this is the result
                     of a missing ';'.

 SSYacc0017e         The precedence specified was to large.  It must be less
                     than 0xfffffffe.

 SSYacc0018e         An invalid name or alias was specified in a %prec section.
                     The name or alias could not be located in an %expression
                     list.

 SSYacc0019e         The precedence specified was to large.  It must be less
                     than 0xfffffffe.

 SSYacc0020e         The precedence entry is a duplicate.  Only one entry may
                     be specified for each %expression list entry.

 SSYacc0021e         A different alias name was specified for the same name in
                     a %expression list entry.  You cannot have 2 different
                     aliases for the same token.

 SSYacc0022e         The alias name was the same as a previous alias name, but
                     the name was different.  You cannot have the same alias on
                     2 different tokens.

 SSYacc0023e         The production is unreachable.  This is usually the result
                     of a misspelled nonterminal name. Use the Symbol File to
                     help resolve the error.

 SSYacc0024e         The production is never derives a token string. This is
                     usually the result of a misspelled nonterminal name. Use
                     the Symbol File to help resolve the error.

 SSYacc0025e         A shift/reduce conflict was detected in the grammar.  Use
                     the Yacc Machine File to help resolve the error.  You can
                     also use the graphical debugger with grammars containing
                     shift/reduce conflicts.  When a conflict is reached, you
                     must reslove the conflict with a mouse click.

 SSYacc0026e         Same as SSYacc0025e

 SSYacc0027e         A reduce/reduce conflict was detected in the grammar.  Use
                     the Yacc Machine File to help resolve the error.  You can
                     also use the graphical debugger with grammars containing
                     reduce/reduce conflicts.  When a conflict is reached, you
                     must reslove the conflict with a mouse click.

 SSYacc0028e         Same as SSYacc0027e

 SSYacc0029e         This is like a reduce/reduce conflict, except the accept
                     state is involved in the conflict.

 SSYacc0030e         There were errors in your rule file specification.

 SSYacc0031e         There were errors in your rule file specification.

 SSYacc0032e         There were errors in your rule file specification.

 SSYacc0033e         The rule file name was missing on the SSPARSE command.

 SSYacc0034e         The start symbol could not be found. Use the Symbol File
                     to help resolve the error.

 SSYacc0035e         The start symbol must be a nonterminal. Use the Symbol
                     File to help resolve the error.

 SSYacc0037e         The %expression list name was duplicated.  Each name on an
                     %expression list must be unique.

 SSYacc0038e         A %push name was encountered, but no corresponding
                     %expression list name could be located.

 SSYacc0039e         An expression list was defined, but never referenced.

 SSYacc0040e         A null quoted expression was detected.  There must be at
                     least 1 character inside a quoted expression.

 SSYacc0041e         The error panic recovery procedure failed, no valid token
                     could be located.

 SSYacc0042e         An %error or % token followed by a %error % token is
                     redundant and not allowed.

 SSYacc0043e         You are using the demo version and specified too many
                     regular expressions.

 SSYacc0044e         You are using the demo version and specified too many
                     productions.

 SSYacc0101e         A file could not be opened.

 SSYacc0102e         An invalid table was detected.

 SSYacc0103e         An attempt was made to read past eof.

 SSYacc0104e         The error panic recovery procedure failed, no token could
                     be located.

 SSYacc0105e         Error recovery failed, no token could be located.

 SSYacc0106e         Error recovery reached end of data before a valid token
                     was located.

 SSYacc0107e         An invalid parse table was detected.

 SSYacc0108e         An invalid index was specified on elementFromProduction.

 SSYacc0109e         The parse table is missing. Each parser requires a parse
                     table.

 SSYacc0110e         A lexer is required by each parser, or you must override
                     the nextLexeme virtual function.

 SSYacc0111e         An error occurred while reading the parse table.

 SSYacc0112e         The parse table is too big.

 SSYacc0113e         A permanent error was detected, but you tried to continue
                     parsing.

 SSYaccOutIn0002e    You continued parsing even though the data was detected.