name: CommandLine
synopsis:

>     g++ [flags ...] commandline ... -l /isip/tools/lib/$ISIP_BINARY/lib_shell.a

>     #include <CommandLine.h>

>     ~CommandLine();
>     CommandLine();
>     CommandLine(const CommandLine& arg);
>     boolean setHelp(const unichar* help_message);
>     String& addOptionParam(Long& var, const String& param, long def_value);
>     boolean parse(int argc, const char** argv);
>     long getOptionIndex(const String& param_name);

quick start:

>     String com_str(L"foo.exe -swap -sf 7000.0 -help");

>     CommandLine cmdl;

>     // add an swap flag
>     //
>     String flag_param(L"swap");
>     Boolean swap;
>     cmdl.addFlagParam(swap, flag_param);

>     // add a sample frequency
>     //
>     String sf_param(L"sf");
>     Float sf;
>     cmdl.addOptionParam(sf, sf_param, (float)8000.0);

>     // parse the commandline
>     //
>     cmdl.parse(com_str);

>     // test the swap flag
>     //
>     if (swap) {
>      Console::put(L"swap flag specified");
>     }

>     // print the sample frequency
>     //
>     sf.debug(L"sample frequency");

description:
The CommandLine class is designed to parse a Unix command line using a standard interface. It is used by every ISIP utility. There are three types of entities found on a command line: arguments, options, and flags. Arguments are present in a pre-specified order and require no qualifiers. Options can appear anywhere on the command line, setting the specified data to the following token.
Flags, like options, can appear anywhere on the command line, yet they are used for boolean data. Any flag not present on the command line is assumed false.
The command line handles partial name completion. If any option is specified partially on command line and it is the single match then commandline accepts this option. If there is more than one match, it is specified as an error.
Certain option names are reserved for use across all ISIP utilities. These include:

- -debug_level: controls the amount of debugging information displayed when a command is run; see DebugLevel for more details.
- -parameter_file: specifies the parameter file to be used to configure the tool.
- -type: used to control whether binary or text files are created; see the File class for more details.
- -verbosity: controls how much status information is displayed during normal processing; uses the same values and interface as DebugLevel.
- -echo_command_line: echoes the command line to the console; useful for programs that want to capture the command line to a log file.
- -help: displays a help message.
- -usage: displays a short message describing the typical use of the command.
- -version: displays version information about the compiled program.

There are also some parameters associated with file processing that used by the Sof database class Sdb. These are:

- -directory: determines what output directory will be used for files created from list processing.
- -extension: the new file extension (e.g., "sof" in "foo.sof").
- -preserve: controls how much of the pathname is preserved when a new filename is generated from an input filename.
- -suffix: a field that can be added to a new filename (e.g. "_0" in "foo_0.sof").

Sdb also reserves one more option name "-list" to identify Sdb files from the command line. The "-list" option allows command line processing to avoid gross inefficiencies in processing lists of files. All these options are described in more detail in the File class and Sdb.
dependencies:

- File
- Boolean
- Vector
- DebugLevel
- Filename
- Sdb

public constants:

- define the class name:

      static const String CLASS_NAME = L"CommandLine";

- default values for parameters for command line parsing:

      static const String DEF_PARAM_PREFIX = L"-";

      static const String DEF_PARAM_SPACE = L" ";

- default values for standard command line options: these are constants for option names expected to be standardized across all utilities. Programs should reference these definitions rather than duplicate them.

      static const String DEF_PARAM_DEBUG = L"debug_level";

      static const String DEF_PARAM_LFILE = L"log_file";

      static const String DEF_PARAM_PFILE = L"parameter_file";

      static const String DEF_PARAM_TYPE = L"type";

      static const String DEF_PARAM_VERBOSITY = L"verbosity";

- default values for parameters for Sdb filename parsing:

      static const String DEF_PARAM_DIRECTORY = L"directory";

      static const String DEF_PARAM_BASENAME = L"basename";

      static const String DEF_PARAM_EXTENSION = L"extension";

      static const String DEF_PARAM_PRESERVE = L"preserve";

      static const String DEF_PARAM_SUFFIX = L"suffix";

- default values for command line messaging:

      static const String DEF_PARAM_ECHOC = L"echo_command_line";

      static const String DEF_PARAM_HELP = L"help";

      static const String DEF_PARAM_USAGE = L"usage";

      static const String DEF_PARAM_VERSION = L"version";

- default values for parameters for temporary space:

      static const long DEF_OBJECTS_SIZE = 100;

- default values for selected output strings:

      static const String COMMAND_STR = L"Command:";

      static const String NO_VERSION_NAME = L"not released";

      static const String VERSION_STR = L"Version: ";

      static const String REPORT_STR_00 = L": processed ";

      static const String REPORT_STR_01 = L" file(s), attempted ";

      static const String REPORT_STR_02 = L" file(s).\n";

- special code for an Sdb list option:

      static const long OPT_INDEX_SDB = 99999;

- default values for selected command line options

      static Filename DEF_EMPTY = L"";

      static Filename DEF_LFILE_NAME = L"-";

error codes:

- error code indicating general CommandLine class error:

      static const long ERR = 45000;

- error code indicating option not found:

      static const long ERR_OPT = 45001;

- error code indicating ambiguous partial completion for option:

      static const long ERR_OPTAMB = 45002;

- error code indicating user specified multiple times option:

      static const long ERR_OPTDUPL = 45003;

- error code indicating programmer specified multiple times option:

      static const long ERR_OPTMULT = 45004;

- error code indicating non-boolean option appears at end of list:

      static const long ERR_OPTARG = 45005;

- error code indicating an option name did not exist on the command line:

      static const long ERR_OPTPARS = 45006;

protected data:

- define the program name (argv[0]):

      String prog_name_d;

- define command line options:

      Vector<String> options_d;

- define data types for each option:

      Vector<String> types_d;

- define a vector to track whether an option has been used:

      Vector<Boolean> used_d;

- define a vector to hold unused arguments:

      Vector<String> args_d;

- define a vector to hold the values supplied for each argument on the command line:

      Vector<String> values_d;

- define a flag for echoing the command line:

      Boolean echoc_flag_d;

- define a flag to indicate the help message needs to be displayed:

      Boolean help_flag_d;

- define a flag for displaying the usage message:

      Boolean usage_flag_d;

- define a variable used to display a version flag:

      Boolean version_flag_d;

- define a string for the help flag:

      String help_msg_d;

- define a string to hold the usage message:

      String usage_msg_d;

- define a string to hold the version message:

      String version_msg_d;

- define a string to hold an expanded command line:

      String expanded_d;

- define a pointer to an Sdb object:

      Sdb* sdb_d;

- define the size of the list of options:

      long objects_size_d;

- define array of void pointers to hold the objects:

      void** objects_d;

- define a flag for tracking usage message printing:

      boolean usage_printed_d;

- define a diagnostic parameter:

      static boolean test_mode_d;

- define a debug level:

      Integral::DEBUG debug_level_d;

- define the static memory manager:

      static MemoryManager mgr_d;

required public methods:

- static methods:

      static const String& name();

      static boolean diagnose(Integral::DEBUG debug_level);

- debug methods:

      boolean setDebug(Integral::DEBUG level);

      boolean debug(const unichar* message) const;

- destructor/ constructor(s):

      ~CommandLine();

      CommandLine();

      CommandLine(const CommandLine& arg);

- assign methods:

      boolean assign(const CommandLine& arg);

- operator= methods:

      CommandLine& operator=(const CommandLine& arg);

- i/o methods:

      these methods are omitted because CommandLine object can not
      write itself to an Sof file

- equality methods:

      boolean eq(const CommandLine& arg) const;

- memory management methods:

      static void* operator new(size_t size);

      static void* operator new[](size_t size);

      static void operator delete(void* ptr);

      static void operator delete[](void* ptr);

      static boolean setGrowSize(long grow_size);

      boolean clear(Integral::CMODE cmode = Integral::DEF_CMODE);

class-specific public methods:

- destructor/ constructor(s):

      CommandLine(Sdb& arg);

- assign methods:

      boolean assign(const String& arg);

- set help and usage file methods:

      boolean setHelp(const unichar* help_message);

      boolean setUsage(const unichar* usage_message);

      boolean setVersion(const unichar* version_message);

      boolean setIdent(const char* rev_str, const char* name_str, const char* date_str);

- set Sdb object methods:

      boolean setSdb(Sdb& arg_a);

- print methods:

      boolean printUsage();

      boolean printHelp() const;

      boolean printVersion() const;

      boolean printCommandLine() const;

      static boolean printFinalReport(const String& prog_name, long num_completed, long num_attempted);

      boolean printFinalReport(long num_completed, long num_attempted) const;

- methods to add options that are logical flags:

      boolean addFlagParam(Boolean& var, const String& param);

- methods to add options for specific types of parameters:

      boolean addOptionParam(File::TYPE& var, const String& param, const File::TYPE& def_value = File::DEF_TYPE);

      boolean addOptionParam(String& var, const String& param, const String& def_value);

      boolean addOptionParam(Filename& var, const String& param, const Filename& def_value);

      boolean addOptionParam(DebugLevel& var, const String& param = DebugLevel::DEF_PARAM, Integral::DEBUG def_value = Integral::DEF_DEBUG);

      boolean addOptionParam(Byte& var, const String& param, byte def_value);

      boolean addOptionParam(Short& var, const String& param, short def_value);

      boolean addOptionParam(Long& var, const String& param, long def_value);

      boolean addOptionParam(Llong& var, const String& param, llong def_value);

      boolean addOptionParam(Ushort& var, const String& param, ushort def_value);

      boolean addOptionParam(Ulong& var, const String& param, ulong def_value);

      boolean addOptionParam(Ullong& var, const String& param, ullong def_value);

      boolean addOptionParam(Float& var, const String& param, float def_value);

      boolean addOptionParam(Double& var, const String& param, double def_value);

- methods to add multiple valued options:

      boolean addOptionParam(SingleLinkedList<String>& var, const String& param);

      boolean addOptionParam(SingleLinkedList<Filename>& var, const String& param);

      boolean addOptionParam(SingleLinkedList<Byte>& var, const String& param);

      boolean addOptionParam(SingleLinkedList<Short>& var, const String& param);

      boolean addOptionParam(SingleLinkedList<Long>& var, const String& param);

      boolean addOptionParam(SingleLinkedList<Llong>& var, const String& param);

      boolean addOptionParam(SingleLinkedList<Ushort>& var, const String& param);

      boolean addOptionParam(SingleLinkedList<Ulong>& var, const String& param);

      boolean addOptionParam(SingleLinkedList<Ullong>& var, const String& param);

      boolean addOptionParam(SingleLinkedList<Float>& var, const String& param);

      boolean addOptionParam(SingleLinkedList<Double>& var, const String& param);

- get methods:

      const String& getProgName() const;

      boolean getArgument(String& arg_a, long ordinal_number) const;

      long numArguments() const;

      boolean getExpanded(String& arg);

      long getOptionIndex(const String& opt_name , boolean prefix = false);

      boolean getValue(String& value, const String& opt_name, boolean prefix = false);

      boolean isPresent(const String& opt_name, boolean prefix = false) const;

- parse methods:

      boolean parse(int argc, const char** argv);

      boolean parse(const String& line);

private methods:

- a general add option method:

      boolean addOptionParam(void* var, const String& name, const String& param);

- a multiple parameter type checking method:

      boolean isMultipleParam(long index);

examples:

- This example shows how to retrieve the command line arguments and values for the following program:

      foo.exe -nbytes 4 -mode stereo file.raw

  The code below demonstrates how to initialize a command line object to process this command line:

      // 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");

notes:

- The main advantage of this class is that it is used by every utility, and hence centralizes command line argument processing. It is also a way of providing a uniform interface across all utilities, since this class standardizes the syntax for command line arguments.