.TH "flexc++" "1" "2008\-2023" "flexc++\&.2\&.14\&.00" "flexc++ scanner generator"

.PP 
.SH "NAME"
flexc++ \- Generate a C++ scanner class and parsing function
.PP 
.SH "SYNOPSIS"
\fBflexc++\fP [options] \fIrules\-file\fP
.PP 
.SH "DESCRIPTION"

.PP 
\fBFlexc++\fP(1) was designed after \fBflex\fP(1) and \fBflex++\fP(1)\&. Like these
latter two programs \fBflexc++\fP generates code performing pattern\-matching on text,
possibly executing actions when certain \fIregular expressions\fP are
recognized\&.
.PP 
\fBFlexc++\fP, contrary to \fBflex\fP and \fBflex++\fP, generates code that is
explicitly intended for use by \fBC++\fP programs\&. The well\-known \fBflex\fP(1)
program generates \fBC\fP source\-code and \fBflex++\fP(1) merely offers a
\fBC++\fP\-like shell around the \fIyylex\fP function generated by \fBflex\fP(1) and
hardly supports present\-day ideas about \fBC++\fP software development\&.
.PP 
Contrary to this, \fBflexc++\fP creates a \fBC++\fP class offering a predefined
member function \fBlex\fP matching input against regular expressions and
possibly executing \fBC++\fP code once regular expressions were matched\&. The
code generated by \fBflexc++\fP is pure \fBC++\fP, allowing its users to apply all
of the features offered by that language\&.
.PP 
Not every aspect of \fBflexc++\fP is covered by the man\-pages\&. In addition to
what\(cq\&s summarized by the man\-pages the \fBflexc++\fP manual offers a chapter covering
pre\-loading of input lines (allowing you to, e\&.g, display lines in which
errors are observed even though not all of the line\(cq\&s tokens have already been
scanned), as well as a chapter covering technical documentation about the
inner working of \fBflexc++\fP\&.
.PP 
Before version 2\&.08\&.00 the lexical scanner\(cq\&s specification file (e\&.g\&.,
\fIlexer\fP) could be split into several files using \fI//include\fP directives,
but \fI//include\fP directives required that all files were specified relative
to the location of the \fIlexer\fP file itself\&. E\&.g\&., if \fIinc/part1\fP had to
include \fIpart2\fP, available in the same (\fIinc\fP) directory as \fIpart1\fP,
then \fIpart1\fP had to specify \fI//include inc/part2\fP instead of merely
\fI//include part2\fP\&.
.PP 
Starting with version 2\&.08\&.00 \fI//include\fP directives use the directories
of the files containing these directories as the current directory\&. In
the provided example \fIpart1\fP should simply contain \fI//include part2\fP\&. See
the \fBflexc++\fP \fBflexc++api\fP(3) and \fBflexc++input\fP(7) man\-pages for
details\&.
.PP 
\fBFlexc++\fP offers several man\-pages\&. These man\-pages contain the following main
sections: 
.PP 
\fBThis man\-page\fP
.PP 
This man\-page offers the following sections:
.PP 
.IP o 
\fB1\&. QUICK START\fP: a quick start overview about how to use \fBflexc++\fP;
.IP o 
\fB2\&. QUICK START: FLEXC++ and BISONC++\fP: a quick start overview
about how to use \fBflexc++\fP in combination with \fBbisonc++\fP(1);
.IP o 
\fB3\&. GENERATED FILES\fP: files generated by \fBflexc++\fP and their purposes
.IP o 
\fB4\&. OPTIONS\fP: options available for \fBflexc++\fP\&.

.PP 
The \fBflexc++api\fP(3) man\-page:
.PP 
This man\-page describes the classes generated by \fBflexc++\fP, describing \fBflexc++\fP\(cq\&s
actions from the programmer\(cq\&s point of view\&.
.PP 
.IP o 
\fB1\&. INTERACTIVE SCANNERS\fP: how to create an interactive scanner
.IP 
.IP o 
\fB2\&. THE CLASS INTERFACE: SCANNER\&.H\fP: Constructors and members
of the scanner class generated by \fBflexc++\fP 
.IP o 
\fB3\&. NAMING CONVENTION\fP: symbols defined by \fBflexc++\fP in the scanner
class\&. 
.IP o 
\fB4\&. CONSTRUCTORS\fP: constructors defined in the scanner class\&.
.IP o 
\fB5\&. PUBLIC MEMBER FUNCTION\fP: public member declared in the scanner
class\&.
.IP o 
\fB6\&. PRIVATE MEMBER FUNCTIONS\fP: private members declared in the
scanner class\&.
.IP o 
\fB7\&. SCANNER CLASS HEADER EXAMPLE\fP: an example of a generated
scanner class header
.IP 
.IP o 
\fB8\&. THE SCANNER BASE CLASS\fP: the scanner class is derived from a
base class\&. The base class is described in this section
.IP o 
\fB9\&. PUBLIC ENUMS AND \-TYPES\fP: enums and types declared by the
base class
.IP o 
\fB10\&. PROTECTED ENUMS AND \-TYPES\fP: enumerations and types used by
the scanner and scanner base classes
.IP o 
\fB11\&. NO PUBLIC CONSTRUCTORS\fP: the scanner base class does not
offer public constructors\&.
.IP o 
\fB12\&. PUBLIC MEMBER FUNCTIONS\fP: several members defined by the
scanner base class have public access rights\&.
.IP o 
\fB13\&. PROTECTED CONSTRUCTORS\fP: the base class can be constructed by
a derived class\&. Usually this is the scanner class generated by \fBflexc++\fP\&.
.IP o 
\fB14\&. PROTECTED MEMBER FUNCTIONS\fP: this section covers the base
class member functions that can only be used by scanner class or
scanner base class members
.IP o 
\fB15\&. PROTECTED DATA MEMBERS\fP: this section covers the base class
data members that can only be used by scanner class or scanner base
class members
.IP o 
\fB16\&. FLEX++ TO FLEXC++ MEMBERS\fP: a short overview of frequently
used \fBflex\fP(1) members that received different names in \fBflexc++\fP\&.
.IP 
.IP o 
\fB17\&. THE CLASS INPUT\fP: the scanner\(cq\&s job is completely decoupled
from the actual input stream\&. The class \fIInput\fP, nested within the
scanner base class handles the communication with the input
streams\&. The  class \fIInput\fP, is described in this section\&.
.IP o 
\fB18\&. INPUT CONSTRUCTORS\fP: the class \fIInput\fP can easily be
replaced by another class\&. The constructor\-requirements are described
in this section\&.
.IP o 
\fB19\&. REQUIRED PUBLIC MEMBER FUNCTIONS\fP: this section covers the
required public members of a self\-made \fIInput\fP class

.PP 
The \fBflexc++input\fP(7) man\-page:
.PP 
This man\-page describes how \fBflexc++\fP\(cq\&s input \fBs\fP should be organized\&. It
contains the following sections:
.PP 
.IP o 
\fB1\&. SPECIFICATION FILE(S)\fP: the format and contents of \fBflexc++\fP input
files, specifying the Scanner\(cq\&s characteristics
.IP o 
\fB2\&. FILE SWITCHING\fP: how to switch to another input specification
file
.IP o 
\fB3\&. DIRECTIVES\fP: directives that can be used in input
specification files
.IP o 
\fB4\&. MINI SCANNERS\fP: how to declare mini\-scanners
.IP o 
\fB5\&. DEFINITIONS\fP: how to define symbolic names for regular
expressions
.IP o 
\fB6\&. %% SEPARATOR\fP: the separator between the input specification
sections 
.IP o 
\fB7\&. REGULAR EXPRESSIONS\fP: regular expressions supported by \fBflexc++\fP
.IP o 
\fB8\&. SPECIFICATION EXAMPLE\fP: an example of a specification file

.PP 
.SH "1\&. QUICK START"

.PP 
A bare\-bones, no\-frills scanner is generated as follows:
.PP 
.IP o 
First define a subdirectory \fIscanner\fP, and change\-dir to
\fIscanner\fP\&. This directory is going to contain all scanner\-related files,
created next\&.
.IP 
.IP o 
Create a file \fIlexer\fP defining the regular expressions to
recognize, and the tokens to return\&. Use token values exceeding 0xff when
plain ascii character values could also be used as token values\&. Example
(assume capitalized words are token\-symbols defined in an enum defined by the
scanner class):
.nf 

%%
[ \et\en]+                            // skip white space chars\&.
[0\-9]+                              return NUMBER;
[[:alpha:]_][[:alpha:][:digit:]_]*  return IDENTIFIER;
\&.                                   return matched()[0];
        
.fi 

.IP 
.IP o 
Execute:
.nf 

    flexc++ lexer
        
.fi 
This generates four files: \fIScanner\&.h, Scanner\&.ih, Scannerbase\&.h\fP, and
\fIlex\&.cc\fP\&.
.IP 
.IP o 
Edit \fIScanner\&.h\fP to add the enum defining the token\-symbols in
(usually) the public section of the class \fIScanner\fP\&. E\&.g\&.,
.nf 

class Scanner: public ScannerBase
{
    public:
        enum Tokens
        {
            IDENTIFIER = 0x100,
            NUMBER
        };
    // \&.\&.\&. (etc, as generated by flexc++)
}
        
.fi 

.IP 
.IP o 
Change\-dir to \fIscanner\(cq\&s\fP base directory, and there create a file
\fImain\&.cc\fP defining \fIint main\fP:
.nf 

#include <iostream>
#include \(dq\&scanner/Scanner\&.h\(dq\&

using namespace std;

int main()
{
    Scanner scanner;        // define a Scanner object

    while (int token = scanner\&.lex())   // get all tokens
    {
        string const &text = scanner\&.matched();
        switch (token)
        {
            case Scanner::IDENTIFIER:
                cout << \(dq\&identifier: \(dq\& << text << \(cq\&\en\(cq\&;
            break;

            case Scanner::NUMBER:
                cout << \(dq\&number: \(dq\& << text << \(cq\&\en\(cq\&;
            break;

            default:
                cout << \(dq\&char\&. token: `\(dq\& << text << \(dq\&\(cq\&\en\(dq\&;
            break;
        }
    }
}
        
.fi 
.IP o 
Compile all \fI\&.cc\fP files, creating \fIa\&.out\fP:
.nf 

    g++ *\&.cc scanner/*\&.cc
        
.fi 

.IP 
.IP o 
To `tokenize\(cq\& \fImain\&.cc\fP, execute:
.nf 

    a\&.out < main\&.cc
        
.fi 

.PP 
.SH "2\&. QUICK START: FLEXC++ and BISONC++"

.PP 
To interface \fBflexc++\fP to the \fBbisonc++\fP(1) parser generator proceed as follows:
.IP o 
Start from the directory containing \fImain\&.cc\fP used in the previous
section; the lexical scanner developed there is also used here\&.
.IP o 
Create a directory \fIparser\fP and change\-dir to that directory\&.
.IP 
.IP o 
Define the following grammar in the file \fIgrammar\fP:
.nf 

%scanner        \&.\&./scanner/Scanner\&.h
%token\-path     \&.\&./scanner/tokens\&.h
        
%token IDENTIFIER NUMBER CHAR

%%

startrule:
    startrule tokenshow
|
    tokenshow
;

tokenshow:
    token
    {
        std::cout << \(dq\&matched: \(dq\& << d_scanner\&.matched() << \(cq\&\en\(cq\&;
    }
;

token:
    IDENTIFIER
|
    NUMBER
|
    CHAR
;
    
.fi 

.IP 
.IP o 
Create the parser by executing:
.nf 

bisonc++ grammar
    
.fi 
This generates five files: \fIparse\&.cc, Parserbase\&.h, Parser\&.h,
\fIParser\&.ih\fP\fP and \fI\&.\&./scanner/tokens\&.h\fP, where the last file contains 
the class \fITokens\fP defining the enumeration \fITokens_\fP specifying the
symbolic token names\&. 
.IP 
.IP o 
Now that the parser has been defined, edit the (three) lines in the
file \fI\&.\&./scanner/lexer\fP containing return statements\&. Change these lines
as follows (the first two lines of the file \fIlexer\fP remain as\-is):
.nf 

[0\-9]+                              return Tokens::NUMBER;
[[:alpha:]_][[:alpha:][:digit:]_]*  return Tokens::IDENTIFIER;
\&.                                   return Tokens::CHAR;
    
.fi 
This allows the scanner to  return \fIParser\fP tokens to the generated
parser\&. 
.IP 
.IP o 
Modify the scanner so that it returns these \fIParser\fP tokens
by executing:
.nf 

    flexc++ lexer
        
.fi 

.IP 
.IP o 
Next, add the line
.nf 

    #include \(dq\&tokens\&.h\(dq\&
        
.fi 
to the file \fIscanner/Scanner\&.ih\fP, informing the scanner about the
existence of the tokens expected by the parser\&. 
.IP 
If ever you have to use members from the parser\(cq\&s base class generated by
\fBbisonc++\fP(1), then 
.nf 

    #include \(dq\&\&.\&./parser/Parserbase\&.h\(dq\&
        
.fi 
should be added to the file \fIscanner/Scanner\&.ih\fP\&. In that case including
the file \fItoken\&.h\fP in \fIscanner/Scanner\&.ih\fP is optional\&.
.IP 
.IP o 
Change\-dir to the \fIscanner\(cq\&s\fP parent directory and rewrite the
\fImain\&.cc\fP file defined in the previous section to contain:
.nf 

#include \(dq\&parser/Parser\&.h\(dq\&

int main(int argc, char **argv)
{
    Parser parser;
    parser\&.parse();
}
    
.fi 

.IP 
.IP o 
Compile all sources:
.nf 

    g++ *\&.cc */*\&.cc
        
.fi 

.IP 
.IP o 
Execute the program, providing it with some source file to be
processed:
.nf 

    a\&.out < main\&.cc
        
.fi 

.PP 
.SH "3\&. GENERATED FILES"

.PP 
\fBFlexc++\fP generates four files from a well\-formed input file:

.IP 
.IP o 
A file containing the implementation of the \fIlex\fP member function
and its support functions\&. By default this file is named \fIlex\&.cc\fP\&.
.IP 
.IP o 
A file containing the scanner\(cq\&s class interface\&. By default this file
is named \fIScanner\&.h\fP\&. The scanner class itself is generated once and is
thereafter `owned\(cq\& by the programmer, who may change it \fIad\-lib\fP\&. Newly
added members (data members, function members) will survive future \fBflexc++\fP runs
as \fBflexc++\fP will never rewrite an existing scanner class interface file, unless
explicitly ordered to do so\&. 
.IP 
.IP o 
A file containing the interface of the scanner class\(cq\&s \fIbase
class\fP\&. The scanner class is publicly derived from this base class\&. It is used
to minimize the size of the scanner interface itself\&. The scanner base class
is `owned\(cq\& by \fBflexc++\fP and should never be hand\-modified\&. By
default the scanner\(cq\&s base class is provided in the file
\fIScannerbase\&.h\fP\&. At each new \fBflexc++\fP run this file is rewritten unless \fBflexc++\fP
is explicitly ordered \fInot\fP to do so\&.
.IP 
.IP o 
A file containing the \fIimplementation header\fP\&. This file should
contain includes and declarations that are only required when compiling the
members of the scanner class\&. By default this file is named
\fIScanner\&.ih\fP\&. This file, like the file containing the scanner class\(cq\&s
interface is never rewritten by \fBflexc++\fP unless \fBflexc++\fP is explicitly ordered to do
so\&.

.PP 
.SH "4\&. OPTIONS"

.PP 
Where available, single letter options are listed between parentheses
following their associated long\-option variants\&. Single letter options require
arguments if their associated long options require arguments as well\&.  Options
affecting the class header or implementation header file are ignored if these
files already exist\&. Options accepting a `filename\(cq\& do not accept path names,
i\&.e\&., they cannot contain directory separators (\fI/\fP); options accepting a
\(cq\&pathname\(cq\& may contain directory separators\&.
.PP 
Some options may generate errors\&. This happens when an option conflicts with
the contents of an existing file which \fBflexc++\fP cannot modify (e\&.g\&., a scanner
class header file exists, but doesn\(cq\&t define a name space, but a
\fI\-\-namespace\fP option was provided)\&. To solve the error the offending option
could be omitted, the existing file could be removed, or the existing file
could be hand\-edited according to the option\(cq\&s specification\&. Note that \fBflexc++\fP
currently does not handle the opposite error condition: if a previously used
option is omitted, then \fBflexc++\fP does not detect the inconsistency\&. In those
cases you may encounter compilation errors\&.
.PP 
.IP o 
\fB\-\-baseclass\-header\fP=\fIfilename\fP (\fB\-b\fP)
.br 
Use \fIfilename\fP as the name of the file to contain the scanner
class\(cq\&s base class\&. Defaults to the name of the scanner class plus
\fIbase\&.h\fP
.IP 
It is an error if this option is used and an already
existing scanner\-class header file does not include
\fI`filename\(cq\&\fP\&. 
.IP 
.IP o 
\fB\-\-baseclass\-preinclude\fP=\fIpathname\fP (\fB\-H\fP)
.br 
\fIPathname\fP defines the path to the file preincluded in the
scanner\(cq\&s base\-class header\&. This option (or the corresponding
directive) may be required when using a user\-defined \fIInput\fP
class using types etc\&. which aren\(cq\&t yet provided by the scanner\(cq\&s
base class header\&. E\&.g\&., if a user\-defined \fIInput\fP class uses a
stack, then \fI#include <stack>\fP must have been declared when
compiling that class (see the description of the \fI%input\-\&.\&.\&.\fP
declarations in the \fBflexc++input\fP(7) man\-page for details)\&.  By
specifying this option (or the corresponding directive) the
required header(s) are included when compiling the files generated
by \fBflexc++\fP\&. By default the \fIpathname\fP argument is surrounded by
double quotes (which can also explicitly be
provided)\&. Alternatively, if \fIpathname\fP is surrounded by pointed
brackets then those are used\&.
.IP 
.IP o 
\fB\-\-baseclass\-skeleton\fP=\fIpathname\fP (\fB\-C\fP)
.br 
Use \fIpathname\fP as the path to the file containing the skeleton of
the scanner class\(cq\&s base class\&. Its filename defaults to
\fIflexc++base\&.h\fP\&.
.IP 
.IP o 
\fB\-\-case\-insensitive\fP
.br 
Use this option to generate a scanner \fIcase insensitively\fP
matching regular expressions\&. All regular expressions specified in
\fBflexc++\fP\(cq\&s input file are interpreted case insensitively and the
resulting scanner object will case insensitively interpret its
input\&. 
.IP 
When this option is specified the resulting scanner does not
distinguish between the following rules:
.nf 

        First       // initial F is transformed to f
        first
        FIRST       // all capitals are transformed to lower case chars
                
.fi 
With a case\-insensitive scanner only the first rule can be matched,
and \fBflexc++\fP will issue warnings for the second and third rule about
rules that cannot be matched\&.
.IP 
Input processed by a case\-insensitive scanner is also handled case
insensitively\&. The above mentioned \fIFirst\fP rule is matched for
all of the following input words: \fIfirst First FIRST firST\fP\&. 
.IP 
Although the matching process proceeds case insensitively, the
matched text (as returned by the scanner\(cq\&s \fImatched()\fP member)
always contains the original, unmodified text\&. So, with the above
input \fImatched()\fP returns, respectively \fIfirst, First, FIRST\fP
and \fIfirST\fP, while matching the rule \fIFirst\fP\&.
.IP 
.IP o 
\fB\-\-class\-header\fP=\fIfilename\fP (\fB\-c\fP)
.br 
Use \fIfilename\fP as the name of the file to contain the scanner
class\&. Defaults to the name of the scanner class plus the suffix
\fI\&.h\fP
.IP 
.IP o 
\fB\-\-class\-name\fP=\fIclassName\fP
.br 
Use \fIclassName\fP (rather than \fIScanner\fP) as the name of the
scanner class\&. Unless overridden by other options generated files
will be given the (transformed to lower case) \fIclassName*\fP name
instead of \fIscanner\fP*\&.
.IP 
It is an error if this option is used and an already
existing scanner\-class header file does not define \fIclass
`className\(cq\&\fP
.IP 
.IP o 
\fB\-\-class\-skeleton\fP=\fIpathname\fP (\fB\-C\fP)
.br 
Use \fIpathname\fP as the path to the file containing the skeleton of
the scanner class\&. Its filename defaults to \fIflexc++\&.h\fP\&.
.IP 
.IP o 
\fB\-\-construction\fP (\fB\-K\fP)
.br 
Write details about the lexical scanner to the file
\fI`rules\-file\(cq\&\&.output\fP\&. Details cover the used character ranges,
information about the regexes, the raw NFA states, and the final
DFAs\&.
.IP 
.IP o 
\fB\-\-debug\fP (\fB\-d\fP)
.br 
Provide \fIlex\fP and its support functions with debugging code,
showing the actual parsing process on the standard output
stream\&. When included, the debugging output is active by default,
but its activity may be controlled using the \fIsetDebug(bool
on\-off)\fP member\&. Note that \fI#ifdef DEBUG\fP macros are not used
anymore\&. By rerunning \fBflexc++\fP without the \fB\-\-debug\fP option an
equivalent scanner is generated not containing the debugging
code\&. This option does not provide debug information about \fBflexc++\fP
itself\&. For that use the options \fI\-\-own\-parser\fP and/or
\fI\-\-own\-tokens\fP (see below)\&. 
.IP 
.IP o 
\fB\-\-filenames\fP=\fIgenericName\fP (\fB\-f\fP)
.br 
Generic name of generated files (header files, not the
\fIlex\fP\-function source file, see the \fI\-\-lex\-source\fP option for
that)\&. By default the header file names will be equal to the name
of the generated class\&.
.IP 
.IP o 
\fB\-\-help\fP (\fB\-h\fP)
.br 
Write basic usage information to the standard output stream and
terminate\&. 
.IP 
.IP o 
\fB\-\-implementation\-header\fP=\fIfilename\fP (\fB\-i\fP)
.br 
Use \fIfilename\fP as the name of the file to contain the
implementation header\&. Defaults to the name of the generated
scanner class plus the suffix \fI\&.ih\fP\&. The implementation header
should contain all directives and declarations \fIonly\fP used by
the implementations of the scanner\(cq\&s member functions\&. It is the
only header file that is included by the source file containing
\fBlex()\fP\(cq\&s implementation\&.  User defined implementation of other
class members may use the same convention, thus concentrating all
directives and declarations that are required for the compilation
of other source files belonging to the scanner class in one header
file\&.
.IP 
It is an error if this option is used and an already existing
\fI\(cq\&filename\(cq\&\fP file does not include the scanner class header
file\&.
.IP 
.IP o 
\fB\-\-implementation\-skeleton\fP=\fIpathname\fP (\fB\-I\fP)
.br 
Use \fIpathname\fP as the path to the file containing the skeleton of
the implementation header\&. Its filename defaults to
\fIflexc++\&.ih\fP\&.
.IP 
.IP o 
\fB\-\-lex\-skeleton\fP=\fIpathname\fP (\fB\-L\fP)
.br 
Use \fIpathname\fP as the path to the file containing the
\fIlex()\fP member function\(cq\&s skeleton\&. Its filename defaults to
\fIflexc++\&.cc\fP\&.
.IP 
.IP o 
\fB\-\-lex\-function\-name\fP=\fIfunname\fP
.br 
Use \fIfunname\fP rather than \fIlex\fP as the name of the member
function performing the lexical scanning\&.
.IP 
.IP o 
\fB\-\-lex\-source\fP=\fIfilename\fP (\fB\-l\fP)
.br 
Define \fIfilename\fP as the name of the source file to contain the
scanner member function \fIlex\fP\&. Defaults to \fIlex\&.cc\fP\&.
.IP 
.IP o 
\fB\-\-matched\-rules\fP (\fB\-\(cq\&R\(cq\&\fP)
.br 
The generated scanner will write the numbers of matched rules to 
the standard output\&. It is implied by the \fI\-\-debug\fP option\&.
Displaying the matched rules can be suppressed by calling the
generated  scanner\(cq\&s member \fIsetDebug(false)\fP (or, of course, by
re\-generating the scanner without using specifying 
\fI\-\-matched\-rules\fP)\&.
.IP 
.IP o 
\fB\-\-max\-depth\fP=\fIdepth\fP (\fB\-m\fP)
.br 
Set the maximum inclusion depth of the lexical scanner\(cq\&s
specification files to \fIdepth\fP\&. By default the maximum depth is
set to 10\&. When more than \fIdepth\fP specification files are used
the scanner throws a \fIMax stream stack size exceeded\fP
\fIstd::length_error\fP exception\&. 
.IP 
.IP o 
\fB\-\-namespace\fP=\fIidentifier\fP 
.br 
Define the scanner class in the namespace \fIidentifier\fP\&. By default
no namespace is used\&. If this options is used the
implementation header is provided with a commented out \fIusing
namespace\fP declaration for the requested namespace\&.  In addition,
the scanner and scanner base class header files also use the 
specified namespace to define their include guard directives\&.
.IP 
It is an error if this option is used and an already existing
scanner\-class header file does not define \fInamespace
identifier\fP\&. 
.IP 
.IP o 
\fB\-\-no\-baseclass\-header\fP
.br 
Do not write the file containing the scanner\(cq\&s base class interface
even if it doesn\(cq\&t yet exist\&. By default the file containing the
scanner\(cq\&s base class interface is (re)written each time \fBflexc++\fP is
called\&.
.IP 
.IP o 
\fB\-\-no\-lines\fP
.br 
Do not put \fB#line\fP preprocessor directives in the file containing
the scanner\(cq\&s \fIlex\fP function\&. By default \fI#line\fP directives
are entered at the beginning of the action statements in the
generated \fIlex\&.cc\fP file, allowing the compiler and debuggers
to associate errors with lines in your grammar specification
file, rather than with the source file containing the \fIlex\fP
function itself\&.
.IP 
.IP o 
\fB\-\-no\-lex\-source\fP
.br 
Do not write the file containing the scanner\(cq\&s predefined scanner
member functions, even if that file doesn\(cq\&t yet exist\&. By default
the file containing the scanner\(cq\&s \fIlex\fP member function is
(re)written each time \fBflexc++\fP is called\&. This option
should normally be avoided, as this file contains parsing
tables which are altered whenever the grammar definition is
modified\&. 
.IP 
.IP o 
\fB\-\-own\-parser\fP (\fB\-P\fP)
.br 
The actions performed by \fBflexc++\fP\(cq\&s own parser are written to the
standard output stream\&.
.IP 
This option does \fInot\fP result in the generated program optionally
displaying the actions of its \fIlex\fP function\&. If that is what
you want, use the \fI\-\-debug\fP option\&.
.IP 
.IP o 
\fB\-\-own\-tokens\fP (\fB\-T\fP)
.br 
The tokens returned as well as the text matched by \fBflexc++\fP are
written to the standard output stream when this option is used\&.
.IP 
This option does \fInot\fP result in the generated program displaying
returned tokens and matched text\&. If that is what you want, use
the \fI\-\-print\-tokens\fP option\&.
.IP 
.IP o 
\fB\-\-print\-tokens\fP (\fB\-t\fP)
.br 
The tokens returned as well as the text matched by the
\fIgenerated\fP \fIlex\fP function are displayed on the standard
output stream, just before returning the token to \fIlex\fP\(cq\&s
caller\&. Displaying tokens and matched text is suppressed again
when the \fIlex\&.cc\fP file is generated without using this
option\&. The function showing the tokens (\fIScannerBase::print_\fP)
is called from \fIScanner::printTokens\fP, which is defined in\-line
in \fIScanner\&.h\fP\&. Calling \fIScannerBase::print_\fP, therefore, can
also easily be controlled by an option controlled by the program
using the scanner object\&.
.IP 
This option does \fInot\fP show the tokens returned and text matched
by \fBflexc++\fP itself when reading its input \fBs\fP\&. If that is what
you want, use the \fI\-\-own\-tokens\fP option\&.
.IP 
.IP o 
\fB\-\-regex\-calls\fP
.br 
Show the function call order when parsing regular expressions (this
option is normally not required\&. Its main purpose is to help
developers understand what happens when regular expressions are
parsed)\&.
.IP 
.IP o 
\fB\-\-show\-filenames\fP (\fB\-F\fP)
.br 
Write the names of the files that are generated to the 
standard error stream\&.
.IP 
.IP o 
\fB\-\-skeleton\-directory\fP=\fIpathname\fP (\fB\-S\fP)
.br 
Defines the directory containing the skeleton files\&. This option
can be overridden by the specific skeleton\-specifying options
(\fI\-B \-C, \-H,\fP and \fI\-I\fP)\&.
.IP 
.IP o 
\fB\-\-target\-directory\fP=\fIpathname\fP 
.br 
Specifies the directory where generated files should be written\&.
By default this is the directory where \fBflexc++\fP is called\&.
.IP 
.IP o 
\fB\-\-usage\fP (\fB\-h\fP)
.br 
Write basic usage information to the standard output stream and
terminate\&. 
.IP 
.IP o 
\fB\-\-verbose\fP(\fB\-V\fP)
.br 
The verbose option generates on the standard output stream various
pieces of additional information, not covered by the
\fI\-\-construction\fP and \fI\-\-show\-filenames\fP options\&.
.IP 
.IP o 
\fB\-\-version\fP (\fB\-v\fP)
.br 
Display \fBflexc++\fP\(cq\&s version number and terminate\&.

.PP 
.SH "FILES"

.PP 
\fBFlexc++\fP\(cq\&s default skeleton files are in \fI/usr/share/flexc++\fP\&.
.br 
By default, \fBflexc++\fP generates the following files:
.IP o 
\fIScanner\&.h\fP: the header file containing the scanner class\(cq\&s
interface\&. 
.IP o 
\fIScannerbase\&.h\fP: the header file containing the interface of the 
scanner class\(cq\&s base class\&.
.IP o 
\fIScanner\&.ih\fP: the internal header file that is meant to be included
by the scanner class\(cq\&s source files (e\&.g\&., it is included by
\fIlex\&.cc\fP, see the next item\(cq\&s file), and that should contain all
declarations required for compiling the scanner class\(cq\&s sources\&.
.IP o 
\fIlex\&.cc\fP: the source file implementing the scanner class member
function \fIlex\fP (and support functions), performing the lexical
scan\&.

.PP 
.SH "SEE ALSO"

.PP 
\fBbisonc++\fP(1), \fBflexc++api\fP(3), \fBflexc++input\fP(7)
.PP 
.SH "BUGS"

.PP 
None reported
.PP 
.SH "ABOUT flexc++"

.PP 
\fBFlexc++\fP was originally started as a programming project by Jean\-Paul van
Oosten and Richard Berendsen in the 2007\-2008 academic year\&. After graduating,
Richard left the project and moved to Amsterdam\&. Jean\-Paul remained in
Groningen, and after on\-and\-off activities on the project, in close
cooperation with Frank B\&. Brokken, Frank undertook a rewrite of the project\(cq\&s
code around 2010\&. During the development of \fBflexc++\fP, the lookahead\-operator
handling continuously threatened the completion of the project\&. But in
version 2\&.00\&.00 the lookahead operator received a completely new
implementation (with a bug fix in version 2\&.04\&.00), which solved previously
encountered problems with the lookahead\-operator\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the 
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP),
.br 
Jean\-Paul van Oosten (\fBj\&.p\&.van\&.oosten@rug\&.nl\fP),
.br 
Richard Berendsen (\fBrichardberendsen@xs4all\&.nl\fP) (until 2010)\&.
.br 

.PP