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

packageSummary

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 TCLAP. 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).

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:

        #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

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

• May 09 : wrapper for the tclap headers written.
• May 09 : 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.