flexc++(1)

flexc++ scanner generator
(flexc++.2.07.00.tar.gz)

2008-2018

NAME

flexc++ - Generate a C++ scanner class and parsing function

SYNOPSIS

flexc++ [options] rules-file

DESCRIPTION

Flexc++(1) was designed after flex(1) and flex++(1). Like these latter two programs flexc++ generates code performing pattern-matching on text, possibly executing actions when certain regular expressions are recognized.

Flexc++, contrary to flex and flex++, generates code that is explicitly intended for use by C++ programs. The well-known flex(1) program generates C source-code and flex++(1) merely offers a C++-like shell around the yylex function generated by flex(1) and hardly supports present-day ideas about C++ software development.

Contrary to this, flexc++ creates a C++ class offering a predefined member function lex matching input against regular expressions and possibly executing C++ code once regular expressions were matched. The code generated by flexc++ is pure C++, allowing its users to apply all of the features offered by that language.

Not every aspect of flexc++ is covered by the man-pages. In addition to what's summarized by the man-pages the flexc++ 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's tokens have already been scanned), as well as a chapter covering technical documentation about the inner working of flexc++.

From version 0.92.00 Until version 1.07.00 flexc++ offered one big manual page. The advantage of that being that you never had to look for which manual page contained which information. At the same time, flexc++'s man-page grew into a huge man-page, in which it was hard to find your way. Starting with release 1.08.00 we reverted back to using multiple man-pages. The following index relates manual pages to their specific contents:

This man-page

This man-page offers the following sections:

The flexc++api(3) man-page:

This man-page describes the classes generated by flexc++, describing flexc++'s actions from the programmer's point of view.

The flexc++input(7) man-page:

This man-page describes how flexc++'s input s should be organized. It contains the following sections:

1. QUICK START

A bare-bones, no-frills scanner is generated as follows:

: Scanner.h, Scanner.ih, Scannerbase.h, and lex.cc

  • Edit Scanner.h, add the enum defining the token-symbols in (usually) the public section of the class Scanner. E.g.,
    
    class Scanner: public ScannerBase
    {
        public:
            enum Tokens
            {
                IDENTIFIER = 0x100,
                NUMBER
            };
        // ... (etc, as generated by flexc++)
            
    

  • Create a file defining int main, e.g.:
    
    #include <iostream>
    #include "Scanner.h"
    
    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 << "identifier: " << text << '\n';
                break;
    
                case Scanner::NUMBER:
                    cout << "number: " << text << '\n';
                break;
    
                default:
                    cout << "char. token: `" << text << "'\n";
                break;
            }
        }
    }
            
    
  • Compile all .cc files:
    
        g++ *.cc
            
    

  • To `tokenize' main.cc, execute:
    
        a.out < main.cc
            
    
    )

    2. QUICK START: FLEXC++ and BISONC++

    To interface flexc++ to the bisonc++(1) parser generator proceed as follows:

    : Scanner.h, Scanner.ih, Scannerbase.h, and lex.cc

  • Add the line
    
    #include "../parser/Parserbase.h"
        
    
    to the file scanner/Scanner.ih

  • Change back to the ./parser directory and execute:
    
    bisonc++ grammar
        
    
    This generates four files): parse.cc, Parserbase.h, Parser.h, and Parser.ih

  • Return to ./parser's parent directory and write a simple main function in the file main.cc. E.g.,
    
    #include "parser/Parser.h"
    
    int main(int argc, char **argv)
    {
        Parser parser;
    
        parser.parse();
    }
        
    

  • Compile all sources:
    
    g++ *.cc */*.cc
        
    

  • Execute the program, providing it some source file to be processed:
    
    a.out < main.cc
        
    
    )

    3. GENERATED FILES

    Flexc++ generates four files from a well-formed input file:

    4. OPTIONS

    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' do not accept path names, i.e., they cannot contain directory separators (/); options accepting a 'pathname' may contain directory separators.

    Some options may generate errors. This happens when an option conflicts with the contents of an existing file which flexc++ cannot modify (e.g., a scanner class header file exists, but doesn't define a name space, but a --namespace 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's specification. Note that flexc++ currently does not handle the opposite error condition: if a previously used option is omitted, then flexc++ does not detect the inconsistency. In those cases you may encounter compilation errors.

    FILES

    Flexc++'s default skeleton files are in /usr/share/flexc++.
    By default, flexc++ generates the following files:

    SEE ALSO

    bisonc++(1), flexc++api(3), flexc++input(7)

    BUGS

    None reported

    ABOUT flexc++

    Flexc++ 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's code around 2010. During the development of flexc++, 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.

    COPYRIGHT

    This is free software, distributed under the terms of the GNU General Public License (GPL).

    AUTHOR

    Frank B. Brokken (f.b.brokken@rug.nl),
    Jean-Paul van Oosten (j.p.van.oosten@rug.nl),
    Richard Berendsen (richardberendsen@xs4all.nl) (until 2010).