NOUSERMACRO(lex setDebug)

includefile(../../release.yo)

htmlbodyopt(text)(#27408B)
htmlbodyopt(bgcolor)(#FFFAF0)
whenhtml(mailto(Frank B. Brokken: f.b.brokken@rug.nl))

DEFINEMACRO(lsoption)(3)(\
    bf(--ARG1)=tt(ARG3) (bf(-ARG2))\
)
DEFINEMACRO(laoption)(2)(\
    bf(--ARG1)=tt(ARG2)\
)
DEFINEMACRO(loption)(1)(\
    bf(--ARG1)\
)
DEFINEMACRO(soption)(1)(\
    bf(-ARG1)\
)

DEFINEMACRO(flc)(0)(bf(flexc++))
DEFINEMACRO(Flc)(0)(bf(Flexc++))
DEFINEMACRO(Cpp)(0)(bf(C++))
DEFINEMACRO(prot)(0)(tt((prot)))

DELETEMACRO(tt)
DEFINEMACRO(tt)(1)(em(ARG1))
DEFINEMACRO(itt)(1)(it() tt(ARG1))
DEFINEMACRO(itb)(1)(it() bf(ARG1))

NOUSERMACRO( FILE Input Scanner ScannerBase YYText accept back begin close
debug echo filename files get interactiveLine leave length less lineNr lineno
matched more name out popStream preCode print push pushStream reRead redo
scanner setFilename setMatched startCondition streamStack switchIstream
switchOstream switchStreams
    )

COMMENT( man-request, section, date, distribution file, general name)
manpage(flexc++)(1)(_CurYrs_)(flexc++._CurVers_.tar.gz)
        (flexc++ scanner generator)

COMMENT( man-request, larger title )
manpagename(flexc++)(Generate a C++ scanner class and parsing function)

COMMENT( all other: add after () )
manpagesynopsis()
       flc() [options] tt(rules-file)

manpagedescription()

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

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

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

    Below, the following sections may be consulted for specific details:
    itemization(
    it() bf(1. QUICK START): a quick start overview about how to use flc().
    it() bf(2. QUICK START: FLEXC++ and BISONC++): a quick start overview
        about how to use flc() in combination with bf(bisonc++)(1)
    it() bf(3. GENERATED FILES): files generated by flc() and their purposes
    it() bf(4. OPTIONS): options available for flc()
    it() bf(5. INTERACTIVE SCANNERS): how to create an interactive scanner

    it() bf(6. SPECIFICATION FILE(S)): the format and contents of flc() input
        files, specifying the Scanner's characteristics
    it() bf(6.1. FILE SWITCHING): how to switch to another input specification
        file
    it() bf(6.2. DIRECTIVES): directives that can be used in input
        specification files
    it() bf(6.3. MINI SCANNERS): how to declare mini-scanners
    it() bf(6.4. DEFINITIONS): how to define symbolic names for regular
        expressions
    it() bf(6.5. %% SEPARATOR): the separator between the input specification
        sections 
    it() bf(6.6. REGULAR EXPRESSIONS): regular expressions supported by flc()
    it() bf(6.7. SPECIFICATION EXAMPLE): an example of a specification file

    it() bf(7. THE CLASS INTERFACE: SCANNER.H): Constructors and members
        of the scanner class generated by flc() 
    it() bf(7.1. NAMING CONVENTION): symbols defined by flc() in the scanner
        class. 
    it() bf(7.2 CONSTRUCTORS): constructors defined in the scanner class.
    it() bf(7.3 PUBLIC MEMBER FUNCTION): public member declared in the scanner
        class.
    it() bf(7.4. PRIVATE MEMBER FUNCTIONS): private members declared in the
        scanner class.
    it() bf(7.5. SCANNER CLASS HEADER EXAMPLE): an example of a generated
        scanner class header

    it() bf(8.1. THE SCANNER BASE CLASS): the scanner class is derived from a
        base class. The base class is described in this section
    it() bf(8.2. PUBLIC ENUMS AND -TYPES): enums and types declared by the
        base class
    it() bf(8.3. PROTECTED ENUMS AND -TYPES): enumerations and types used by
        the scanner and scanner base classes
    it() bf(8.4. NO PUBLIC CONSTRUCTORS): the scanner base class does not
        offer public constructors.
    it() bf(8.5. PUBLIC MEMBER FUNCTIONS): several members defined by the
        scanner base class have public access rights.
    it() bf(8.6. PROTECTED CONSTRUCTORS): the base class can be constructed by
        a derived class. Usually this is the scanner class generated by flc().
    it() bf(8.7. PROTECTED MEMBER FUNCTIONS): this section covers the base
        class member functions that can only be used by scanner class or
        scanner base class members
    it() bf(8.8. PROTECTED DATA MEMBERS): this section covers the base class
        data members that can only be used by scanner class or scanner base
        class members
    it() bf(8.9. FLEX++ TO FLEXC++ MEMBERS): a short overview of frequently
        used bf(flex)(1) members that received different names in flc().

    it() bf(9.1. THE CLASS INPUT): the scanner's job is completely decoupled
        from the actual input stream. The class tt(Input), nested within the
        scanner base class handles the communication with the input
        streams. The  class tt(Input), is described in this section.
    it() bf(9.2. CONSTRUCTORS): the class tt(Input) can easily be replaced by
        another class. The constructor-requirements are described in this
        section. 
    it() bf(9.3. REQUIRED PUBLIC MEMBER FUNCTIONS): this section covers the
        required public members of a self-made tt(Input) class
    )

includefile(generic.yo)
includefile(rules.yo)
includefile(scanner.h.yo)
includefile(scannerbase.h.yo)
includefile(input.yo)

manpagefiles()

    Flc()'s default skeleton files are in tt(/usr/share/flexc++).nl()
    By default, flc() generates the following files:
        itemization(
        itt(Scanner.h): the header file containing the scanner class's
            interface. 
        itt(Scannerbase.h): the header file containing the interface of the 
            scanner class's base class.
        itt(Scanner.ih): the internal header file that is meant to be included
            by the scanner class's source files (e.g., it is included by
            tt(lex.cc), see the next item's file), and that should contain all
            declarations required for compiling the scanner class's sources.
        itt(lex.cc): the source file implementing the scanner class member
            function tt(lex) (and support functions), performing the lexical
            scan.
    )

manpageseealso()

    bf(bisonc++)(1)

manpagebugs()

    itemization(
    it() The priority of interval expressions (tt({...})) equals the priority
of other multiplicative operators (like tt(*)).
    it() All tt(INITIAL) rules apply to inclusive mini scanners, also those
tt(INITIAL) rules that were explicitly associated with the tt(INITIAL) mini
scanner.
    it() Generating interactive and non-interactive scanners (see section
        5. INTERACTIVE SCANNERS) cannot be mixed.
    )

manpagesection(ABOUT flexc++)

    Flc() 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 flc(), the lookahead-operator
handling continuously threatened the completion of the project. By now, the
project has evolved to a level that we feel it's defensible to publish the
program, although we still tend to consider the program in its experimental
stage; it will remain that way until we decide to move its version from the
0.9x.xx series to the 1.xx.xx series.

includefile(include/trailer.yo)
