Joe Verbout / Mbed 2 deprecated main

opencv on mbed

Dependencies:   mbed

Embed: (wiki syntax)

« Back to documentation index

CommandLineParser Class Reference
Public Member Functions

CommandLineParser Class Reference
[Utility and system functions and macros]

Designed for command line parsing. More...

#include <utility.hpp>

Public Member Functions

 CommandLineParser (int argc, const char *const argv[], const String &keys)
 Constructor.
 CommandLineParser (const CommandLineParser &parser)
 Copy constructor.
CommandLineParser & operator= (const CommandLineParser &parser)
 Assignment operator.
 ~CommandLineParser ()
 Destructor.
String getPathToApplication () const
 Returns application path.
template<typename T >
T get (const String &name, bool space_delete=true) const
 Access arguments by name.
template<typename T >
T get (int index, bool space_delete=true) const
 Access positional arguments by index.
bool has (const String &name) const
 Check if field was provided in the command line.
bool check () const
 Check for parsing errors.
void about (const String &message)
 Set the about message.
void printMessage () const
 Print help message.
void printErrors () const
 Print list of errors occured.

Detailed Description

Designed for command line parsing.

The sample below demonstrates how to use CommandLineParser: 

    CommandLineParser parser(argc, argv, keys);
    parser.about("Application name v1.0.0");

    if (parser.has("help"))
    {
        parser.printMessage();
        return 0;
    }

    int N = parser.get<int>("N");
    double fps = parser.get<double>("fps");
    String path = parser.get<String>("path");

    use_time_stamp = parser.has("timestamp");

    String img1 = parser.get<String>(0);
    String img2 = parser.get<String>(1);

    int repeat = parser.get<int>(2);

    if (!parser.check())
    {
        parser.printErrors();
        return 0;
    }

### Keys syntax

The keys parameter is a string containing several blocks, each one is enclosed in curley braces and describes one argument. Each argument contains three parts separated by the `|` symbol:

  1. argument names is a space-separated list of option synonyms (to mark argument as positional, prefix it with the `@` symbol)
  2. default value will be used if the argument was not provided (can be empty)
  3. help message (can be empty)

For example:

 {.cpp}
    const String keys =
        "{help h usage ? |      | print this message   }"
        "{@image1        |      | image1 for compare   }"
        "{@image2        |<none>| image2 for compare   }"
        "{@repeat        |1     | number               }"
        "{path           |.     | path to file         }"
        "{fps            | -1.0 | fps for output video }"
        "{N count        |100   | count of objects     }"
        "{ts timestamp   |      | use time stamp       }"
        ;
}

Note that there are no default values for `help` and `timestamp` so we can check their presence using the `has()` method. Arguments with default values are considered to be always present. Use the `get()` method in these cases to check their actual value instead.

String keys like `get<String>("@image1")` return the empty string `""` by default - even with an empty default value. Use the special `<none>` default value to enforce that the returned string must not be empty. (like in `get<String>("@image2")`)

### Usage

For the described keys:

 {.sh}
    # Good call (3 positional parameters: image1, image2 and repeat; N is 200, ts is true)
    $ ./app -N=200 1.png 2.jpg 19 -ts

    # Bad call
    $ ./app -fps=aaa
    ERRORS:
    Parameter 'fps': can not convert: [aaa] to [double]

Definition at line 612 of file utility.hpp.

Constructor & Destructor Documentation

CommandLineParser ( int  argc,
const char *const   argv[],
const String &  keys 
)

Constructor.

Initializes command line parser object

Parameters:
argcnumber of command line arguments (from main())
argvarray of command line arguments (from main())
keysstring describing acceptable command line parameters (see class description for syntax)
CommandLineParser ( const CommandLineParser &  parser )

Copy constructor.

~CommandLineParser (  )

Destructor.

Member Function Documentation

void about ( const String &  message )

Set the about message.

The about message will be shown when printMessage is called, right before arguments table.

bool check (  ) const

Check for parsing errors.

Returns true if error occured while accessing the parameters (bad conversion, missing arguments, etc.). Call printErrors to print error messages list.

T get ( int  index,
bool  space_delete = true 
) const

Access positional arguments by index.

Returns argument converted to selected type. Indexes are counted from zero.

For example, define: 

 {.cpp}
    String keys = "{@arg1||}{@arg2||}"

Call: 

 {.sh}
    ./my-app abc qwe

Access arguments: 

 {.cpp}
    String val_1 = parser.get<String>(0); // returns "abc", arg1
    String val_2 = parser.get<String>(1); // returns "qwe", arg2
Parameters:
indexindex of the argument
space_deleteremove spaces from the left and right of the string
Template Parameters:
Tthe argument will be converted to this type if possible

Definition at line 711 of file utility.hpp.

T get ( const String &  name,
bool  space_delete = true 
) const

Access arguments by name.

Returns argument converted to selected type. If the argument is not known or can not be converted to selected type, the error flag is set (can be checked with check).

For example, define: 

 {.cpp}
    String keys = "{N count||}";

Call: 

 {.sh}
    $ ./my-app -N=20
    # or
    $ ./my-app --count=20

Access: 

 {.cpp}
    int N = parser.get<int>("N");
Parameters:
namename of the argument
space_deleteremove spaces from the left and right of the string
Template Parameters:
Tthe argument will be converted to this type if possible
Note:
You can access positional arguments by their `@`-prefixed name: 
 {.cpp}
    parser.get<String>("@image");

Definition at line 679 of file utility.hpp.

String getPathToApplication (  ) const

Returns application path.

This method returns the path to the executable from the command line (`argv[0]`).

For example, if the application has been started with such command: 

 {.sh}
    $ ./bin/my-executable

this method will return `./bin`.

bool has ( const String &  name ) const

Check if field was provided in the command line.

Parameters:
nameargument name to check
CommandLineParser& operator= ( const CommandLineParser &  parser )

Assignment operator.

void printErrors (  ) const

Print list of errors occured.

See also:
check
void printMessage (  ) const

Print help message.

This method will print standard help message containing the about message and arguments description.

See also:
about
Generated on Tue Jul 12 2022 16:42:43 by  doxygen 1.7.2