| main | class hierarchy | alphabetical | list | functions | files | tutorial | programs |

smtk::parse_arguments Class Reference

parse program options and generate documentation More...

Inheritance diagram for smtk::parse_arguments:

[legend]List of all members.

Public Types
enum	OPTION_NUM {   ERROR = -1, APP = 0, VERSION, USAGE,   HELP, HTML, BRIEF, DOXYGEN }
	returns values for parse() More...
Public Member Functions
const char *	bld (void) const
	color bold
const char *	blu (void) const
	color blue
bool	check_color (void)
	check is escape colors are set
const char *	end (void) const
	color end
void	get_env_color (FILE *file, bool over_ride_env=false)
	parse environment variable SMTK_COLOR.
option_item *	get_opt (const char *long_name)
	check that option was given
const char *	grn (void) const
	color green
OPTION_NUM	parse (int argc, const char **argv)
	parse the arguments
	parse_arguments (void)
const char *	rblu (void) const
	color reverse blue
const char *	red (void) const
	color red
const char *	rev (void) const
	color reverse
const char *	rgrn (void) const
	color reverse green
const char *	rred (void) const
	color reverse red
const char *	rtur (void) const
	color reverse turquoise
const char *	rvil (void) const
	color reverse violet
const char *	ryel (void) const
	color reverse yellow
parse_arguments parse_arguments parse_arguments &	set_brief (const char *fmt,...) __attribute__((format(printf
	set the brief description of the program
void	set_color (bool on=true)
	enable/disable the escape color strings.
parse_arguments parse_arguments &	set_description (const char *fmt,...) __attribute__((format(printf
	set the description of the program
parse_arguments &	set_opt (const char *parent_long_name, const char *long_name, char short_name, bool option_required, bool remaining_arguments, int number_values_required, const char *arg_sample, const char *description,...) __attribute__((format(printf
	add a command line option
parse_arguments &	set_opt_verbose (void)
	add the --verbose|-v option
parse_arguments parse_arguments &	set_opt_version (void)
	add the --version|-V option
parse_arguments &	set_opt_version (const char *fmt,...) __attribute__((format(printf
	add the --version|-V option
parse_arguments &	set_program_name (const char *fmt,...) __attribute__((format(printf
	set the name of the program
const char *	tur (void) const
	color turquoise
const char *	und (void) const
	color under line
const char *	vil (void) const
	color violet
const char *	yel (void) const
	color yellow

---

Detailed Description

parse program options and generate documentation

smtk::parse_arguments is like getopt_long() and a lot more. It parses command line arguments, generates usage, generates help, and generates HTML documentation. It automatically adds the command line options: --help|-h, --usage, --html-doc, and --smtk-version. Also prvides easy methods to add options --version|-v and --verbose|-V.

The inherited class tty_color may be used to add terminal color escape strings to the text in the in the terminal and in the generated html document.

---

Member Enumeration Documentation

enum smtk::parse_arguments::OPTION_NUM

returns values for parse()

List of returns values for parse(). In the simplest case a program will only continue to run after parse() returns APP (zero).

Enumerator:

ERROR	error like bad conversion from a arguement string to a float
APP	arguments were parsed for the application
VERSION	the --version option was acted on
USAGE	the --usage option was acted on
HELP	the --help option was acted on
HTML	the --html-doc option was acted on
BRIEF	the --brief option was acted on
DOXYGEN	the --doxygen option was acted on

---

Constructor & Destructor Documentation

parse_arguments::parse_arguments

(

void

)

constructor.

---

Member Function Documentation

const char* smtk::tty_color::bld

(

void

)

const [inline, inherited]

color bold

Returns:

color termio escape string bold.

const char* smtk::tty_color::blu

(

void

)

const [inline, inherited]

color blue

Returns:

color termio escape string blue.

bool smtk::tty_color::check_color

(

void

)

[inline, inherited]

check is escape colors are set

Returns:

true if there are color escape strings set, and false if there are all null strings.

const char* smtk::tty_color::end

(

void

)

const [inline, inherited]

color end

Returns:

color termio escape string to end the current color mode.

void tty_color::get_env_color	(	FILE *	file,
		bool	over_ride_env = false
	)			[inherited]

parse environment variable SMTK_COLOR.

See color_env for how the environment variable SMTK_COLOR effects this class.

Parameters:

	file	is used to check if the file is a tty terminal that will interpret the escape sequences.
	over_ride_env	if true the color strings will not depend on the environment variable SMTK_COLOR.

option_item* smtk::parse_arguments::get_opt

(

const char *

long_name

)

[inline]

check that option was given

Parameters:

long_name

the long name of the option. May be an empty string for unmarked arguments.

Returns:

true is the option was given in the argument list, false is not.

const char* smtk::tty_color::grn

(

void

)

const [inline, inherited]

color green

Returns:

color termio escape string green.

parse_arguments::OPTION_NUM parse_arguments::parse	(	int	argc,
		const char **	argv
	)

parse the arguments

Parse the arguments for options. You should exclude the first argument that is the program name, or like. This writes to stdout when the --help, --usage, --version, --html-doc, --doxygen, or --brief option is given.

Parameters:

	argc	number of elements in argv.
	argv	points to the argument strings. argv should be 0 terminated.

Returns:

values are listed in enum OPTION_NUM

const char* smtk::tty_color::rblu

(

void

)

const [inline, inherited]

color reverse blue

Returns:

color termio escape string reverse blue.

const char* smtk::tty_color::red

(

void

)

const [inline, inherited]

color red

Returns:

color termio escape string red.

const char* smtk::tty_color::rev

(

void

)

const [inline, inherited]

color reverse

Returns:

color termio escape string reverse-video.

const char* smtk::tty_color::rgrn

(

void

)

const [inline, inherited]

color reverse green

Returns:

color termio escape string reverse green.

const char* smtk::tty_color::rred

(

void

)

const [inline, inherited]

color reverse red

Returns:

color termio escape string reverse red.

const char* smtk::tty_color::rtur

(

void

)

const [inline, inherited]

color reverse turquoise

Returns:

color termio escape string reverse turquoise.

const char* smtk::tty_color::rvil

(

void

)

const [inline, inherited]

color reverse violet

Returns:

color termio escape string reverse violet.

const char* smtk::tty_color::ryel

(

void

)

const [inline, inherited]

color reverse yellow

Returns:

color termio escape string reverse yellow.

parse_arguments & parse_arguments::set_brief	(	const char *	fmt,
			...
	)

set the brief description of the program

Set the brief description of the program name that will be displayed in the help, and html documentation.

Parameters:

fmt

is a general printf()-like format for the remaining arguments.

Returns:

a reference to the parse_arguments object.

void tty_color::set_color

(

bool

on = true

)

[inherited]

enable/disable the escape color strings.

To give the API user the control, this is not called in any part of the SmTk API, other than in this class in the constructor. The setting of escape color strings is also set in the constructor from the value of the environment variable SMTK_COLOR. This will over-ride that. See color_env in the spew class detailed description.

Parameters:

on

If on is true the escape color strings are set, and if on is false all the escape color strings are set to empty strings.

Reimplemented in smtk::spew.

parse_arguments & parse_arguments::set_description	(	const char *	fmt,
			...
	)

set the description of the program

Set the description of the program name that will be displayed in the help, and html documentation.

Parameters:

fmt

is a general printf()-like format for the remaining arguments.

Returns:

a reference to the parse_arguments object.

parse_arguments & parse_arguments::set_opt	(	const char *	parent_long_name,
		const char *	long_name,
		char	short_name,
		bool	option_required,
		bool	remaining_arguments,
		int	number_values_required,
		const char *	arg_sample,
		const char *	description,
			...
	)

add a command line option

Add a argument option.

This argument option may be an option that modifies another option. Each argument option that is parsed is a node in a tree data structure with node parent/child relations.

Parameters:

	parent_long_name	is the long option tag used in the command line to mark that the parent option of this option is present. parent_long_name should be an empty string ("") to indicate an unmarked argument. parent_long_name should be 0 for an argument option without parent option.
	long_name	is the long option tag used in the command line to mark that the option is present.
	short_name	the single character option marker. 0 ('\0') may be given if there is no short name.
	option_required	is true if the option is not optional (not an option at all), and false if this is a regular option.
	remaining_arguments	is true is option should parse all remaining arguments in the command line, and false if not.
	number_values_required	is the number of values required to get from the arguments parsed.
	arg_sample	is the argument example description, like VAL in --value=VAL or "MIN MAX" in --range MIN MAX. This will be egnored if number_of_values is 0 and remaining_arguments is false. If this is not set, preprogramed defaults will be used.
	description	is a description that will be used in the help and html documentation. This is may be a printf(2) variable argument format.

Returns:

a reference to the parse_arguments object.

parse_arguments & parse_arguments::set_opt_verbose

(

void

)

add the --verbose|-v option

Sets up the --verbose|-v command line option. This will set the default smtk::spew spew level to "debug" if this option is given. The user may add additional functionality by checking for this option.

Returns:

a reference to the parse_arguments object.

parse_arguments & parse_arguments::set_opt_version

(

void

)

add the --version|-V option

Sets up the --version|-V command line option. The value for the version will be set to the version of this SmTk package.

Returns:

a reference to the parse_arguments object.

parse_arguments & parse_arguments::set_opt_version	(	const char *	fmt,
			...
	)

add the --version|-V option

Sets up the --version|-V command line option.

Parameters:

fmt

is a general printf()-like format for the remaining arguments.

Returns:

a reference to the parse_arguments object.

parse_arguments & parse_arguments::set_program_name	(	const char *	fmt,
			...
	)

set the name of the program

Set the name is the program name that will be displayed in the usage, help, and html documentation.

Parameters:

fmt

is a general printf()-like format for the remaining arguments.

Returns:

a reference to the parse_arguments object.

const char* smtk::tty_color::tur

(

void

)

const [inline, inherited]

color turquoise

Returns:

color termio escape string turquoise.

const char* smtk::tty_color::und

(

void

)

const [inline, inherited]

color under line

Returns:

color termio escape string under-line.

const char* smtk::tty_color::vil

(

void

)

const [inline, inherited]

color violet

Returns:

color termio escape string violet.

const char* smtk::tty_color::yel

(

void

)

const [inline, inherited]

color yellow

Returns:

color termio escape string yellow.

---

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

• libsmtk/smtk/parse_arguments.h
• libsmtk/parse_arguments.cpp
• libsmtk/parse_arguments_adjust_width.cpp
• libsmtk/parse_arguments_html_help.cpp

---