flexc++(1)

📦

version 2.19.00 · 6 versions

2.19.00 · ubuntu stonking (latest)
2.05.00 · nixos 26.05, nixpkgs unstable
2.11.00 · ubuntu jammy
2.11.02 · debian bookworm
2.15.00 · ubuntu noble
2.17.01 · debian trixie, ubuntu questing, ubuntu resolute

💖 flexc++(1) — flexc++ scanner generator 💖

okay bestie, listen UP, this is the flexc++ manual page (that's the title and the manual-section bit, btw, in case you were wondering why I'm screaming numbers) and it's literally the glow-up of your whole tokenizing era ✨

🎀 NAME 🎀

flexc++ — Generate a C++ scanner class and parsing function 🫶

🌸 SYNOPSIS 🌸

flexc++ [options] rules-file

✨ DESCRIPTION ✨

So flexc++(1) was designed after flex(1) and flex++(1). Like those two, flexc++ generates code that does pattern-matching on text, and possibly executes actions when certain regular expressions get recognized. iconic behavior, no notes 💅

But here's the tea 🍓: 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. like... it's giving 1993, bestie 😭

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. pure C++. unmatched. periodt 👑

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++. deep lore, iykyk 🧚

Before version 2.08.00 the lexical scanner's specification file (e.g., lexer) could be split into several files using //include directives, but //include directives required that all files were specified relative to the location of the lexer file itself. E.g., if inc/part1 had to include part2, available in the same (inc) directory as part1, then part1 had to specify //include inc/part2 instead of merely //include part2. okay that was lowkey chaotic of them 🙈

Starting with version 2.08.00 //include directives use the directories of the files containing these directories as the current directory. In the provided example part1 should simply contain //include part2. See the flexc++ flexc++api(3) and flexc++input(7) man-pages for details. slay, fixed it 💖

Flexc++ offers several man-pages. These man-pages contain the following main sections:

📖 This man-page

This man-page offers the following sections:

1. QUICK START: a quick start overview about how to use flexc++;
2. QUICK START: FLEXC++ and BISONC++: a quick start overview about how to use flexc++ in combination with bisonc++(1);
3. GENERATED FILES: files generated by flexc++ and their purposes;
4. OPTIONS: options available for flexc++.

📖 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.

1. INTERACTIVE SCANNERS: how to create an interactive scanner
2. THE CLASS INTERFACE: SCANNER.H: Constructors and members of the scanner class generated by flexc++
3. NAMING CONVENTION: symbols defined by flexc++ in the scanner class.
4. CONSTRUCTORS: constructors defined in the scanner class.
5. PUBLIC MEMBER FUNCTION: public member declared in the scanner class.
6. PRIVATE MEMBER FUNCTIONS: private members declared in the scanner class.
7. SCANNER CLASS HEADER EXAMPLE: an example of a generated scanner class header
8. THE SCANNER BASE CLASS: the scanner class is derived from a base class. The base class is described in this section
9. PUBLIC ENUMS AND -TYPES: enums and types declared by the base class
10. PROTECTED ENUMS AND -TYPES: enumerations and types used by the scanner and scanner base classes
11. NO PUBLIC CONSTRUCTORS: the scanner base class does not offer public constructors.
12. PUBLIC MEMBER FUNCTIONS: several members defined by the scanner base class have public access rights.
13. PROTECTED CONSTRUCTORS: the base class can be constructed by a derived class. Usually this is the scanner class generated by flexc++.
14. PROTECTED MEMBER FUNCTIONS: this section covers the base class member functions that can only be used by scanner class or scanner base class members
15. PROTECTED DATA MEMBERS: this section covers the base class data members that can only be used by scanner class or scanner base class members
16. FLEX++ TO FLEXC++ MEMBERS: a short overview of frequently used flex(1) members that received different names in flexc++.
17. THE CLASS INPUT: the scanner's job is completely decoupled from the actual input stream. The class Input, nested within the scanner base class handles the communication with the input streams. The class Input, is described in this section.
18. INPUT CONSTRUCTORS: the class Input can easily be replaced by another class. The constructor-requirements are described in this section.
19. REQUIRED PUBLIC MEMBER FUNCTIONS: this section covers the required public members of a self-made Input class

📖 The `flexc++input(7)` man-page

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

1. SPECIFICATION FILE(S): the format and contents of flexc++ input files, specifying the Scanner's characteristics
2. FILE SWITCHING: how to switch to another input specification file
3. DIRECTIVES: directives that can be used in input specification files
4. MINI SCANNERS: how to declare mini-scanners
5. DEFINITIONS: how to define symbolic names for regular expressions
6. %% SEPARATOR: the separator between the input specification sections
7. REGULAR EXPRESSIONS: regular expressions supported by flexc++
8. SPECIFICATION EXAMPLE: an example of a specification file

🚀 1. QUICK START 🚀

okay so you want a bare-bones, no-frills scanner? say less bestie, here's the whole recipe 👇

First define a subdirectory scanner, and change-dir to scanner. This directory is going to contain all scanner-related files, created next.
Create a file lexer 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):

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

Execute:

flexc++ lexer

This generates four files: Scanner.h, Scanner.ih, Scannerbase.h, and lex.cc. four whole files, we love a productive queen 🌈

Edit Scanner.h to 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++)
}

Change-dir to scanner's base directory, and there create a file main.cc defining int main:

#include <iostream>
#include "scanner/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, creating a.out:

g++ *.cc scanner/*.cc

To `tokenize' main.cc, execute:

a.out < main.cc

and that's only part 1 bestie, we're not even done yet 💜

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

okay bestie, so now we're wiring flexc++ up to the bisonc++(1) parser generator, and honestly? it's giving choreography. Do the steps in order and you'll be fine 🫶

Start from the directory containing main.cc used in the previous section; the lexical scanner developed there is also used here. (no cap, we're reusing her 👑)
Create a directory parser and change-dir to that directory.
Define the following grammar in the file grammar:

%scanner        ../scanner/Scanner.h
%token-path     ../scanner/tokens.h

%token IDENTIFIER NUMBER CHAR

%%

startrule:
    startrule tokenshow
|
    tokenshow
;

tokenshow:
    token
    {
        std::cout << "matched: " << d_scanner.matched() << '\n';
    }
;

token:
    IDENTIFIER
|
    NUMBER
|
    CHAR
;

Create the parser by executing:

bisonc++ grammar

This generates five files: parse.cc, Parserbase.h, Parser.h, Parser.ih and ../scanner/tokens.h, where that last file contains the class Tokens defining the enumeration Tokens_ specifying the symbolic token names. five files bestie, all of them iconic ✨

Now that the parser has been defined, define the directory scanner in the directory parser's parent directory, and modify the abovementioned scanner/lexer file so that it contains the %token-path directive, and edit the (three) lines in the file ../scanner/lexer so that they return tokens defined in tokens/tokens.h:

%token-path = "../tokens/tokens.h"

%%

[0-9]+                              return Tokens::NUMBER;
[[:alpha:]_][[:alpha:][:digit:]_]*  return Tokens::IDENTIFIER;
.                                   return Tokens::CHAR;

Generate the Scanner class, the scanner.ih internal header file and the file lex.cc by executing in the directory scanner the command:

flexc++ lexer

It's not very likely, but if the scanner ever has to use members of the parser's base class then add

#include "../parser/Parserbase.h"

to the file scanner/Scanner.ih. (edge case behavior, but we're ready for her 💅)

Change-dir to the scanner's parent directory and rewrite the main.cc file defined in the previous section as follows:

#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 with some source file to be processed:

a.out < main.cc

and that's the whole pipeline queen, flexc++ out here feeding bisonc++ across directories and it just works 🦋

📁 3. GENERATED FILES 📁

Flexc++ generates four files from a well-formed input file, bestie, count 'em, four:

A file containing the implementation of the lex member function and its support functions. By default this file is named lex.cc.
A file containing the scanner's class interface. By default this file is named Scanner.h. The scanner class itself is generated once and is thereafter owned by the programmer, who may change it ad-lib. Newly added members (data members, function members) will survive future flexc++ runs, because flexc++ will never rewrite an existing scanner class interface file, unless you explicitly order it to. she's respectful like that 💖
A file containing the interface of the scanner class's base class. The scanner class is publicly derived from this base class. It's used to minimize the size of the scanner interface itself. The scanner base class is owned by flexc++ and should never be hand-modified 🙈. By default the scanner's base class is provided in the file Scannerbase.h. At each new flexc++ run this file is rewritten, unless flexc++ is explicitly ordered not to do so.
A file containing the implementation header. 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 Scanner.ih. This file, like the file containing the scanner class's interface, is never rewritten by flexc++ unless flexc++ is explicitly ordered to do so.

⚠️ tl;dr vibe check: Scanner.h and Scanner.ih are yours, Scannerbase.h is hers. Touch the base class by hand at your own risk, no cap.

🎀 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 😭

--baseclass-header=filename (-b) — Use filename as the name of the file to contain the scanner class's base class. Defaults to the name of the scanner class plus base.h.

it is an error if this option is used and an already existing scanner-class header file does not include filename.

--baseclass-preinclude=pathname (-H) — pathname defines the path to the file preincluded in the scanner's base-class header. This option (or the corresponding directive) may be required when using a user-defined Input class using types etc. which aren't yet provided by the scanner's base class header. E.g., if a user-defined Input class uses a stack, then #include <stack> must have been declared when compiling that class (see the description of the %input-... declarations in the flexc++input(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 flexc++. By default the pathname argument is surrounded by double quotes (which can also explicitly be provided). Alternatively, if pathname is surrounded by pointed brackets then those are used.
--baseclass-skeleton=pathname (-C) — Use pathname as the path to the file containing the skeleton of the scanner class's base class. Its filename defaults to flexc++base.h.
--case-insensitive — Use this option to generate a scanner case insensitively matching regular expressions. All regular expressions specified in flexc++'s input file are interpreted case insensitively and the resulting scanner object will case insensitively interpret its input. 👑

When this option is specified the resulting scanner does not distinguish between the following rules:

First       // initial F is transformed to f
first
FIRST       // all capitals are transformed to lower case chars

With a case-insensitive scanner only the first rule can be matched, and flexc++ will issue warnings for the second and third rule about rules that cannot be matched.

Input processed by a case-insensitive scanner is also handled case insensitively. The above mentioned First rule is matched for all of the following input words: first First FIRST firST.

Although the matching process proceeds case insensitively, the matched text (as returned by the scanner's matched() member) always contains the original, unmodified text. So, with the above input matched() returns, respectively, first, First, FIRST and firST, while matching the rule First. the way she preserves your original casing?? we love a respectful queen 💅

--class-header=filename (-c) — Use filename as the name of the file to contain the scanner class. Defaults to the name of the scanner class plus the suffix .h.
--class-name=className — Use className (rather than Scanner) as the name of the scanner class. Unless overridden by other options, generated files will be given the (transformed to lower case) className* name instead of scanner*.

it is an error if this option is used and an already existing scanner-class header file does not define class className.

--class-skeleton=pathname (-C) — Use pathname as the path to the file containing the skeleton of the scanner class. Its filename defaults to flexc++.h.
--construction (-K) — Write details about the lexical scanner to the file rules-file.output. Details cover the used character ranges, information about the regexes, the raw NFA states, and the final DFAs. lowkey the receipts of how your scanner got built 🍓
--debug (-d) — Provide lex 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 setDebug(bool on-off) member. Note that #ifdef DEBUG macros are not used anymore. By rerunning flexc++ without the --debug option an equivalent scanner is generated not containing the debugging code. This option does not provide debug information about flexc++ itself. For that use the options --own-parser and/or --own-tokens (see below). two very different kinds of debugging bestie, don't mix them up 😭
--filenames=genericName (-f) — Generic name of generated files (header files, not the lex-function source file, see the --lex-source option for that). By default the header file names will be equal to the name of the generated class.
--help (-h) — Write basic usage information to the standard output stream and terminate. ✨
--implementation-header=filename, -i — sets filename as the name of the file that holds the implementation header. By default it's the generated scanner class name plus the suffix .ih 💅. What even is this file? It's the spot for all the directives and declarations that only the implementations of the scanner's member functions care about — and it's the only header file included by the source file containing lex()'s implementation. So if you write your own implementations of other class members, you can use the same convention, and then all the directives and declarations needed to compile every other source file belonging to the scanner class live together in one cozy little header 🏠.

🚨 It is an error if you use this option and an already existing filename file does not include the scanner class header file.

--implementation-skeleton=pathname, -I — use pathname as the path to the file containing the skeleton of the implementation header. Its filename defaults to flexc++.ih ✨.
--lex-skeleton=pathname, -L — use pathname as the path to the file containing the skeleton of the lex() member function. Its filename defaults to flexc++.cc 💖.
--lex-function-name=funname — use funname instead of lex as the name of the member function that does the lexical scanning. Renaming your main character, honestly 🎭.
--lex-source=filename, -l — define filename as the name of the source file that contains the scanner member function lex. Defaults to lex.cc 🌸.
--matched-rules, -R — the generated scanner writes the numbers of the matched rules to the standard output. It's implied by the --debug option. Wanna shut it up? Call the generated scanner's member setDebug(false) — or, of course, just regenerate the scanner without specifying --matched-rules 🫶.
--max-depth=depth, -m — sets the maximum inclusion depth of the lexical scanner's specification files to depth. Default is 10. Use more than depth specification files and the scanner throws a Max stream stack size exceeded std::length_error exception 💀.
--namespace=identifier — defines the scanner class inside the namespace identifier. By default no namespace is used. When you use this option, the implementation header gets a commented-out using namespace declaration for the requested namespace. Also, the scanner and scanner base class header files use the specified namespace to define their include guard directives 👑.

🚨 It is an error if you use this option and an already existing scanner-class header file does not define namespace identifier.

--no-baseclass-header — don't write the file containing the scanner's base class interface, even if it doesn't exist yet. By default that file is (re)written every single time flexc++ is called. So this is you telling it "bestie, hands off" 🙈.
--no-lines — no #line preprocessor directives in the file containing the scanner's lex function. By default #line directives are entered at the beginning of the action statements in the generated lex.cc file, which lets the compiler and debuggers blame errors on lines in your grammar specification file instead of on the source file containing the lex function itself. Honestly iconic error-mapping behaviour ✨.
--no-lex-source — don't write the file containing the scanner's predefined scanner member functions, even if that file doesn't exist yet. By default the file containing the scanner's lex member function is (re)written each time flexc++ is called.

😭 This option should normally be avoided, because that file contains the parsing tables, and those get altered whenever the grammar definition is modified.

--own-parser, -P — the actions performed by flexc++'s own parser are written to the standard output stream.
- Heads up: this does not make the generated program optionally display the actions of its lex function. If that's the vibe you want, use --debug instead 🔍.
--own-tokens, -T — the tokens returned as well as the text matched by flexc++ are written to the standard output stream when this option is used.
- Heads up again: this does not make the generated program display returned tokens and matched text. If that's what you want, use --print-tokens 🙌.
--print-tokens, -t — the tokens returned as well as the text matched by the generated lex function are displayed on the standard output stream, right before returning the token to lex's caller. Displaying tokens and matched text gets suppressed again when the lex.cc file is generated without using this option. The function showing the tokens (ScannerBase::print_) is called from Scanner::printTokens, which is defined in-line in Scanner.h. So calling ScannerBase::print_ can also easily be controlled by an option controlled by the program using the scanner object 🎀.
- And once more: this does not show the tokens returned and text matched by flexc++ itself when it reads its input. If that's what you want, use --own-tokens 💜.
--regex-calls — show the function call order when parsing regular expressions. Normal people do not need this one — its main purpose is helping developers understand what's happening when regular expressions are parsed 🧚.
--show-filenames, -F — write the names of the files that are generated to the standard error stream 🌈.
--skeleton-directory=pathname, -S — specifies the directory containing the skeleton files. This option can be overridden by the specific skeleton-specifying options (-B, -C, -H, and -I) 💅.
--target-directory=pathname — specifies the directory where generated files should be written. By default that's the directory where flexc++ was called 📁.
--token-path=pathname, -O — specifies the location of the file containing the struct Tokens, which defines the (parser's) symbolic tokens that can be returned by the scanner's lex() function. By default (i.e. if token_path isn't specified) symbolic tokens to be returned by the scanner's lex() function must otherwise be made available to the scanner — say, by defining them in the scanner class. The bisonc++(1) parser generator has a similar option generating the file containing the struct Tokens 👯.
--usage, -h — write basic usage information to the standard output stream and terminate. The polite lil "how do I even" button 🫶.
--verbose, -V — the verbose option generates various pieces of additional information on the standard output stream, stuff not covered by the --construction and --show-filenames options 🗣️.
--version, -v — display flexc++'s version number and terminate ⭐.

🌸 FILES 🌸

Flexc++'s default skeleton files live in /usr/share/flexc++ 🏡.

By default, flexc++ generates the following files:

Scanner.h: the header file containing the scanner class's interface.
Scannerbase.h: the header file containing the interface of the scanner class's base class.
Scanner.ih: the internal header file that's meant to be included by the scanner class's source files (e.g. it's included by lex.cc, see the next item's file), and that should contain all declarations required for compiling the scanner class's sources.
lex.cc: the source file implementing the scanner class member function lex (and support functions), performing the lexical scan 💫.

🦋 BUGS 🦋

None reported 🙈 — she's flawless as far as anyone's saying. Periodt.

👑 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 the previously encountered problems with the lookahead-operator. Character development arc, honestly ✨.

⭐ 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).

okay bestie that's the whole page, you're officially a flexc++ girlie now 💅✨ this was flexc++.2.19.00, dated 2008-2026, from the flexc++(1) manual — go forth and lex, no cap 🌈🎀🦋

📦 where this page comes from

ubuntu stonking: flexc++ 2.19.00-1build1 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms