Geogram
Version 1.9.1-rc
A programming library of geometric algorithms
|
Utilities to process command line arguments. More...
Typedefs | |
typedef char ** | charptrptr |
Enumerations | |
enum | ArgType { ARG_UNDEFINED = 0 , ARG_INT = 1 , ARG_DOUBLE = 2 , ARG_STRING = 4 , ARG_BOOL = 8 , ARG_PERCENT = 16 } |
Command line argument types. More... | |
enum | ArgFlags { ARG_FLAGS_DEFAULT = 0 , ARG_ADVANCED = 1 } |
Command line group or argument flags. More... | |
Functions | |
void | initialize () |
Initializes the command line framework. More... | |
void | terminate () |
Cleans up the command line framework. More... | |
void | set_config_file_name (const std::string &filename, bool auto_create_args=false) |
Defines the name of the configuration file. More... | |
bool | config_file_loaded () |
Tests whether the configuration file was loaded. More... | |
std::string | get_config_file_name () |
Gets the name of the configuration file. More... | |
void | load_config (const std::string &filename, const std::string &program_name) |
Loads command line argument values from a file. More... | |
void | declare_arg_group (const std::string &name, const std::string &description, ArgFlags flags=ARG_FLAGS_DEFAULT) |
Declares an argument group. More... | |
void | declare_arg (const std::string &name, ArgType type, const std::string &default_value, const std::string &description, ArgFlags flags=ARG_FLAGS_DEFAULT) |
Declares an argument. More... | |
ArgType | get_arg_type (const std::string &name) |
Gets the type of an argument. More... | |
bool | arg_is_declared (const std::string &name) |
Checks if an argument exists. More... | |
void | declare_arg (const std::string &name, const std::string &default_value, const std::string &description, ArgFlags flags=ARG_FLAGS_DEFAULT) |
Declares an argument of type string. More... | |
void | declare_arg (const std::string &name, const char *default_value, const std::string &description, ArgFlags flags=ARG_FLAGS_DEFAULT) |
Declares an argument of type string. More... | |
void | declare_arg (const std::string &name, int default_value, const std::string &description, ArgFlags flags=ARG_FLAGS_DEFAULT) |
Declares an argument of type integer. More... | |
void | declare_arg (const std::string &name, double default_value, const std::string &description, ArgFlags flags=ARG_FLAGS_DEFAULT) |
Declares an argument of type floating point. More... | |
void | declare_arg (const std::string &name, bool default_value, const std::string &description, ArgFlags flags=ARG_FLAGS_DEFAULT) |
Declares an argument of type boolean. More... | |
void | declare_arg_percent (const std::string &name, double default_value, const std::string &description="...", ArgFlags flags=ARG_FLAGS_DEFAULT) |
Declares an argument of type percentage. More... | |
bool | parse (int argc, char **argv, std::vector< std::string > &unparsed_args, const std::string &additional_arg_specs="") |
Parses the command line arguments. More... | |
bool | parse (int argc, char **argv) |
Parses the command line arguments. More... | |
int | argc () |
Gets the number of arguments of the command line. More... | |
charptrptr | argv () |
Gets the command line arguments. More... | |
void | show_usage (const std::string &additional_args="", bool advanced=false) |
Displays program help. More... | |
std::string | get_arg (const std::string &name) |
Gets an argument value. More... | |
int | get_arg_int (const std::string &name) |
Gets an argument value as an integer. More... | |
unsigned int | get_arg_uint (const std::string &name) |
Gets an argument value as an unsigned integer. More... | |
double | get_arg_double (const std::string &name) |
Gets an argument value as a floating point. More... | |
double | get_arg_percent (const std::string &name, double reference) |
Gets an argument value as a percentage. More... | |
bool | get_arg_bool (const std::string &name) |
Gets an argument value as a boolean. More... | |
bool | set_arg (const std::string &name, const std::string &value) |
Sets an argument value from a string. More... | |
bool | set_arg (const std::string &name, const char *value) |
Sets an argument value from a C-string. More... | |
void | set_arg (const std::string &name, Numeric::int32 value) |
Sets an argument value from an integer. More... | |
void | set_arg (const std::string &name, Numeric::uint32 value) |
void | set_arg (const std::string &name, Numeric::int64 value) |
void | set_arg (const std::string &name, Numeric::uint64 value) |
void | set_arg (const std::string &name, double value) |
Sets an argument value from a floating point. More... | |
void | set_arg (const std::string &name, bool value) |
Sets an argument value from a boolean. More... | |
void | set_arg_percent (const std::string &name, double value) |
Sets an argument value from a percentage. More... | |
void | get_args (std::vector< std::string > &args) |
Gets the value of all arguments. More... | |
index_t | ui_terminal_width () |
Gets the width of the console. More... | |
void | ui_separator (const std::string &title, const std::string &short_title="") |
Outputs a separator with a title on the console. More... | |
void | ui_separator () |
Outputs a separator without a title on the console. More... | |
void | ui_close_separator () |
Closes an opened separator. More... | |
void | ui_message (const std::string &message, index_t wrap_margin) |
Outputs a message on the console. More... | |
void | ui_message (const std::string &message) |
Outputs a message on the console. More... | |
void | ui_clear_line () |
Clears the last line. More... | |
void | ui_progress (const std::string &task_name, index_t val, index_t percent, bool clear=true) |
Displays a progress bar. More... | |
void | ui_progress_time (const std::string &task_name, double elapsed, bool clear=true) |
Displays the time elapsed for a completed task. More... | |
void | ui_progress_canceled (const std::string &task_name, double elapsed, index_t percent, bool clear=true) |
Displays the time elapsed for a canceled task. More... | |
std::string | ui_feature (const std::string &feature, bool show=true) |
Formats a Logger feature name. More... | |
bool | import_arg_group (const std::string &name) |
Imports a group of command line arguments. More... | |
bool | set_profile (const std::string &name) |
Sets the current application profile. More... | |
Utilities to process command line arguments.
CmdLine defines utility functions to declare program options and parse command line arguments.
Command line group or argument flags.
Enumerator | |
---|---|
ARG_FLAGS_DEFAULT | Default argument flags (nothing) |
ARG_ADVANCED | Argument is advanced |
Definition at line 146 of file command_line.h.
Command line argument types.
Definition at line 128 of file command_line.h.
bool GEO::CmdLine::arg_is_declared | ( | const std::string & | name | ) |
Checks if an argument exists.
[in] | name | the argument name |
true | if the argument exists |
false | otherwise |
int GEO::CmdLine::argc | ( | ) |
Gets the number of arguments of the command line.
parse() should be called before.
charptrptr GEO::CmdLine::argv | ( | ) |
Gets the command line arguments.
parse() should be called before.
bool GEO::CmdLine::config_file_loaded | ( | ) |
Tests whether the configuration file was loaded.
The default configuration file, or the one specified by set_config_file_name() may not exist, in this case this function returns false.
true | if the configuration file was loaded. |
false | otherwise. |
void GEO::CmdLine::declare_arg | ( | const std::string & | name, |
ArgType | type, | ||
const std::string & | default_value, | ||
const std::string & | description, | ||
ArgFlags | flags = ARG_FLAGS_DEFAULT |
||
) |
Declares an argument.
This is the general function for declaring an argument of name name
. The default value default_value
is given as a string and must be convertible to the given type type
. The command line framework provides type-safe variants of declare_arg() for declaring arguments, it is highly recommended to use them.
Argument names can have 2 forms:
[in] | name | the argument name |
[in] | type | the argument type |
[in] | default_value | the default value as a string |
[in] | description | the argument description |
[in] | flags | the argument flags |
|
inline |
Declares an argument of type boolean.
[in] | name | the argument name |
[in] | default_value | argument's default boolean value |
[in] | description | argument description |
[in] | flags | the argument flags |
Definition at line 305 of file command_line.h.
|
inline |
Declares an argument of type string.
[in] | name | the argument name |
[in] | default_value | argument's default C-string value |
[in] | description | argument description |
[in] | flags | the argument flags |
Definition at line 248 of file command_line.h.
|
inline |
Declares an argument of type string.
[in] | name | the argument name |
[in] | default_value | argument's default string value |
[in] | description | argument description |
[in] | flags | the argument flags |
Definition at line 229 of file command_line.h.
|
inline |
Declares an argument of type floating point.
[in] | name | the argument name |
[in] | default_value | argument's default floating point value |
[in] | description | argument description |
[in] | flags | the argument flags |
Definition at line 286 of file command_line.h.
|
inline |
Declares an argument of type integer.
[in] | name | the argument name |
[in] | default_value | argument's default integer value |
[in] | description | argument description |
[in] | flags | the argument flags |
Definition at line 267 of file command_line.h.
void GEO::CmdLine::declare_arg_group | ( | const std::string & | name, |
const std::string & | description, | ||
ArgFlags | flags = ARG_FLAGS_DEFAULT |
||
) |
Declares an argument group.
This creates a new argument group with the given name name
. If a group with the same name already exists, the new group is not created.
Argument groups are used to organize arguments in a set of logically related arguments. For instance:
...
To declare an argument in a given group, the argument name must be prefixed by the group name followed by a colon as in "group:arg".
[in] | name | the group name |
[in] | description | the group description |
[in] | flags | the group flags |
|
inline |
Declares an argument of type percentage.
Percentage values are normal floating point values, except that their string representation is followed by a percent "%" sign.
[in] | name | the argument name |
[in] | default_value | argument's default percentage value |
[in] | description | argument description |
[in] | flags | the argument flags |
Definition at line 326 of file command_line.h.
std::string GEO::CmdLine::get_arg | ( | const std::string & | name | ) |
Gets an argument value.
Retrieves the string value of argument name
. If the argument does not exist, then the function calls abort().
[in] | name | the argument name |
bool GEO::CmdLine::get_arg_bool | ( | const std::string & | name | ) |
Gets an argument value as a boolean.
Retrieves the value of argument name
and converts it to an integer. If the argument does not exists or its value is not convertible to a boolean, then the function aborts.
[in] | name | the argument name |
double GEO::CmdLine::get_arg_double | ( | const std::string & | name | ) |
Gets an argument value as a floating point.
Retrieves the value of argument name
and converts it to a floating point. If the argument does not exists or its value is not convertible to a floating point, then the function aborts.
[in] | name | the argument name |
int GEO::CmdLine::get_arg_int | ( | const std::string & | name | ) |
Gets an argument value as an integer.
Retrieves the value of argument name
and converts it to an integer. If the argument does not exists or its value is not convertible to an integer, then the function aborts.
[in] | name | the argument name |
double GEO::CmdLine::get_arg_percent | ( | const std::string & | name, |
double | reference | ||
) |
Gets an argument value as a percentage.
Retrieves the value of argument name:
reference
. The returned value is the floating point value 0.01*dd multiplied by the parameter reference
.reference
is ignored.[in] | name | the argument name |
[in] | reference | the value to apply the percentage to |
reference
name
ArgType GEO::CmdLine::get_arg_type | ( | const std::string & | name | ) |
Gets the type of an argument.
[in] | name | the argument name |
the | type of the argument if it exists |
ARG_UNDEFINED | otherwise |
unsigned int GEO::CmdLine::get_arg_uint | ( | const std::string & | name | ) |
Gets an argument value as an unsigned integer.
Retrieves the value of argument name
and converts it to an unsigned integer. If the argument does not exists or its value is not convertible to an unsigned integer, then the function aborts.
[in] | name | the argument name |
void GEO::CmdLine::get_args | ( | std::vector< std::string > & | args | ) |
Gets the value of all arguments.
Stores in vector args
the value of all declared arguments in the form "name=value".
[out] | args | output vector |
std::string GEO::CmdLine::get_config_file_name | ( | ) |
Gets the name of the configuration file.
bool GEO::CmdLine::import_arg_group | ( | const std::string & | name | ) |
Imports a group of command line arguments.
The behavior of the the Vorpaline library is controlled by several properties organized in the following groups:
To allow setting the properties from the command line, users must declare command line arguments and groups for the Vorpaline properties that they want to control, plus their own specific command line options. The function import_arg_group() relieves users of this tiresome and repetitive task by declaring a whole group of command line arguments.
The following example illustrates how to use import_arg_group() in a main program, to declare command line options for the "standard" and "remesh" Vorpaline property groups:
[in] | name | the name of the group to import. |
void GEO::CmdLine::initialize | ( | ) |
Initializes the command line framework.
This function must be called once at program start. It is called by the general initialization function GEO::initialize().
void GEO::CmdLine::load_config | ( | const std::string & | filename, |
const std::string & | program_name | ||
) |
Loads command line argument values from a file.
only args in the section with program_name
are loaded.
[in] | filename | the complete path to the file. |
[in] | program_name | the name of the program. |
bool GEO::CmdLine::parse | ( | int | argc, |
char ** | argv | ||
) |
Parses the command line arguments.
This is a simplified version of parse() which does not accept additional unparsed arguments.
[in] | argc | number of arguments passed to main() |
[in] | argv | array of command line arguments passed to main() |
true | if the command line arguments are successfully parsed |
false | otherwise |
bool GEO::CmdLine::parse | ( | int | argc, |
char ** | argv, | ||
std::vector< std::string > & | unparsed_args, | ||
const std::string & | additional_arg_specs = "" |
||
) |
Parses the command line arguments.
This analyzes command line arguments passed to the main() program in argc
and argv
. Arguments not matching program options declared with declare_arg() are stored in output vector unparsed_args
.
Command line parsing allows users to specify partial option names on the command line. If a partial name matches more than 1 declared argument, it is rejected and the functions fails, otherwise, it is accepted and replaced by the full argument name.
Parameter additional_arg_specs
specifies how to handle unparsed arguments. It consists in a white space separated list of additional argument names expected by the program, with the following meaning:
For instance the following additional argument specification:
means that the program expects at least one additional argument input_file, with two additional optional arguments option_file and output_file.
If argument "-h" is found in the list of arguments, then the program displays a summary of program options and exits (see show_usage()).
[in] | argc | number of arguments passed to main() |
[in] | argv | array of command line arguments passed to main() |
[out] | unparsed_args | output vector of unparsed arguments |
[in] | additional_arg_specs | unparsed argument specification |
true | if the command line arguments are successfully parsed |
false | otherwise |
void GEO::CmdLine::set_arg | ( | const std::string & | name, |
bool | value | ||
) |
Sets an argument value from a boolean.
This replaces the value of argument name
by the given boolean value
. If the declared type of the argument is not compatible with a boolean then the function aborts (compatible argument types are: boolean or string). If the argument does not exist, it is added as a new argument of undefined type.
[in] | name | the argument name |
[in] | value | the new value as a floating point |
|
inline |
Sets an argument value from a C-string.
This replaces the value of argument name
by the given C-string value
. If the string value
is not strictly convertible to the declared type of the argument then the function aborts. If the argument does not exist, it is added as a new argument of undefined type.
[in] | name | the argument name |
[in] | value | the new value as a C-string |
true | if the argument was successfully set |
false | otherwise |
Definition at line 538 of file command_line.h.
bool GEO::CmdLine::set_arg | ( | const std::string & | name, |
const std::string & | value | ||
) |
Sets an argument value from a string.
This replaces the value of argument name
by the given string value
. If the string value
is not strictly convertible to the declared type of the argument then the function aborts. If the argument does not exist, it is added as a new argument of undefined type.
[in] | name | the argument name |
[in] | value | the new value as a string |
true | if the argument was successfully set |
false | otherwise |
void GEO::CmdLine::set_arg | ( | const std::string & | name, |
double | value | ||
) |
Sets an argument value from a floating point.
This replaces the value of argument name
by the given floating point value
. If the declared type of the argument is not compatible with a floating point then the function aborts (compatible argument types are: double or string). If the argument does not exist, it is added as a new argument of undefined type.
[in] | name | the argument name |
[in] | value | the new value as a floating point |
void GEO::CmdLine::set_arg | ( | const std::string & | name, |
Numeric::int32 | value | ||
) |
Sets an argument value from an integer.
This replaces the value of argument name
by the given integer value
. If the declared type of the argument is not compatible with an integer then the function aborts (compatible argument types are: int, double or string). If the argument does not exist, it is added as a new argument of undefined type.
[in] | name | the argument name |
[in] | value | the new value as an integer |
void GEO::CmdLine::set_arg_percent | ( | const std::string & | name, |
double | value | ||
) |
Sets an argument value from a percentage.
This replaces the value of argument name
by the given floating point value
. If the declared type of the argument is not compatible with a floating point then the function aborts (compatible argument types are: double or string), otherwise the argument receives the value
converted to a floating with a trailing '' sign. If the argument does not exist, it is added as a new argument of undefined type.
[in] | name | the argument name |
[in] | value | the new value as a floating point |
void GEO::CmdLine::set_config_file_name | ( | const std::string & | filename, |
bool | auto_create_args = false |
||
) |
Defines the name of the configuration file.
[in] | filename | the name of the configuration file. Before parsing command line arguments, arguments are set according to this file, loaded from the home directory (or 'My Documents' under Windows). Default is 'geogram.ini'. |
[in] | auto_create_args | if set, all the args present in the configuration file are created if they do not already exist, else a warning message is displayed for args that do not exist. |
bool GEO::CmdLine::set_profile | ( | const std::string & | name | ) |
Sets the current application profile.
A profile is a predefined set of property values that affect the configuration of the Vorpaline library in order to perform very specific tasks. Only a single profile can be active at a time, but nothing prevents from tweaking indivual properties to fine tune the profile values.
Vorpaline defines the following profiles:
[in] | name | the name of the profile, as defined above. |
void GEO::CmdLine::show_usage | ( | const std::string & | additional_args = "" , |
bool | advanced = false |
||
) |
Displays program help.
Displays a list of all declared arguments (sorted by argument group) with their current value. By default, show_usage() only displays standard groups and arguments. If parameter advanced
is set to true
, show_usage() also displays advanced groups and arguments (declared with flag ARG_ADVANCED).
[in] | additional_args | additional argument specification (see parse()). |
[in] | advanced | boolean flag that controls the display of advanced groups and arguments. |
void GEO::CmdLine::terminate | ( | ) |
Cleans up the command line framework.
This function must be called at program termination program. It is called by the general cleanup function GEO::terminate().
void GEO::CmdLine::ui_clear_line | ( | ) |
Clears the last line.
This function is only used in pretty mode and mainly to display progress bars.
void GEO::CmdLine::ui_close_separator | ( | ) |
Closes an opened separator.
This closes the last opened box. When the Logger is in pretty mode, the separator has the following form:
In non-pretty mode, or if the program output is redirected to a file, nothing is printed.
std::string GEO::CmdLine::ui_feature | ( | const std::string & | feature, |
bool | show = true |
||
) |
Formats a Logger feature name.
Logger features are displayed with a special formatting in the output log. They precede the messages sent to the Logger as illustrated below:
Multiple messages sent to the Logger with the same feature display the feature only once:
If parameter show
is set to true
, the function returns the feature formatted as for the first message in the example above. If show
is set to false
, the functions returns an empty placeholder used as a left margin length.
[in] | feature | the text of the feature |
[in] | show | true to actually display the feature name or false to return an empty placeholder of the same width |
void GEO::CmdLine::ui_message | ( | const std::string & | message | ) |
Outputs a message on the console.
This is a variant of ui_message() with a default wrap_margin that keeps wrapped lines aligned with the end of the feature names.
[in] | message | the message to print |
void GEO::CmdLine::ui_message | ( | const std::string & | message, |
index_t | wrap_margin | ||
) |
Outputs a message on the console.
Prints the message message
to the console. In pretty mode, the message is enclosed in vertical bars, thus forming a box with the previous separator (see ui_separator()). If the message is too long to fit in the console width, it is wrapped on the next line(s) with an additional left margin given by wrap_margin
.
In non-pretty mode, the message is printed "as is".
[in] | message | the message to print |
[in] | wrap_margin | extra left margin used to print continuation lines of long messages |
void GEO::CmdLine::ui_progress | ( | const std::string & | task_name, |
index_t | val, | ||
index_t | percent, | ||
bool | clear = true |
||
) |
Displays a progress bar.
This displays a progress bar for the given task task
name. The progress of the task is specified by the current progress value val
and the percentage of completion percent
. The progress bar is formatted as illustrated below:
where:
[in] | task_name | the name of the task in progress |
[in] | val | the current progress value |
[in] | percent | the percentage of completion |
[in] | clear | whether to clear the line before displaying the progress bar (default is true ) |
void GEO::CmdLine::ui_progress_canceled | ( | const std::string & | task_name, |
double | elapsed, | ||
index_t | percent, | ||
bool | clear = true |
||
) |
Displays the time elapsed for a canceled task.
Call this function when a task has been canceled to display the elapsed time elapsed
and the percentage of completion percent
.
[in] | task_name | the name of the task being completed. |
[in] | elapsed | the time elapsed since the beginning of the task |
[in] | percent | the percentage of completion of the task |
[in] | clear | whether to clear the line before displaying the progress bar (default is true ) |
void GEO::CmdLine::ui_progress_time | ( | const std::string & | task_name, |
double | elapsed, | ||
bool | clear = true |
||
) |
Displays the time elapsed for a completed task.
Call this function after successive calls to ui_progress() to display the elapsed time once the task task task_name
has completed.
[in] | task_name | the name of the task being completed. |
[in] | elapsed | the time elapsed for completing the task |
[in] | clear | whether to clear the line before displaying the progress bar (default is true ) |
void GEO::CmdLine::ui_separator | ( | ) |
Outputs a separator without a title on the console.
Prints a simple separator string on the console. When the Logger is in pretty mode, the separator has the following form:
In non-pretty mode, or if the program output is redirected to a file, nothing is printed.
void GEO::CmdLine::ui_separator | ( | const std::string & | title, |
const std::string & | short_title = "" |
||
) |
Outputs a separator with a title on the console.
Prints a separator string on the console that contains the given title
and optional short_title
. If it is specified, the short_title
appears on the left of title
in the separator as illustrated below. This function is used by Logger::div() to create a new division in the log output.
When the Logger is in pretty mode, the separator has the following form:
Otherwise the separator has the following form In non-pretty mode, or if the program output is redirected to a file, the separator has the following form:
[in] | title | the main title string |
[in] | short_title | optional title that appears on the left of title |
index_t GEO::CmdLine::ui_terminal_width | ( | ) |
Gets the width of the console.