Sourceforge.net - The VCF's Project Host
   The VCF Website Home   |   Online Discussion Forums   |   Sourceforge.net Project Page   
VCF::CommandLine

VCF::CommandLine Class Reference

A utility for parsing command lines. More...

#include <vcf/FoundationKit/CommandLine.h>

Inheritance diagram for VCF::CommandLine:

VCF::Object List of all members.

Public Member Functions

 CommandLine ()
virtual ~CommandLine ()
int splitLine (int argc, char **argv)
 parse the command line into switches and arguments.
int splitLine (const String &commandLine)
int splitLine (const std::vector< String > &commandLine)
bool hasSwitch (const String &aSwitch) const
 was the switch found on the command line ?
String getSafeArgument (const String &aSwitch, size_t iIdx, const String &aDefault) const
 fetch an argument associated with a switch .
String getArgument (const String &aSwitch, size_t iIdx) const
 fetch a argument associated with a switch.
String getArgument (size_t index) const
int getArgumentCount (const String &aSwitch) const
Enumerator< String > * getOriginalCommands ()
size_t getArgCount () const
const std::vector< String > & getOriginalCommandLine () const

Protected Types

typedef std::map< String,
CmdParam > 		CommandLineMap

Protected Member Functions

bool isSwitch (const String &param) const
 protected member function test a parameter to see if it's a switch : switches are of the form : -x where 'x' is one or more characters.

Protected Attributes

CommandLineMap commandLine_
std::vector< String > originalCommandLine_
EnumeratorContainer< std::vector<
String >, String > 		commandLineContainer_

Detailed Description

A utility for parsing command lines.

This was originally written by Chris Losinger, changes were simply removing the inheritance from std::map<>, and adding a map as a member variable instead. Also made some cosmetic name changes to conform better with VCF naming standards.

Example :

Our example application uses a command line that has two required switches and two optional switches. The app should abort if the required switches are not present and continue with default values if the optional switches are not present.

Sample command line : MyApp.exe -p1 text1 text2 -p2 "this is a big argument" -opt1 -55 -opt2

Switches -p1 and -p2 are required. p1 has two arguments and p2 has one.

Switches -opt1 and -opt2 are optional. opt1 requires a numeric argument. opt2 has no arguments.

Also, assume that the app displays a 'help' screen if the '-h' switch is present on the command line.

   #include "CmdLine.h"

   void main(int argc, char **argv)
   {
      // our cmd line parser object
      CommandLine cmdLine;

      // parse argc,argv
      if (cmdLine.splitLine(argc, argv) &lt; 1)
      {
         // no switches were given on the command line, abort
         ASSERT(0);
         exit(-1);
      }

      // test for the 'help' case
      if (cmdLine.HasSwitch("-h"))
      {
         show_help();
         exit(0);
      }

      // get the required arguments
      String p1_1, p1_2, p2_1;
      try
      {
         // if any of these fail, we'll end up in the catch() block
         p1_1 = cmdLine.getArgument("-p1", 0);
         p1_2 = cmdLine.getArgument("-p1", 1);
         p2_1 = cmdLine.getArgument("-p2", 0);

      }
      catch (...)
      {
         // one of the required arguments was missing, abort
         ASSERT(0);
         exit(-1);
      }

      // get the optional parameters

      // convert to an int, default to '100'
      int iOpt1Val =    atoi(cmdLine.getSafeArgument("-opt1", 0, 100));

      // since opt2 has no arguments, just test for the presence of
      // the '-opt2' switch
      bool bOptVal2 =   cmdLine.hasSwitch("-opt2");

      .... and so on....

   }
Version:
1.0 Chris Losinger

2.0 Jim Crafton

Member Typedef Documentation

typedef std::map<String, CmdParam> VCF::CommandLine::CommandLineMap [protected]
 

Constructor & Destructor Documentation

VCF::CommandLine::CommandLine (   )  [inline]
 

virtual VCF::CommandLine::~CommandLine (   )  [inline, virtual]
 

Member Function Documentation

size_t VCF::CommandLine::getArgCount (   )  const [inline]
 

String VCF::CommandLine::getArgument (  size_t  index  )  const
 

String VCF::CommandLine::getArgument (  const String &  aSwitch,
size_t  iIdx
)  const
 

fetch a argument associated with a switch.

throws an exception of (int)0, if the parameter at index iIdx is not found.

example : 

    command line is : app.exe -a p1 p2 p3 -b p4 -c -d p5

      call                             return
      ----                             ------
      cmdLine.getArgument("-a", 0)     p1
      cmdLine.getArgument("-b", 1)     throws (int)0, returns an empty string

int VCF::CommandLine::getArgumentCount (  const String &  aSwitch  )  const
 

Returns:
the number of arguments found for a given switch. -1 if the switch was not found

const std::vector<String>& VCF::CommandLine::getOriginalCommandLine (   )  const [inline]
 

Enumerator<String>* VCF::CommandLine::getOriginalCommands (   )  [inline]
 

String VCF::CommandLine::getSafeArgument (  const String &  aSwitch,
size_t  iIdx,
const String &  aDefault
)  const
 

fetch an argument associated with a switch .

if the parameter at index iIdx is not found, this will return the default that you provide.

example : 

    command line is : app.exe -a p1 p2 p3 -b p4 -c -d p5

      call                                      return
      ----                                      ------
      cmdLine.getSafeArgument("-a", 0, "zz")    p1
      cmdLine.getSafeArgument("-a", 1, "zz")    p2
      cmdLine.getSafeArgument("-b", 0, "zz")    p4
      cmdLine.getSafeArgument("-b", 1, "zz")    zz

bool VCF::CommandLine::hasSwitch (  const String &  aSwitch  )  const
 

was the switch found on the command line ? 

    ex. if the command line is : app.exe -a p1 p2 p3 -b p4 -c -d p5

      call                          return
      ----                          ------
      cmdLine.hasSwitch("-a")       true
      cmdLine.hasSwitch("-z")       false
Returns:
bool true if it has the swith, otherwise false

bool VCF::CommandLine::isSwitch (  const String &  param  )  const [protected]
 

protected member function test a parameter to see if it's a switch : switches are of the form : -x where 'x' is one or more characters.

the first character of a switch must be non-numeric!

int VCF::CommandLine::splitLine (  const std::vector< String > &  commandLine  ) 
 

int VCF::CommandLine::splitLine (  const String &  commandLine  ) 
 

int VCF::CommandLine::splitLine (  int  argc,
char **  argv
) 
 

parse the command line into switches and arguments.

Returns:
int number of switches found

Member Data Documentation

CommandLineMap VCF::CommandLine::commandLine_ [protected]
 

EnumeratorContainer<std::vector<String>,String> VCF::CommandLine::commandLineContainer_ [protected]
 

std::vector<String> VCF::CommandLine::originalCommandLine_ [protected]
 

The documentation for this class was generated from the following file:
   Comments or Suggestions?    License Information