December / Monthly / Tutorials / Software / Home

Command line programming and manipulations is an integral component of any tool in the Unix environment. Command line interfaces are necessary to allow the user to set options and arguments when executing programs. However, during the process of application development, a significant amount of effort is spent on rewriting command line parsing code for each utility because of the absence of a well-defined and reusable command line interface. To overcome these drawbacks, all the tools and the utilities in our programming environment maintain a common command line interface. In this tutorial, we introduce you to the command line interface, and show you how easily it can be implemented in a C++ program.

The command line interface supported in our foundation classes (IFC's) is implemented through the CommandLine class. This command line interface follows standard Unix conventions. The class encapsulates several features that make implementation of the command line functionality in a utility trivial. The interface supported by this class is listed below.
  • Options - Options can appear anywhere in the command line. The specified option is set to its corresponding value. (e.g., "-sf 7000.0")

  • Option Names - Option names can be abbreviated as long as the abbreviation is unique. For example, "-sample_frequency" can be entered using "-samp" or even "-s", given the fact that no other options begin with "s".

  • Arguments - Arguments are generally filenames and must be in a pre-specified order.

  • Flags - Flags can also appear anywhere in the command line and are used only as a boolean option. Any flag not present in the command line is assumed false.

  • Help Message - A detailed help message is available for all utilities by using the "-help" option.

  • Usage Message - A brief help message describing the usage in case the user did not follow the utility interface in the command line.

  • Debug Message - Debugging information can be obtained by specifying the debug option "-debug". Allowed values are "NONE", "BRIEF", "DETAILED", and "ALL". These provide varying amounts of debugging information. All utilities and classes in IFC's support this option.

The code given below is an example of how we parse the command line from within a C++ program. 
    // declare a command line, and a string containing an example command line
//
CommandLine cmdl;
String str(L"foo.exe -nbytes 4 -mode stereo file.raw");

// add the mode
//
String mode_param(L"mode");
String mode_def(L"play");
String mode;
              
cmdl.addOptionParam(mode, mode_param, mode_def);
              
// add the number of bytes
//
String nbytes_param(L"nbytes");
Long nbytes;

cmdl.addOptionParam(nbytes, nbytes_param, (long)2);
              
// set the help message
//
cmdl.setHelp(#include "dbg_help.help");
              
// parse the commandline
//
cmdl.parse(str);
              
// print the mode
//
mode.debug(L"mode");
              
// get number of unused arguments
//
Long num_arg = (long)cmdl.numArguments();
              
// get unused arguments
//
String arg;
cmdl.getArgument(arg, 0);
              
// print the number of unused arguments
//
num_arg.debug(L"numArguments");
              
// print the unused argument
//
arg.debug(L"getArgument");
In the above example, the CommandLine class is used to parse a string, str, that represents a simulated command line. There are two options: the nbytes option and the mode option. Each option is defined separately using the function addOptionParam. This function has three parameters. The first is a variable that stores the value of the given option. The second is the name of the option. The third parameter is the default value for the option. Next, the help message is defined using the setHelp function. The parameter for this function is an external file containing the help message. Once all of the options have been defined, the string str is parsed. The number of arguments (filenames) in the string are determined using the numArguments function. These arguments are accessed using the getArguments function. Unlike options, these arguments should usually appear in a pre-defined order.

The code segment shown below is a snap-shot of the command line parsing code for a utility named isip_transform. 
    CommandLine cmdl(sdb);
  
cmdl.setUsage(
#include "usage_message.text"
             );
cmdl.setHelp(
#include "help_message.text"
            );
  
cmdl.setIdent("$Revision: 1.10 $",
              "$Name:  $",
	      "$Date: 2006/06/30 22:39:59 $");
  
// add a command line option for output type
//
String output_type;
cmdl.addOptionParam(output_type, OPTION_OUTPUT_TYPE, EMPTY);

// add a command line option for suffix
//
String output_suffix;
cmdl.addOptionParam(output_suffix, OPTION_OUTPUT_SUFFIX, EMPTY);      

// add a command line option for the parameter file
//
Filename param_file;
cmdl.addOptionParam(param_file, OPTION_PARAMS_FILE, (Filename)EMPTY);
  
// add a command line option for the debug level
//
DebugLevel debug_level;
cmdl.addOptionParam(debug_level, OPTION_DEBUG_LEVEL);
  
// add a command line option for the verbosity
//
DebugLevel verbosity;
cmdl.addOptionParam(verbosity, OPTION_VERBOSITY_LEVEL);
  
// add a command line option for the log file
//
Filename log_file;
cmdl.addOptionParam(log_file, OPTION_LOG_FILE, (Filename)LOG_FILE_DEFAULT);
  
// parse the command line
//
cmdl.parse(argc,argv);
Refer to the online manual pages for a complete description of the CommandLine class. To see detailed examples of the usage of this class, refer to any of the utilities provided in our software distribution.