LLParser Class Reference

This is the base class of any LLParser generated from a gsp grammar. More...

Detailed Description

This is the base class of any LLParser generated from a gsp grammar.

Using a LL parser is straightforward. It just consists in passing to the appropriate constructor the source from which to get the char stream, running the parsing with the run() method and getting results with other methods.

For further information and get any example of use, check the source of the examples provided with this documentation.

Files Included

Functions Documentation

Stream operator for outputting the message of a fatal error exception to the passed stream.

See also:

Constructs a parser that will read the input chars from the passed is input stream reference, regardless of the actual type of the input stream, e.g. a file stream (fstream) or a string stream (strstream).

Default parser status is:

- Stream break-off is expected when parsing is completed.

- root() raises an exception as no root symbol is still created.

- done() returns false (parsing not done yet).

- fail() returns false (no failure).

- getLineNo() returns 1.

- nbErrors() returns 0.

- syntaxerror() returns false (no syntax error).

- ignoreCase() returns true if the parse code was generated with the '--ignore-case' option. False otherwise.

- showLineNo() returns true, i.e. the line numbers are shown in the error contexts.

Example:

 #include <fstream>
 ...
 ifstream ifs("myfile");
 sample::Parser parser(ifs);
 parser.run();
 if (parser.fail())
 {
   // Handle error here.
 }

Example:

 #include <strstream>
 ...
 strstream str;
 str << "line, 1, 2.0: , , a constant";
 sample::Parser parser(str);
 parser.run();
 if (parser.fail())
 {
   // Handle error here.
 }

See also:

This is an overloaded constructor provided for convenience. It behaves essentially like the above constructor.

Constructs a parser that will get the input chars from the passed ifd file descriptor, regardless of the actual type of the file, e.g. a conventional system file, a socket or whatever else for which a file descriptor can be got.

Example:

 #include <fstream>
 ...
 int ifd = open("myfile", O_RDONLY);
 sample::Parser parser(ifd);
 parser.run();
 if (parser.fail())
 {
   // Handle error here.
 }

See also:

This is an overloaded constructor provided for convenience. It behaves essentially like the above constructor.

Constructs a parser that will get the input chars from the passed file name or file path.

If the file couldn't be opened, fail() will return true and an error message is returned by getFailureMessage().

Example:

   sample::Parser parser("my_file");

is equivalent to

Example:

   ifstream ifs("my_file");
   sample::Parser parser(ifs);

See also:

This is an overloaded constructor provided for convenience. It behaves essentially like the above constructor.

Constructs a parser that will get the input chars from the passed arguments argc and argv which are typically those passed to the main() function of a program.

Argument values containing relevant whitespaces are surrounded with left delimiter pszLeftValDelim and right delimiter pszRightValDelim (by default double quotes in both cases) to avoid parse problems when values contain relevant whitespaces.

Example:

   sample::Parser parser(argc, argv);

is equivalent to

Example:

  strstream str;
  universal::String sArg;
  for (i=1; i < argc; i++)
    {
      sArg = argv[i];
      if ((sArg.indexOf(' ') >= 0) ||
	  (sArg.indexOf('\t') >= 0) ||
	  (sArg.indexOf('\v') >= 0) ||
	  (sArg.indexOf('\r') >= 0) ||
	  (sArg.indexOf('\f') >= 0)
	  )
	{
	  str << pszLeftValDelim << sArg.str() << pszRightValDelim << " ";
	}
      else
	{
	  str << sArg.str() << " ";
	}
    }
   str << ends;
   sample::Parser parser(str);

Note: When a parser is constructed with this constructor, no line number is shown in failure contexts.

See also:

Destructor.

Note:

The root symbol object that was possibly instantiated when the last parsing was run is NOT destroyed. It is up to calling programs to manage root objects destruction following parse runs.

See also:

Initializes the parser object, setting appropriate default status.

Private.

See also:

Tells the parser whether to expect a stream break-off when the parsing is completed. A stream break-off occurs when no char can be read from the input anymore. For conventional files it is typically when the End-of-File marker is encountered and for strings it is when the null char '\0' is encountered.

By default, a stream break-off is expected (bBreakOff is true). That means that a parse error is raised when EOF / end-of-stream is not encountered and that further characters can be read once the parsing completed.

In fact, depending on the grammar design, it may happen that a parsing can be successful (a valid syntactical parse tree could be resolved) although not all the chars of the stream have been read. Generally, this may reveal a flaw in the grammar design. Most of the time users are willing to parse the whole available input. Therefore it is recommended not to change the default behavior and to reserve the use of this method for advanced uses only.

See also:

Tells whether a stream break-off is expected during parsing.

See also:

This is an overloaded function provided for convenience. It is equivalent to the function referred to below.

See also:

Tells whether the input stream is a string, i.e. whether the istream reference passed to the constructor can be cast to an istrstream reference.

See also:

Tells whether the input stream is a file, i.e. whether the istream reference passed to the constructor can be cast to an ifstream reference.

See also:

Tells whether the input stream is a socket, i.e. whether the file descriptor passed to the constructor is attached to a socket.

See also:

Tells whether the input stream is a fifo, i.e. whether the file descriptor passed to the constructor is attached to a fifo.

See also:

Tells whether the input stream is a char device, i.e. whether the file descriptor passed to the constructor is attached to a char device.

See also:

Tells whether the input stream is a link, i.e. whether the file descriptor passed to the constructor is attached to a link.

See also:

Returns a reference to the actual input stream on which is performed the parsing.

Most of the time, except in very specific uses, the actual stream returned is the pre-processed stream containing the pre-processed image of the chars read from the original raw input stream as passed to the parser constructor.

If the pre-processing was not carried out (see preprocess()), the raw stream as passed to parser constructor is simply returned.

Normally, pre-processing is always done and is transparent for the user. Pre-processing is the first operation that is done when the parsing is run. If no pre-processor is defined, the parse stream just contains a copy of the chars that were read from the input source.

This stream should never be accessed directly by users, except for writing tokens parse codes (implicit local reference named 'is' is then already available), or for advanced uses within non-terminal reduction codes (using $0.stream(), $0 being a reference to the parser object).

See also:

Returns the preprocessing stream.

See also:

Tells whether a failure occurred during the parsing.

There is a failure when:

- Pre-processing failed. Normally, the sole possible way to make pre- processing fail is to pass an invalid input source to the constructor from which no chars can be got (e.g. invalid file name).

- A syntax error was encountered and detected by the generated parse code

- A fatal (breaking) failure was raised in a non-terminal reduction code

- At least one (non-breaking) error was notified in a non-terminal reduction code

See also:

Tells whether char case is ignored during parsing. This method always returns the same result and the value is fixed at generation time. Passing '--ignore-case' to the generator forces generation of code that ignores input char case. By default, case is always relevant.

See also:

Sets the failure flag.

Private.

See also:

Tells whether the parse was already run, regardless of final result.

See also:

Tells whether the pre-processing was done.

See also:

Tells whether a parsing from the root symbol of the grammar is currently running, i.e. the run() was called and the function call has not returned yet.

Returns false for temporary parser objects created internally by the generated code when users wants to parse a random non-terminal symbol which is not the root symbol of the grammar.

See also:

Stops a running parsing. If the parsing was already finished, calling this method has no effect. Otherwise done() will return true afterwards.

This method is foreseen for the case where a running parsing could be interrupted by another thread as the one actually running the parse code. At the moment, there is no real requirement nor any request for providing such feature and the function is not fully implemented in that sense that a running parsing can't be interrupted yet (may be implemented later by closing the input parse stream).

Therefore, right now this function only serves internal purposes for setting internal flags appropriately.

See also:

Runs the parser, i.e. parses the input data source passed to the parser object constructor.

The function only returns once the parsing completed or a fatal failure was encountered.

See also:

Runs all the tests defined for the symbols imported or defined in the grammar.

Returns false if at least one test failed.

Tests outputs and results are printed out into the passed output stream os.

bVerbose tells whether to print out additional information about the run tests. bVerbose is optional and is not set by default. This value is forwarded to the respective test() method called on each tested symbol.

See also:

Runs the parsing.

Creates the root symbol object if it was not created it.

This method is internally called by run().

Private.

See also:

Pre-processes the characters read from the input source and put the result in the parse stream from which the parsing actually takes place.

Pre-processors that were imported in the grammar are used to carry out the pre-processing. The input chars are filtered by calling successively each pre-processor routine in the same order as they were imported in the grammar. Should any of these routines reject a charater, the character is definetely rejected and will not be part of the parse stream.

See also:

Pre-processes c. This function should return false if the character has to be excluded from the stream that will be parsed. The value of c may be replaced with another by the pre-processing routines.

Private.

See also:

Checks whether the number of instances parsed for each symbol is consistent with the occurrence constraints defined for it in the grammar.

See also:

Returns the number of the line currently being parsed.

This method is foreseen for the case where another thread as the one carrying out the parsing wants to get some advancement data about the parsing. Could be relevant when parsing lasts a long time.

See also:

Sets the number of the line currently being parsed. Called internally by the base symbol class.

Private.

See also:

Returns the number of the line at which a parse failure occurred. When the parser created, there is no known failure and this function returns 0.

See also:

Returns the error message attached to a fatal (breaking) failure. Fatal failures split into two categories: On the one hand there are the failures managed internally by the generated code, e.g. an invalid input source (bad file...) is passed to the constructor. For them a constant default error message is always provided. On the other hand, there are the failures that the user raises manually in non-terminal reduction codes. In that case, it is the user that constructs and passes the error message to the method call raising the fatal failure.

If only a syntax error was encountered, the message returned is empty. Precise location of the syntax error and context in the input char stream can be got through other methods.

If non-breaking errors were notified, the message returned is also empty. Messages attached to non-breaking error do not appear here.

See also:

This function is provided for convenience. Fulfills the same function as the function referred to below, except that the failure message is re-directed to an output stream and not returned as a string object.

See also:

Traces back all the symbols that have been parsed until the end of the parsing or before the parse error occurred.

The trace is put into the passed output stream os.

This function is very useful for grammar development and debug purposes to check what happens during the parsing and to detect when an error actually occurred.

See also:

Forces the recording of a failure at the specified line number and offset in stream.

The last recorded failure, if any, is lost.

Exclusively used when a fatal failure is raised in a symbol reduction code.

Private.

See also:

Records a (non-breaking) failure at the specified line number uFailureLineNo and offset failureOffset in stream. Additionally, uMismatchConstantIndex provides the index of the missed constant in the parser's constants table.

The new failure is recorded and overrides the previous one only if the line number and offset of the new failure are greater or equal to the last recorded one.

Returns true if the new failure overrides the previous recorded one. False otherwise (new failure ignored).

This method may be invoked in different situations: First, it is called by the generated parse code of the non-terminal symbols in order to record the successive syntax errors encountered while attempting to resolve the syntactical parse tree. That way, whenever the parsing finally fails, the last recorded failure will give the line number and offset in stream at which the syntax error occurred. Secondly, it is indirectly invoked whenever the user notifies non-breaking errors from reduction code. Usually the reject() and error(...) methods referred to below will be used for that purpose.

Despite of being public, it is recommended to never invoke this method directly, but rather using the reject() and error(...) methods provided by the base Symbol class for all non-terminals and tokens.

See also:

Returns the context of the failure in the original input char stream. A failure context shows the line at which the syntax error or the last user (non-breaking) error occurred, with a cursor pointing to the exact char from which the stream couldn't be parsed properly anymore.

In order to facilitate identification of the erroneous line in the source stream, immediate preceding and following lines are also included. The amount of preceding lines shown depends on value passed to optional parameter uNbLinesAround (1 by default). There are always as many preceding lines shown as following ones, except when the error occurred at a boundary of the stream, in which case there is either less preceding lines (error occurred at beginning of stream) or less following lines ( error occurred at end of stream).

By default line numbers are always shown along the source lines themselves. They are not shown when a parser was constructed for parsing process command line arguments, since these latter are contained within one and only one line.

For readability purposes and in order to fit to most terminal windows the length of a context line is limited to 70 characters, inclusive line numbers.

For all context lines except the error line, the following rules prevails: If the length of the line exceeds the maximum limit, the right end of the line is truncated and replaced with '[...]'.

The error line is shown such as the exact position of the failure with its cursor always remains visible. It is ensured that the 15 chars following the failure position are also visible. Therefore, if necessary, the error line is shown centered to the failure position. If the left part of the line is too long and can't be fully shown, it is truncated and replace with '[...]'. Idem for the right part.

The following gives an example of context string obtained when feeding a 'sample' parser with its own grammar (sample.gsp).

Example:

 ...
 sample::Parser parser(pszFilename);
 parser.run();
 if (parser.fail())
 {
   if (parser.syntaxerror())
   {
     cerr << parser.getFailureContext(4);
   }
 }
 ...

Example:

 Example of error output:
 1: import std;
    _______^
 2:
 3: token SampleToken extends class universal::String()
 4:   include <stdio.h>, <ctype.h>, "universal__String.h"
 5:   alias "mytoken"

See also:

This function is provided for convenience. Fulfills the same function as the function referred to below, except that the failure context is re-directed to the passed output stream os and not returned as a string object.

See also:

Gets a single context line from the original input stream.

Private.

See also:

Calculates the position of the parse error in the original input stream according to the error position in the (pre-processed) parse stream. The parse stream content is likely to be quite different than the original stream as pre-processing may remove or in contrary add characters from the original stream.

Private.

See also:

Returns the name of the original input source. When parser was constructed with the first constructor referred to below (file path), it is the base file name. When parser was constructed with the first constructor referred to below (process arguments), it is 'argv'. In all other cases the name is empty.

See also:

Returns the exact name of the original input file as passed to the constructor.

If the parser object was constructed otherwise as with a file name, the name is empty.

See also:

Writes the parse statistics file.

At the moment, it just reports the number of instances created for each symbol class.

Private.

See also:

Increments the non-breaking errors counter. Called transparently when a call is made to the methods referred to below.

Private.

See also:

Returns the amount of non-breaking errors raised by calls to the following methods.

See also:

Indicates whether a syntax error was encountered.

See also:

Sets the syntax error status to bSyntaxError.

Private.

See also:

Tells whether line numbering is shown in failure messages.

By default line numbering is always visible, except when the parser was constructed for parsing application arguments (always only 1 line).

See also:

Sets whether line numbering is shown in failure messages.

By default line numbering is always visible, except when the parser was constructed for parsing application arguments (always only 1 line).

See also:

Strictly equivalent to showLineNo(false).

See also:

Activates or deactivates the checking of the number of symbol occurrences.

bYes is optional and is true by default when this function is called without argument.

By default, the number of occurrences are always checked immediately following the parsing. according to the limits if any, either specified in the grammar or set manually using the appropriate methods,

Deactivating this feature may only be relevant for performance optimization purposes.

See also:

Tells whether the number of symbol occurrences is checked according to the minimum and maximum limits.

See also:

Activates or deactivates the stream pre-processing.

bYes is optional and is true by default when this function is called without argument.

By default, the preprocessing is always performed prior to the actual parsing.

Deactivating this feature may be useful in advanced and specific uses.

See also:

Tells whether the stream pre-processing is deactivated.

See also:

This file is part of the LLOOP Reversible Object-Oriented Parser Generator. Copyright (c) 2005-2006 Michel MEHL, France. All rights reserved. LLOOP is distributed by the company ERSA SaRL.