LLOOP GSP Language Reference

Overview
Symbol Definitions

Overview
Importing gsp files
Tokens
Non-terminals
Command Line Options
Pre-processors
Post-processors
Symbol Inheritances
Symbol Self-tests
Symbol Aliases
Symbol Count Limits
Including C++ Header Files
Recommendations

Syntax Rules Definitions

BNF Syntax Rules
Syntax Rule Reduction Code
Syntax Rule Expand Code
Getting parsed symbols values within reduction code

A GSP file is written in plain text files which should have the " .gsp " file extension.

Its content divides into two parts :

The symbol definitions. The type of symbols that can be defined are the following:

pre-processors
tokens
non-terminals standing for syntax rules
command line options

Symbols which are defined outside the gsp file can be imported into the current gsp file with an appropriate instruction.

The GSP grammar in BNF notation, describing syntax rules and reduction codes for all non-terminals.

A GSP file can be empty. There is also rarely no definition to provide for a symbol, because there is always at least one token needed. Most time some symbols also need to be defined for integration purposes with the final application in the target programming language.

Overview

The following types can be defined in the scope of the symbol definitions:

tokens
non-terminals
command line options
pre-processors
post-processors

Any symbol definition, i.e. token, non-terminal or option, offers the following common features:

a symbol can inherit from a C++ class or another symbol
aliases can be defined for it
unit tests can be defined for it
specification of the minimum and maximum number of times the symbol can occur
inclusion of additional C++ header files

Importing gsp files

Purpose

Importing a gsp file allows to include into the current gsp file all the pre-processors, non-terminals or tokens defined in that gsp file. This allows to keep gsp specifications modular, reusable, shareable and readable.

Statement

A GSP file is imported using the keyword import and the name of that file without the " .gsp " file extension.

'import' word ';'

Example:

import int;

There are numerous other examples.

Tokens

Declaration

A token is declared with the keyword token, a name followed by some options, and finally the token implementation code.

'token' word [ SymbolDef ] [ Include ] [ Alias ] [ 'declare' '{{' Block '}}' ] [ 'implement' '{{' Block '}}' ] ['parse'] '{{' Block '}}' [ [ 'expand' ] '{{' Block '}}' ] [ STestCode ]

Principle

The token is is parsed according to the C++ parse code defined for it.

Inheritances can be defined for tokens.
Aliases can be defined for tokens.
Self-tests can be defined for tokens.
C++ includes can be defined for tokens.

Parse Code

A Token is written with C/C++ code enclosed by {{ and }}.

The principle for parsing a token is to read chars one by one from the input as long as a valid char sequence is found for the token.

The input from which to read the input chars is accessible via the following implicit and pre-declared reference :

istream& is

If the read chars are not valid for the token, the parsing can be aborted at any moment by calling the following method:

abort() ;

IMPORTANT: Once a token has been successfully parsed, the input stream pointer shall be re-positioned on the first not-accepted char.

Additional C++ code can be embedded within the token definition using the notations given below. For an example, check the standard block token.

declare {{ ... }}

implement {{ ... }}

Please check the standard block token as example.

Expand code

If the parser should be reversible, the user should also provide the C++ code that allows to re-construct and output the token value (expand code).

The expand code is written with C/C++ code enclosed by {{ and }}.

The expand code is executed when one of the following method is called on the parsed symbol object (generated for a sample token named IdToken):

bool expand()
String expand()

The output chars can be written into the following implicit and pre-declared reference :

ostream& os

Example :

Non-terminals

Outline

An explicit definition of a non-terminal is useful whenever the user wants to make inherit the non-terminal from an application class, which is actually likely to be the most common case. This explains why.

Declaration

A symbol is declared with the keyword symbol and a name.

 ('symbol'|'string') word [ SymbolDef ] [ImplementsOption] [ Include ] [ Alias ] [ STestCode ] ';'

It is not mandatory to provide a definition for a non-terminal prior to giving its syntax rules. A non-terminal is implicitly defined if a syntax rule is provided for it.

For convenience, it is possible to declare a non-terminal as a string. In that case, the generated symbol class inherits from the standard String class:

string Name;

is equivalent to

symbol Name extends class universal::String()  
  include "universal__String";

Principle

The non-terminal is parsed according to the syntax rule(s) which is (are) mandatory defined for it.

Inheritances can be defined for non-terminals.
Aliases can be defined for non-terminals.
Self-tests can be defined for non-terminals.
C++ includes can be defined for non-terminals.

Examples

Check the examples.

Command Line Options

Outline

LLOOP allows to fully automate the management of command line options without any programming. This is achieved simply by providing a specification for the set of options to recognise, i.e. at least an identifying keyword and a type of expected value, if any, for each option.

It is also possible to define subsets of options within a set of options. This allows to structure hierarchically all options and manage the complexity of highly configurable applications in an organised manner.

Declaration of Options

A non-terminal symbol can declared as implementing a command line option inside the non-terminal definition, using the keyword implements option followed by the specific data defining the option, enclosed by parenthesis ( ) :

ImplementsOption ::= 'implements' 'option' '(' quote ',' quote ',' quote ',' quote { ',' quote } { ',' word } ')'

options

Option Data	Meaning
Label	The name describing what the option is about
Synopsis	A line documenting the usage of the option
Documentation	The comprehensive documentation of the option
Switch(s)	The list of keywords which can be used as switch for the option
Value(s)	The list of expected symbol (token, non-terminal) to be read after the switch. There can be none or several. Even if several values can be specified for an option, in general, there is often only one value associated with it

Declaration of Option Sets

A non-terminal symbol can declared as implementing an option set inside the non-terminal definition, using the keyword implements optionset followed by the specific data defining the option set, enclosed by parenthesis ( ):

ImplementsOption ::= ...
'| 'implements' 'optionset' '(' quote ',' quote ','  symbolpath ')' 
symbolpath ::= word { '.' word }

option sets

Option Data	Meaning
Label	A name describing what the option set is about
Usage Preamble	Preamble to the synopsis of all options of the option set
Parse Symbol	The expected symbol (generally an external non-terminal) used to read the options of the option set

An option set shall be specified in an external (not imported) gsp specification file. In this case, the symbol is referred to as an external symbol, i.e. with the name of the gsp file without extension, followed by a dot and the symbol name.

Principle

From the specification of each option and option subset, the following is generated:

C++ Parse Code Reads and checks the passed options and their values. This is of course the base functionality provided by the generator.

C++ Formatted Usage Function Prints out, for each option, the synopsis and the label on the standard output.

C++ Formatted Help Function Prints out, for each option, the synopsis and the comprehensive documentation on the standard output.

TCL/TK Entry Forms Allows entry of options through graphical interface. This feature is detailed in the next paragraphs.

No syntax rule has to be provided for symbols defined as command line options: the generator builds implicitly the required syntax rules from the specified option data.

The following table summarises the possible rules which are implicitly defined for options and option sets depending on their specification. Note that there are as many alternative rules implicitly defined as there are different possible switches specified for an option.

Option or Option Set	Rule
Option with no value	option ::= switch
Option with value and with switch starting with `--`	option ::= switch '=' value
Option with value and with switch NOT starting with `--`	option ::= switch value
Option set	option set ::= symbol

The definition of a root syntax rule is still required for specifying which alternative options should be parsed and how.

A root syntax rule for parsing command line options would typically look like:

Arguments ::=  { Argument } {{ }}
Argument ::=  ( option1 | option2 | option3 ...)

A root syntax rule for parsing sub-options would typically look like:

SubArgument ::=  ( sub-option1 | sub-option2 | sub-option3 ...)

This advanced functionality is thoroughly used by the generator itself (gspc.exe). It can therefore be illustrated as follows by taking some excerpts of the matching specification and resulting generated code and outputs. Please note that "[...]" stands for information removed for space saving and readability purposes:

Options Specification
[...] symbol MakeExeOption implements option( "Executable", "--make-exe", "Tells whether to generate a makefile that builds an executable", "--make-exe") ; symbol MakeLibOption implements option( "Library", "--make-lib", "Tells whether to generate a makefile that builds a library", "--make-lib") ; symbol PlatformOption implements option( "Platform", "--platform=<PLATFORM>", "Gives the name [...]", PlatformName) ; [...] symbol AdvancedMakefileOptionSet implements optionset( "Advanded Makefile Option Set", "Advanded Makefile Option Set", gspc_arguments_make.ArgumentMAK) ; [...]

C++ Parse Code
gspc_arguments::Parser parser(argc, argv); parser.run();

C++ Formatted Usage Function
>gspc -- usage: gspc [ options ] [...] --make-exe Executable --make-lib Library --platform=<PLATFORM> Platform [...]

C++ Formatted Detailed Help Function
>gspc -h help: [...] --make-exe Tells whether to generate a makefile that builds an executable --make-lib Tells whether to generate a makefile that builds a library --platform=<PLATFORM> Gives the name of the platform for which the executable or library shall be build. Possible values are 'windows', 'unix' and 'all'. [...]

TCL/TK Forms

Graphical Front End

BNF Syntax Rules

A syntax rule is specified using the BNF notation. The principle of BNF is also well described in the tutorial.

It is possible to define constants which contain whitespaces, provided the following peculiarities:

When a constant is composed of whitespace chars only, the parser ensures whitespace eating is disabled before reading that constant.
The parsing is undefined or fails when a constant starts with one or several whitespace(s) char followed by normal chars.

A symbol which is defined in an external (not imported) gsp spec file can be referred to with the name of the gsp file without extension (which serves also as C++ namespace), followed by a dot and the symbol name. There is a simple academic example which demonstrates this functionality.

No syntax rule has to be provided for symbols defined as command line options: the generator builds implicitly the required syntax rules from the specified option data. This is detailed earlier on this page.

A missing rule will raise an error during generation.

Syntax Rule Reduction Code

The reduction code is written in C++ code enclosed by {{ }}.

During parsing, the reduction code of a syntax rule is executed immediately after an input was successfully parsed according to this rule.

The parser object is accessible via the following implicit and pre-declared reference :

Parser& parser

The reduction is executed internally by the generated code through the following method (generated for a sample symbol named SIniFile):

reduce()
reduce()

Trick: It is not mandatory to provide a reduction code for each alternaltive rule, except for the last one.

Syntax Rule Expand Code

The expand code is written in C++ code enclosed by {{ }}.

Providing an expand code is optional and only required if the parser should be reversible.

The expand code is executed when one of the following method is called on the parsed symbol object (generated for a sample symbol named SIniFile):

bool expand()
String expand()

The C++ output stream where to write is accessible via the following implicit and pre-declared reference :

std::ostream& os

Getting parsed symbols values within reduction code

Principle

From the reduction code, you can get access both to the parsed constants and to the objects corresponding to the parsed tokens and non-terminals, using the specific short notations detailed hereafter.

The code into which these notations are translated ensures that accesses to objects are done in a safe way. An attempt to access an unparsed optional symbol object or a repetitive symbol with an invalid index will result in an error and an appropriate error message.

Getting the value of a parsed constant

You can get the value of a parsed constant using the char " # " followed by the index of the constant among all constants of the reduced syntax rule. Example:

#1
#2

Returns respectively the first and second constant in the syntax rule.

The returned value is of the following C type:

const char*

The interest of using this notation is to refer to a constant within the reduction code independently of the actual constant value, thereby improving maintainability.

Getting a reference to a token or a non-terminal object

To get a C++ non-const object reference, use the char " $ " followed by the index of the token or non-terminal among all tokens and terminals in the reduced syntax rule. Example:

$1
$2

Returns respectively a reference to the first and second symbol objects in the syntax rule.

To get a C++ non-const object pointer, use the char " & " followed by the index of the token or non-terminal among all tokens and terminals in the reduced syntax rule. Example:

&1
&2

Returns respectively a pointer to the first and second symbol objects in the syntax rule.

Using pointers is not recommended, but is useful to check whether an optional symbol was actually parsed or not. If not parsed, the pointer is null.

Getting a reference to a token/non-terminal object in a repetitive symbol sequence

If a non-terminal/token is located within a repetitive symbol sequence, an index within that sequence must be provided additionally, enclosed by parenthesises. Example:

$1(49)

Returns the 50th instance of the symbol in the repetitive sequence.

When there are several nested repetitive sequences, an index must be specified for each of these sequences. For example, let's assume you have the following dummy syntax rule:

MyRule ::= { 'a' { 'b' MyRule } }

Here { 'a' ... } is the first repetitive sequence. This sequence includes another one which is { 'b' MyRule }.

Examples:

$1(0, 0)

Returns the first MyRule instance in the first repetitive symbol sequence.

$1(9, 2)

Returns the third instance in the 10th occurrence of the first repetitive sequence.

$1(20, 0)

Returns the first instance in the 21th occurrence of the first repetitive sequence.

Getting the number of occurrences of a repetitive symbol

To get the number of occurrence of a symbol in a repetitive sequence, use the normal notation as described above, followed by (#). Example:

#1(#)

Returns the number of occurrences of the first repetitive constant. $1(#)

Returns the number of occurrences of the first repetitive token/non-terminal.

In case of nested repetitive symbol sequences, an index for all intermediate repetitive sequence must be provided. Let's check the following examples basing on the above-mentioned dummy rule MyRule:

#1(0, #)

Returns the number of occurrences of constant b within the first occurence of the first repetitive sequence.

$1(1, #)

Returns the number of occurrences of MyRule within the second occurrence of the first repetitive sequence.

$1(20, #)

Returns the number of occurrences of MyRule within the 21th occurrence of the first repetitive sequence.

Only integer numbers or simple strings (typically variable names) are accepted and can be used as indexes.

The generator does not check whether symbol indexes following either " # ", " $ " or " $ " are out-of-range. Invalid indexes will appear as is in the generated code and will result in a compilation error.

Examples

Check the gspc_rc example, which is the gsp spec file used to parse these notations.

Check also the other examples.

C++ Parse Code	Reads and checks the passed options and their values. This is of course the base functionality provided by the generator.
C++ Formatted Usage Function	Prints out, for each option, the synopsis and the label on the standard output.
C++ Formatted Help Function	Prints out, for each option, the synopsis and the comprehensive documentation on the standard output.
TCL/TK Entry Forms	Allows entry of options through graphical interface. This feature is detailed in the next paragraphs.

LLOOP GSP Language Reference

Index

Overview

Symbol Definitions

Overview

Importing gsp files

Tokens

Non-terminals

Command Line Options

Pre-processors

Post-processors

Symbol Count Limits

Symbol Inheritances

Symbol Self-tests

Symbol Aliases

Including C++ Header Files

Recommendations

Syntax Rules Definitions

BNF Syntax Rules

Syntax Rule Reduction Code

Syntax Rule Expand Code

Getting parsed symbols values within reduction code