Evaluate parameters from command line. More...

Collaboration diagram for Options:

Public Types
enum	RunModes { ERROR_MESSAGE, HELP_MESSAGE, VERSION_MESSAGE, GEANY_MODE, DEF_MODE, FILE_MODE, LIST_MODE, SYNT_MODE }
	fb-doc operation modes. More...

enum	TypesStyle { C_STYLE, FB_STYLE }
	The style of the types in the C source. More...

enum	CaseModes { CASE_ORIGN, CASE_LOWER, CASE_MIXED, CASE_UPPER }
	The letter-case mode for keywords. More...

Public Member Functions
	Options ()
	Read options and parameters from the command line. More...

	~Options ()
	The destructor. More...

FUNCTION_AS_RunModes	parseCLI ()
	parse the command line More...

FUNCTION_AS_STRING	parseOptpara (BYREF_AS_INTEGER Idx)
	parse an additional parameter for an option More...

FUNCTION_as_EmitterIF_PTR	chooseEmitter (BYREF_AS_STRING F, BYREF_AS_STRING)
	Choose a named emitter, if possible. More...

SUB	FileModi ()
	Operate on file(s), single name and / or pattern(s) More...

SUB	doFile (BYREF_AS_STRING)
	Operate a single file. More...

FUNCTION_AS_INTEGER	checkDir (BYREF_AS_STRING)
	Create folder (if not exists) More...

FUNCTION_AS_STRING	scanFiles (BYREF_AS_STRING, BYREF_AS_STRING)
	Scan file names of given pattern. More...

FUNCTION_AS_STRING	addPath (BYREF_AS_STRING, BYREF_AS_STRING)
	Add two directories. More...

Public Attributes
RunModes	RunMode = DEF_MODE
	the mode to operate (defaults to DOXYFILTER) More...

TypesStyle	Types = FB_STYLE
	the style for the type generation (defaults to FB_STYLE) More...

Parser_PTR	Pars = 0
	the parser we use More...

EmitterTypes	EmitTyp = C_SOURCE
	the emitter type (defaults to `C_Source`) More...

CaseModes	CaseMode = CASE_ORIGN
	the emitter type (defaults to `C_Source`) More...

EmitterIF_PTR	EmitIF = 0
	the emitter we use (set in Options::parseCLI()) More...

ANY_PTR	DllEmitter = 0
	the pointer for an external emitter More...

ZSTRING_PTR	DirUp = "../"
	sequence to get one directory up More...

STRING	InFiles = ""
	name or pattern of all input file[s] More...

STRING	StartPath = ""
	path at program start More...

STRING	FileIncl = ""
	names of #`INCLUDE` files More...

STRING	OutPath = ""
	path for file output (option SecOptOutpath) More...

STRING	Errr = ""
	the error message (if any) More...

INTEGER	Asterix = 0
	comment block style for emitter C_Source More...

INTEGER	Docom = 0
	include documentational comments in source code (SyntaxHighlighting) More...

INTEGER	AllCallees = 0
	export external callee names as well (mode --list-mode (-l)) More...

INTEGER	InRecursiv = 0
	flag set when InFiles should get scaned recursiv in subfolders (option --recursiv (-r)) More...

INTEGER	InTree = 0
	flag set when source tree should get scanned (option --tree (-t)) More...

INTEGER	Level = 0
	counter for #`INCLUDE`s More...

INTEGER	Efnr = 0
	file number for error messages (file modes) More...

INTEGER	Ocha = 0
	file number for output More...

UBYTE	JoComm = ASC("*")
	magic character to start a documentational comment More...

UBYTE	AdLine = ASC("&")
	magic character to start a comment for direct export More...

EmitFunc	CreateFunction
	emitter for a function declaration with parameter list More...

EmitFunc	CreateVariable
	emitter for a variable declaration More...

Detailed Description

Evaluate parameters from command line.

This class is designed to scan options and parameters from command line. The command line gets parsed once at the program start. Since this structure is global, the settings are available in all internal modules.

Definition at line 35 of file fbdoc_options.bi.

Member Enumeration Documentation

enum Options::RunModes

fb-doc operation modes.

Enumerator
ERROR_MESSAGE	Report an error found in the command line. The parser found an error in the command line and we cannot operate. Output the error message and stop.
HELP_MESSAGE	Print the helptext. Stop after printing out some help information on how to start fb-doc and how to use options at the command line (mode --help (-h)).
VERSION_MESSAGE	Print version information. Print out the version information and stop (mode --version (-v)).
GEANY_MODE	Operate in Geany mode. Input from `STDIN` and output on `STDOUT`. Usually this is to generate templates in Geany, but it also can be used with pipes (mode --geany-mode (-g)).
DEF_MODE	Operate as Doxygen filter. Read a file and generate C-source to `STDOUT` (mode none (default)).
FILE_MODE	Operate in scan mode. Read input from one or more files, write output to files. Usually this is to generate pseudo C source output, but an alternative emitter can be specified. When no file name or pattern is specified, all .bas and .bi files in the current folder gets parsed (mode --file-mode (-f)).
LIST_MODE	Operate in list mode. Read input from one or more files, write output to a single file `fb-doc.lfn`. Generate a list of callee names in this file. When no file name or pattern is specified, all .bas and .bi files in the current folder gets parsed (mode --list-mode (-l)).
SYNT_MODE	Operate in syntax-highlighting mode. Read input from one or more files, write output to a several files (mode --syntax-mode (-s)). As input fb-doc reads files created by Doxygen, containing the source listings in the intermediate format. The file types depend on the settings in the Doxyfile. It may be `.html`, `.tex` and `*.xml`, depending on tags `SOURCE_BROWSER =` and `GENERATE_HTML =`, `GENERATE_LATEX =` / `LATEX_SOURCE_CODE =` and `GENERATE_XML =` / `XML_PROGRAMLISTING`.

Definition at line 37 of file fbdoc_options.bi.

enum Options::TypesStyle

The style of the types in the C source.

A FB type can be translated to a C type or it can be shown as a pseudo type. Ie. instead of the C type void the pseudo type SUB can be used.

Enumerator
C_STYLE	types gets translated to C
FB_STYLE	pseudo FB types are used

Definition at line 103 of file fbdoc_options.bi.

enum Options::CaseModes

The letter-case mode for keywords.

Enumerator
CASE_ORIGN	Output original formating.
CASE_LOWER	Output keywords in lower case.
CASE_MIXED	Output keywords in mixed case.
CASE_UPPER	Output keywords in upper case.

Definition at line 109 of file fbdoc_options.bi.

Constructor & Destructor Documentation

Options::Options ( )

Read options and parameters from the command line.

The constructor scans all command line arguments and checks for options and their parameters (, see SecTabOptions for details). Options may be specified in short form (starting with a single minus character) or in human readable LONG form (starting with two minus characters). Some options may have an additinal parameter.

Each command line argument that is neither an option nor its parameter gets interpreted as a file name or pattern. fb-doc collects them in a queue and operates on this queue afterwards. The queue may have mixed entries (names and patterns). It's recommended to specify queue entries in single or double quotes.

Definition at line 36 of file fbdoc_options.bas.

Here is the call graph for this function:

Options::~Options ( )

The destructor.

Delete the memory used for an external emitter (if any) and for the Parser.

Definition at line 52 of file fbdoc_options.bas.

Member Function Documentation

FUNCTION_AS_RunModes Options::parseCLI ( )

parse the command line

Returns: the RunMode

This function parses the command line. Options and its parameter (if required) get read and the file specifier(s) are listed in the variable InFiles, separated by new line characters.

The function returns the value of RunMode. In case of an error the RunMode is ERROR_MESSAGE and the variable Errr contains an message text. fb-doc stops execution in that case.

Loading an external emitter plugin must be done after scanning the COMMAND strings because DYLIBLOAD destroys the COMMAND array. All unknown parameters get collected in the variable par, separated by tabulators (!"\\t"), in order to get passed to the plugin initialisation function.

Definition at line 100 of file fbdoc_options.bas.

Here is the call graph for this function:

FUNCTION_AS_STRING Options::parseOptpara ( BYREF_AS_INTEGER Idx )

parse an additional parameter for an option

Parameters

Idx	the current index in `COMMAND()`

Returns: the parameter, without quotes if any

This function evaluates a parameter for an option. Some options need an additional parameter (ie. like SecOptOutpath). It gets read by this function, removing surrounding single or double quotes (if any).

In case of no further parameter or when the parameter starts by an "`-`" character an error messages gets created.

Definition at line 71 of file fbdoc_options.bas.

Here is the caller graph for this function:

FUNCTION_AS_EmitterIF_PTR Options::chooseEmitter	(	BYREF_AS_STRING	F,
		BYREF_AS_STRING	P
	)

Choose a named emitter, if possible.

Parameters

F	the name of the emitter to search for
P	parameters to pass to an external emitter (plugin)

This function checks for an emitter specified by the parameter F. The check is not case-sensitve and is done for a complete emitter name as well as for a fragment. So it's enough to specify some of the start characters of the emitter name (ie. dox instead of DoxygenTemplates).

In case of no match for any internal emitter name this SUB tries to load an external emitter (plugin), located in the current folder. See External Emitters for details. If this fails an error message gets created and fb-doc stops execution.

Parameter P contains all command line options that are unknown to fb-doc*. Those options get passed to the plugins function EmitterInit(). There, all known options should get extracted and evaluated. When this string is not empty after the plugin initialization, fb-doc stops execution by an unknown options error.

Definition at line 187 of file fbdoc_options.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB Options::FileModi ( )

Operate on file(s), single name and / or pattern(s)

This SUB gets called in case of file input modes. It separates the file name specifiers from the Options::InFiles list, expands file patterns and executes the required operations.

Definition at line 331 of file fbdoc_options.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

SUB Options::doFile ( BYREF_AS_STRING Fnam )

Operate a single file.

This SUB gets called to operate on a single file. Depending on the RunMode it emits messages to STDERR and it opens a file for the output channel Ocha.

Definition at line 414 of file fbdoc_options.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

FUNCTION_AS_INTEGER Options::checkDir ( BYREF_AS_STRING P )

Create folder (if not exists)

Parameters

P	the folder name

Returns: -1 on error, else 0

This FUNCTION gets called to prepare the folders for file output in mode --file-mode (-f). It creates matching subfolders in the target directory set by option --outpath or its default.

Definition at line 305 of file fbdoc_options.bas.

Here is the caller graph for this function:

FUNCTION_AS_STRING Options::scanFiles	(	BYREF_AS_STRING	Patt,
		BYREF_AS_STRING	Path
	)

Scan file names of given pattern.

Parameters

Patt	The name pattern to search for
Path	A path to add

Returns: A list of file names and their subfolder

This function scans the current directory for file names matching a given pattern and the subfolders, if Options::InRecursiv ist set. It returns a list of filenames including their subfolder. The list is separated by newline characters.

Definition at line 234 of file fbdoc_options.bas.

Here is the call graph for this function:

Here is the caller graph for this function:

FUNCTION_AS_STRING Options::addPath	(	BYREF_AS_STRING	P1,
		BYREF_AS_STRING	P2
	)

Add two directories.

Parameters

P1	the path of the basis directory
P2	the path of the directory to add

Returns: a string of the combined directory

Append second path to first, if it's not an absolute path. In case of an absolute path this path gets returned. The returned path has a SLASH at the end and all '..' sequences are unscrambled.

Definition at line 277 of file fbdoc_options.bas.

Here is the caller graph for this function:

Member Data Documentation

RunModes Options::RunMode = DEF_MODE

the mode to operate (defaults to DOXYFILTER)

Definition at line 116 of file fbdoc_options.bi.

TypesStyle Options::Types = FB_STYLE

the style for the type generation (defaults to FB_STYLE)

Definition at line 117 of file fbdoc_options.bi.

Parser_PTR Options::Pars = 0

the parser we use

Definition at line 118 of file fbdoc_options.bi.

EmitterTypes Options::EmitTyp = C_SOURCE

the emitter type (defaults to C_Source)

Definition at line 119 of file fbdoc_options.bi.

CaseModes Options::CaseMode = CASE_ORIGN

the emitter type (defaults to C_Source)

Definition at line 120 of file fbdoc_options.bi.

EmitterIF_PTR Options::EmitIF = 0

the emitter we use (set in Options::parseCLI())

Definition at line 121 of file fbdoc_options.bi.

ANY_PTR Options::DllEmitter = 0

the pointer for an external emitter

Definition at line 122 of file fbdoc_options.bi.

ZSTRING_PTR Options::DirUp = "../"

sequence to get one directory up

Definition at line 124 of file fbdoc_options.bi.

STRING Options::InFiles = ""

name or pattern of all input file[s]

Definition at line 132 of file fbdoc_options.bi.

STRING Options::StartPath = ""

path at program start

Definition at line 133 of file fbdoc_options.bi.

STRING Options::FileIncl = ""

names of #INCLUDE files

Definition at line 134 of file fbdoc_options.bi.

STRING Options::OutPath = ""

path for file output (option SecOptOutpath)

Definition at line 135 of file fbdoc_options.bi.

STRING Options::Errr = ""

the error message (if any)

Definition at line 136 of file fbdoc_options.bi.

INTEGER Options::Asterix = 0

comment block style for emitter C_Source

Definition at line 138 of file fbdoc_options.bi.

INTEGER Options::Docom = 0

include documentational comments in source code (SyntaxHighlighting)

Definition at line 139 of file fbdoc_options.bi.

INTEGER Options::AllCallees = 0

export external callee names as well (mode --list-mode (-l))

Definition at line 140 of file fbdoc_options.bi.

INTEGER Options::InRecursiv = 0

flag set when InFiles should get scaned recursiv in subfolders (option --recursiv (-r))

Definition at line 141 of file fbdoc_options.bi.

INTEGER Options::InTree = 0

flag set when source tree should get scanned (option --tree (-t))

Definition at line 142 of file fbdoc_options.bi.

INTEGER Options::Level = 0

counter for #INCLUDEs

Definition at line 143 of file fbdoc_options.bi.

INTEGER Options::Efnr = 0

file number for error messages (file modes)

Definition at line 144 of file fbdoc_options.bi.

INTEGER Options::Ocha = 0

file number for output

Definition at line 145 of file fbdoc_options.bi.

UBYTE Options::JoComm = ASC("*")

magic character to start a documentational comment

Definition at line 147 of file fbdoc_options.bi.

UBYTE Options::AdLine = ASC("&")

magic character to start a comment for direct export

Definition at line 148 of file fbdoc_options.bi.

EmitFunc Options::CreateFunction

emitter for a function declaration with parameter list

Definition at line 150 of file fbdoc_options.bi.

EmitFunc Options::CreateVariable

emitter for a variable declaration

Definition at line 150 of file fbdoc_options.bi.

The documentation for this class was generated from the following files:

src/bas/fbdoc_options.bi
src/bas/fbdoc_options.bas

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation