═══ 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 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 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 # include # 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 # include # 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.