NOUSERMACRO(lex setDebug postCode)

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_)
        (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.

    Not every aspect of flc() is covered by the man-pages. In addition to
what's summarized by the man-pages the flc() 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 flc().

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

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

    Flc() offers several man-pages. These man-pages contain the following main
sections: 

bf(This man-page)

    This man-page offers the following sections:

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

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

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

    itemization(
    it() bf(1. INTERACTIVE SCANNERS): how to create an interactive scanner

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

    it() bf(8. THE SCANNER BASE CLASS): the scanner class is derived from a
        base class. The base class is described in this section
    it() bf(9. PUBLIC ENUMS AND -TYPES): enums and types declared by the
        base class
    it() bf(10. PROTECTED ENUMS AND -TYPES): enumerations and types used by
        the scanner and scanner base classes
    it() bf(11. NO PUBLIC CONSTRUCTORS): the scanner base class does not
        offer public constructors.
    it() bf(12. PUBLIC MEMBER FUNCTIONS): several members defined by the
        scanner base class have public access rights.
    it() bf(13. PROTECTED CONSTRUCTORS): the base class can be constructed by
        a derived class. Usually this is the scanner class generated by flc().
    it() bf(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
    it() bf(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
    it() bf(16. FLEX++ TO FLEXC++ MEMBERS): a short overview of frequently
        used bf(flex)(1) members that received different names in flc().

    it() bf(17. 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(18. INPUT CONSTRUCTORS): the class tt(Input) can easily be
        replaced by another class. The constructor-requirements are described
        in this section.
    it() bf(19. REQUIRED PUBLIC MEMBER FUNCTIONS): this section covers the
        required public members of a self-made tt(Input) class
    )

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

    This man-page describes how flc()'s input file(s) should be organized. It
contains the following sections:

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

includefile(generic.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), bf(flexc++api)(3), bf(flexc++input)(7)

manpagebugs()

   None reported

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

includefile(include/trailer.yo)


