ecl_command_line Documentation

ecl_command_line

Embeds the TCLAP library inside the ecl. This is a very convenient command line parser in templatised c++.

• Homepage: http://wiki.ros.org/ecl_command_line

Embedded Control Library

    Provides a templatised c++ parser for handling command line arguments.
    The templates provide a very flexible manner for handling any type
    of input argument.

    The code for the command line parser is a simple wrapper around another
    template header library called <a href="http://tclap.sourceforge.net/">TCLAP</a>.
    Since it is relatively small, its
    bundled here in the command_line subdirectory and namespaced
    in a convenient manner. Licensing terms (MIT) are included in the
    command_line subdirectory (also included as an install target).

    @subsection Alternatives

            A more complicated, but more flexible alternative
            (it allows argument parsing from both command line and configuration
            file simultaneously) is the boost::program_options library.

Compiling & Linking

    Include the following at the top of any translation unit which
    requires this library:

    @code
    #include <ecl/command_line.hpp>

// Interface classes
using ecl::CmdLine;
using ecl::ArgException
// Argument classes
using ecl::SwitchArg;
using ecl::ValueArg;
using ecl::MultiArg;
using ecl::UnlabeledValueArg; 
using ecl::UnlabeledMultiArg; // there are more - see tclap docs
    @endcode


    Since it is a template header library, no linking is required if you are
    only using these classes.

Usage

Initialisation

A single object is used to parse the command line. Initialise it with a few default properties. These will be used to automatically generate a –help argument.

// Supply a program description, argument separator (optional) and version number (optional).
CmdLine cmd("This is a test program to test the command line parsing facilities provided by TCLAP.");
// CmdLine cmd("This is a test program to test the command line parsing facilities provided by TCLAP.", ' ', "0.01");

Adding Arguments

// Add a boolean (flag, name, description, default)
SwitchArg debug("d","debug","Enable debugging.", false);
cmd.add(debug);
 
// Add an int (flag,name,description,compulsory flag,default value,help description of the type")
ValueArg<int> intArg("i","integer","An integer argument for testing.",false,5,"integer");
// Not a regular option (name,description,compulsory flag,default value,help description of the type")
UnlabeledValueArg<std::string> outputDirArg("output_dir","Output directory for rectified images.",true,"./rectified","string");
 
cmd.add(intArg);

Valid argument types include

• SwitchArg : simple boolean.
• ValueArg : expect some value on the command line.
• MultiArg : permit multiple values for an argument which get stored in a vector.
• MultiSwitchArg : as above, but for booleans, not often used so see TCLAP for more instructions.
• UnlabeledValueArg : does not use a flag (like the arguments for copy), order is important!
• UnlabeledMultiArg : reads in all remaining unlabelled args (like rm file1.txt file2.txt etc.)

Custom Arguments

Custom ValueArg types can be used so long as they implement the >> operator.

Further Help (TCLAP)

Most of tclap's doxygen is generated automatically inside the ecl. For more detailed documentation, read the manual at tclap's home page.

Unit Tests

    - src/test/command_line.cpp

Examples

    - src/examples/command_line.cpp

ChangeLog

    - <b>May 09</b> : wrapper for the tclap headers written.
    - <b>May 09</b> : initial import of the tclap headers.

Errata

    Now it's in the ros, at some point in the future I will unwind this back to the original package since it no longer needs
    to be embedded in the ecl.