SimpleOpt.h File Reference

A cross-platform command line library which can parse almost any of the standard command line formats in use today. It is designed explicitly to be portable to any platform and has been tested on Windows and Linux. See CSimpleOptTempl for the class definition. More...

#include <stdlib.h>
#include <string.h>

Go to the source code of this file.

Classes
class	CSimpleOptTempl< SOCHAR >
	Implementation of the SimpleOpt class. More...
struct	CSimpleOptTempl< SOCHAR >::SOption
	Structure used to define all known options. More...
Defines
#define	SO_END_OF_OPTIONS   { -1, NULL, SO_NONE }
	this option definition must be the last entry in the table
#define	SO_ASSERT(b)
	assertion used to test input data
#define	CSimpleOpt   CSimpleOptA
	TCHAR version dependent on if _UNICODE is defined.
Typedefs
typedef enum _ESOError	ESOError
	Error values.
typedef enum _ESOArgType	ESOArgType
typedef CSimpleOptTempl< char >	CSimpleOptA
	ASCII/MBCS version of CSimpleOpt.
typedef CSimpleOptTempl< wchar_t >	CSimpleOptW
	wchar_t version of CSimpleOpt
Enumerations
enum	_ESOError {   SO_SUCCESS = 0, SO_OPT_INVALID = -1, SO_OPT_MULTIPLE = -2, SO_ARG_INVALID = -3,   SO_ARG_INVALID_TYPE = -4, SO_ARG_MISSING = -5, SO_ARG_INVALID_DATA = -6 }
	Error values. More...
enum	_ESOFlags {   SO_O_EXACT = 0x0001, SO_O_NOSLASH = 0x0002, SO_O_SHORTARG = 0x0004, SO_O_CLUMP = 0x0008,   SO_O_USEALL = 0x0010, SO_O_NOERR = 0x0020, SO_O_PEDANTIC = 0x0040, SO_O_ICASE_SHORT = 0x0100,   SO_O_ICASE_LONG = 0x0200, SO_O_ICASE_WORD = 0x0400, SO_O_ICASE = 0x0700 }
	Option flags. More...
enum	_ESOArgType {   SO_NONE, SO_REQ_SEP, SO_REQ_CMB, SO_OPT,   SO_MULTI }

---

Detailed Description

A cross-platform command line library which can parse almost any of the standard command line formats in use today. It is designed explicitly to be portable to any platform and has been tested on Windows and Linux. See CSimpleOptTempl for the class definition.

Version:

3.5

FEATURES

• MIT Licence allows free use in all software (including GPL and commercial)
• multi-platform (Windows 95/98/ME/NT/2K/XP, Linux, Unix)
• supports all lengths of option names:

  -	switch character only (e.g. use stdin for input)
  -o	short (single character)
  -long	long (multiple character, single switch character)
  --longer	long (multiple character, multiple switch characters)

• supports all types of arguments for options:

  --option	short/long option flag (no argument)
  --option ARG	short/long option with separate required argument
  --option=ARG	short/long option with combined required argument
  --option[=ARG]	short/long option with combined optional argument
  -oARG	short option with combined required argument
  -o[ARG]	short option with combined optional argument

• supports options with multiple or variable numbers of arguments:

  --multi ARG1 ARG2	Multiple arguments
  --multi N ARG-1 ARG-2 ... ARG-N	Variable number of arguments

• supports case-insensitive option matching on short, long and/or word arguments.
• supports options which do not use a switch character. i.e. a special word which is construed as an option. e.g. "foo.exe open /directory/file.txt"
• supports clumping of multiple short options (no arguments) in a string e.g. "foo.exe -abcdef file1" <==> "foo.exe -a -b -c -d -e -f file1"
• automatic recognition of a single slash as equivalent to a single hyphen on Windows, e.g. "/f FILE" is equivalent to "-f FILE".
• file arguments can appear anywhere in the argument list: "foo.exe file1.txt -a ARG file2.txt --flag file3.txt file4.txt" files will be returned to the application in the same order they were supplied on the command line
• short-circuit option matching: "--man" will match "--mandate" invalid options can be handled while continuing to parse the command line valid options list can be changed dynamically during command line processing, i.e. accept different options depending on an option supplied earlier in the command line.
• implemented with only a single C++ header file
• optionally use no C runtime or OS functions
• char, wchar_t and Windows TCHAR in the same program
• complete working examples included
• compiles cleanly at warning level 4 (Windows/VC.NET 2003), warning level 3 (Windows/VC6) and -Wall (Linux/gcc)

USAGE

The SimpleOpt class is used by following these steps:

1. Include the SimpleOpt.h header file

           #include "SimpleOpt.h"
           

2. Define an array of valid options for your program.

    CSimpleOpt::SOption  g_rgOptions[] = {
       { OPT_FLAG, _T("-a"),     SO_NONE    }, // "-a"
       { OPT_FLAG, _T("-b"),     SO_NONE    }, // "-b"
       { OPT_ARG,  _T("-f"),     SO_REQ_SEP }, // "-f ARG"
       { OPT_HELP, _T("-?"),     SO_NONE    }, // "-?"
       { OPT_HELP, _T("--help"), SO_NONE    }, // "--help"
       SO_END_OF_OPTIONS                       // END
   };
   

   Note that all options must start with a hyphen even if the slash will be accepted. This is because the slash character is automatically converted into a hyphen to test against the list of options. For example, the following line matches both "-?" and "/?" (on Windows).

           { OPT_HELP, _T("-?"),     SO_NONE    }, // "-?"
           

3. Instantiate a CSimpleOpt object supplying argc, argv and the option table

    CSimpleOpt  args(argc, argv, g_rgOptions);
   

4. Process the arguments by calling Next() until it returns false. On each call, first check for an error by calling LastError(), then either handle the error or process the argument.

   while (args.Next()) {
       if (args.LastError() == SO_SUCCESS) {
           handle option: use OptionId(), OptionText() and OptionArg()
       }
       else {
           handle error: see ESOError enums
       }
   }
   

5. Process all non-option arguments with File(), Files() and FileCount()

   ShowFiles(args.FileCount(), args.Files());
   

NOTES

• In MBCS mode, this library is guaranteed to work correctly only when all option names use only ASCII characters.
• Note that if case-insensitive matching is being used then the first matching option in the argument list will be returned.

MIT LICENCE

The licence text below is the boilerplate "MIT Licence" used from: http://www.opensource.org/licenses/mit-license.php

Copyright (c) 2006-2007, Brodie Thiesfield

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Definition in file SimpleOpt.h.

---

Typedef Documentation

typedef enum _ESOArgType ESOArgType

Types of arguments that options may have. Note that some of the _ESOFlags are not compatible with all argument types. SO_O_SHORTARG requires that relevant options use either SO_REQ_CMB or SO_OPT. SO_O_CLUMP requires that relevant options use only SO_NONE.

---

Enumeration Type Documentation

enum _ESOArgType

Types of arguments that options may have. Note that some of the _ESOFlags are not compatible with all argument types. SO_O_SHORTARG requires that relevant options use either SO_REQ_CMB or SO_OPT. SO_O_CLUMP requires that relevant options use only SO_NONE.

Enumerator:

SO_NONE	No argument. Just the option flags. e.g. -o --opt
SO_REQ_SEP	Required separate argument. e.g. -o ARG --opt ARG
SO_REQ_CMB	Required combined argument. e.g. -oARG -o=ARG --opt=ARG
SO_OPT	Optional combined argument. e.g. -o[ARG] -o[=ARG] --opt[=ARG]
SO_MULTI	Multiple separate arguments. The actual number of arguments is determined programatically at the time the argument is processed. e.g. -o N ARG1 ARG2 ... ARGN --opt N ARG1 ARG2 ... ARGN

Definition at line 293 of file SimpleOpt.h.

enum _ESOError

Error values.

Enumerator:

SO_SUCCESS	No error.
SO_OPT_INVALID	It looks like an option (it starts with a switch character), but it isn't registered in the option table.
SO_OPT_MULTIPLE	Multiple options matched the supplied option text. Only returned when NOT using SO_O_EXACT.
SO_ARG_INVALID	Option doesn't take an argument, but a combined argument was supplied.
SO_ARG_INVALID_TYPE	SO_REQ_CMB style-argument was supplied to a SO_REQ_SEP option Only returned when using SO_O_PEDANTIC.
SO_ARG_MISSING	Required argument was not supplied.
SO_ARG_INVALID_DATA	Option argument looks like another option. Only returned when NOT using SO_O_NOERR.

Definition at line 211 of file SimpleOpt.h.

enum _ESOFlags

Option flags.

Enumerator:

SO_O_EXACT	Disallow partial matching of option names
SO_O_NOSLASH	Disallow use of slash as an option marker on Windows. Un*x only ever recognizes a hyphen.
SO_O_SHORTARG	Permit arguments on single letter options with no equals sign. e.g. -oARG or -o[ARG]
SO_O_CLUMP	Permit single character options to be clumped into a single option string. e.g. "-a -b -c" <==> "-abc"
SO_O_USEALL	Process the entire argv array for options, including the argv[0] entry.
SO_O_NOERR	Do not generate an error for invalid options. errors for missing arguments will still be generated. invalid options will be treated as files. invalid options in clumps will be silently ignored.
SO_O_PEDANTIC	Validate argument type pedantically. Return an error when a separated argument "-opt arg" is supplied by the user as a combined argument "-opt=arg". By default this is not considered an error.
SO_O_ICASE_SHORT	Case-insensitive comparisons for short arguments
SO_O_ICASE_LONG	Case-insensitive comparisons for long arguments
SO_O_ICASE_WORD	Case-insensitive comparisons for word arguments i.e. arguments without any hyphens at the start.
SO_O_ICASE	Case-insensitive comparisons for all arg types

Definition at line 241 of file SimpleOpt.h.