Image Component Library (ICL)
Classes | Functions
Programm Argument Evaluation Functions

Classes

struct  icl::utils::ProgArgException
 Programm argument environment exception type \. More...
class  icl::utils::ProgArg
 Programm argument utility class. More...

Functions

bool icl::utils::operator&& (const ProgArg &a, const ProgArg &b)
 this allows to check if two progargs are defined
bool icl::utils::operator&& (const ProgArg &a, bool b)
 allows to check more than two ProgArg instances at once
bool icl::utils::operator&& (bool &b, const ProgArg &a)
 allows to check more than two ProgArg instances at once
bool icl::utils::operator|| (const ProgArg &a, const ProgArg &b)
 this allows to check if either of two progargs are defined
bool icl::utils::operator|| (const ProgArg &a, bool b)
 allows to check if either of more than two ProgArg instances is defined
bool icl::utils::operator|| (bool &b, const ProgArg &a)
 allows to check if either of more than two ProgArg instances is defined
const ProgArg icl::utils::pa (const std::string &id, unsigned int subargidx=0) throw (ProgArgException)
 returns given program argument
const ProgArg icl::utils::pa (unsigned int idx, bool danglingOnly=true)
 returns given program argument at given index
template<class T >
const T icl::utils::pa_def (const std::string &id, unsigned int subargidx, const T &def) throw (ProgArgException)
 utility function that allows to use a default value, if given argument was not defined
template<class T >
const T icl::utils::pa_def (const std::string &id, const T &def) throw (ProgArgException)
 utility function that allows to use a default value, if given argument was not defined
ICLUtils_API unsigned int icl::utils::pa_get_count (bool danglingOnly=true)
 returns number of actually given args given
ICLUtils_API void icl::utils::pa_show_usage (const std::string &msg="")
 shows current available programm arguments
PAEX icl::utils::pa_explain (const std::string &pa, const std::string &ex)
 This function can be used to provide additional information for certain program arguments.
ICLUtils_API void icl::utils::pa_init (int n, char **ppc, const std::string &init, bool allowDanglingArgs=false)
 initialization function for ICL's program argument evaluation framework
ICLUtils_API void icl::utils::pa_show ()
 shows all given program arguments
ICLUtils_API void icl::utils::pa_set_license (const std::string &newLicenseText)
 Sets a license text, that is used when applications are run with --version or -v.
ICLUtils_API void icl::utils::pa_set_help_text (const std::string &newHelpText)
 Sets a applications help text that is used when applications are run with --help or with unknown arguments.
ICLUtils_API std::string icl::utils::pa_get_license ()
 returns the current license text
ICLUtils_API std::string icl::utils::pa_get_help_text ()
 returns the current help text (which is empty, if it was not set)

Function Documentation

bool icl::utils::operator&& ( const ProgArg &  a,
const ProgArg &  b 
) [inline]

this allows to check if two progargs are defined

this allows you to write:

        if(pa("-size") && pa("-scale")){
          ...
        }
bool icl::utils::operator&& ( const ProgArg &  a,
bool  b 
) [inline]

allows to check more than two ProgArg instances at once

Example:

        if(pa("-size") && pa("-scale") && pa("-format")){ ... }
bool icl::utils::operator&& ( bool &  b,
const ProgArg &  a 
) [inline]

allows to check more than two ProgArg instances at once

Example:

        if(pa("-size") && pa("-scale") && pa("-format")){ ... }
bool icl::utils::operator|| ( const ProgArg &  a,
const ProgArg &  b 
) [inline]

this allows to check if either of two progargs are defined

this allows you to write:

        if(pa("-size") || pa("-scale")){
          ...
        }
bool icl::utils::operator|| ( const ProgArg &  a,
bool  b 
) [inline]

allows to check if either of more than two ProgArg instances is defined

Example:

        if(pa("-size") || pa("-scale") || pa("-format")){ ... }
bool icl::utils::operator|| ( bool &  b,
const ProgArg &  a 
) [inline]

allows to check if either of more than two ProgArg instances is defined

Example:

        if(pa("-size") || pa("-scale") || pa("-format")){ ... }
const ProgArg icl::utils::pa ( const std::string &  id,
unsigned int  subargidx = 0 
) throw (ProgArgException) [inline]

returns given program argument

The pa-function is the main interface for extracting information about given program arguments and/or their default values at run-time.

The returned icl::utils::ProgArg instance is always automatically parsed from its internal string representation into the expressions lvalue-type (this can easily be implemented with a templated version of the implicit cast operator of a class). Here are some examples:

        pa_init(n,ppc,"-size|-s(Size=VGA) -index(int) -files(...)");
        
        // extract the first sub-argument of argument 
        // '-index' and convert it into an int value
        int i = pa("-index"); 
  
        // extract the first sub-argument of argument '-size'
        // if '-s' is the shortcut for '-size'
        Size s = pa("-s"); 
  
        // extract the 2nd sub-argument of argument '-input'
        int = pa("-input",1); 
        
        // check if argument -size was actually given
        if(pa("-size")){ ... }
        
        // read a list of files from the arbitrary sub-argument
        // arg '-files'. Note: it is not recommended to use 
        // pa("-files") within a loop, as internally the argument hash-
        // map must always be searched
        int nFiles = pa("-files").n();
        for(int i=0;i<nFiles;++i){
           std::cout << "file " << i << " " << pa("-files",i) << std::endl;
        }

        // alternatively, the "-files" prog-arg can be extracted
        ProgArg f = pa("-files");
        for(int i=0;i<f.n();++i){
           std::cout << "file " << i << " " << f[i] << std::endl;
        }
  
        // list all given arguments and subarguments
        std::cout << "all arguments " << std::endl;
        for(unsigned int i=0;i<pa_get_count(false);++i){
          std::cout << pa(i,false) << std::endl;
        }
  
        // in case of having dangling arguments allowed in 
        // painit-call: list all dangling arguments
        std::cout << "all dangling arguments " << std::endl;
        for(unsigned int i=0;i<pa_get_count();++i){
          std::cout << pa(i) << std::endl;
        }
  
        // using ProgArg instances as std::strings is sometimes
        // a bit complicated as conversion to std::string is
        // sometimes ambiguous 
        struct Test{
           Test(int i){...}
           Test(const std::string &s){ .. }
        };
        ...
        Test t(pa("-x")); // ambiguous -> int | std::string
        Test t((std::string)pa("-x")); // also ambiguous 
        // due to different available std::string constructors
        
        Test t(pa("-x").as<std::string>()); // works, but long 
        
        Test t(*pa("-x")); // much shorter, but only for using
        // a program argument as std::string
See also:
icl::utils::pa_init(int,char**,const std::string&,bool)
const ProgArg icl::utils::pa ( unsigned int  idx,
bool  danglingOnly = true 
) [inline]

returns given program argument at given index

See also:
icl::utils::pa(const std::string&,unsigned int)
template<class T >
const T icl::utils::pa_def ( const std::string &  id,
unsigned int  subargidx,
const T &  def 
) throw (ProgArgException) [inline]

utility function that allows to use a default value, if given argument was not defined

template<class T >
const T icl::utils::pa_def ( const std::string &  id,
const T &  def 
) throw (ProgArgException) [inline]

utility function that allows to use a default value, if given argument was not defined

PAEX icl::utils::pa_explain ( const std::string &  pa,
const std::string &  ex 
) [inline]

This function can be used to provide additional information for certain program arguments.

Due to the use of a special but hidden utility structure called icl::PAEX, this function can be called in a 'stacked' manner. This mean, that the function can be called several times without repeating the function name. Example:

        paex("-size","defines the input image size")
            ("-input","defines input device id and parameters")
            ("-format","define input image format");
See also:
icl::utils::pa(const std::string&,unsigned int)
ICLUtils_API unsigned int icl::utils::pa_get_count ( bool  danglingOnly = true)

returns number of actually given args given

See also:
icl::utils::pa(const std::string&,unsigned int)

returns the current help text (which is empty, if it was not set)

returns the current license text

ICLUtils_API void icl::utils::pa_init ( int  n,
char **  ppc,
const std::string &  init,
bool  allowDanglingArgs = false 
)

initialization function for ICL's program argument evaluation framework

painit always receives your program's main-functions arguments as n and ppc. The actual definition of the underlying program argument evaluation framework is given by the init- argument.
The following rules define the syntax for the init-string:

  • The init string consists of space-separated tokens of single program argument definitions. Necessary space-characters within these tokens must be escaped using a back-slash character.
  • Each single argument definition token consists of a pipe-separated list of argument name alternatives (e.g. -size|-s followed by an optional parameter list in round braces.
  • Each argument is allowed to have 0, N or unlimited sub-arguments.
  • If the argument has no sub arguments it is a flag, which implicitly has the value true if it was given and false otherwise. Zero sub- arguments can be forced by using no parameter list, i.e., no round braces, an empty parameter list () or a parameter list with a zero argument count (0).
  • An arbitrary sub-argument count can be reached by using the special parameter list (...).
  • Otherwise, the parameter-list is a comma separated list of type, type=default-value, or argument-count tokens. Examples:
    • (int,int) defines two integer sub-arguments
    • (5) defines 5 sub-arguments with no type information
    • (float,2,int) defines 4 sub-arguments of type float, any, any and int
    • (int=4,Size=VGA) defines two sub-arguments of type int and Size with given default values 4 and VGA Note: if an int-type is used to define several arguments together, no defaults can be given. If you don't want to define the type, but only the default values, the special type string * should be used e.g., (*=foo,*=bar)

Furthermore, it is worth to mention, that the defined types are always just hints for the user. Internally all parameters are treated as strings.

Here are some further complete example calls for painit.

        int main(int n, char **ppc){
          icl::utils::pa_init(n,ppc,"-size|-s(Size=VGA) -format|-f(format-string)");
        }
        int main(int n, char **ppc){
          icl::utils::pa_init(n,ppc,"-input|-i(device-type=dc,device-params=0)");
        }

Arguments

Sometimes, certain arguments shall be used directly without defining arguments and sub-arguments. E.g. if you have a converter application that gets an input and an output file only (e.g., program call: myConvert image.ppm converted-image.ppm rather than something like myConvert -i image.ppm -o converted-image.ppm). Dangling arguments are these arguments that do not match defined arguments or sub-arguments of these. Usually, given arguments that do not match primary arguments or sub-arguments lead to a ProgArgException. You can explicitly allow these dangling arguments by setting allowDanglingArgs to 'true'.
Dangling arguments can then be obtained simply using the functions icl::utils::pa_get_count and icl::utils::pa(unsigned int,bool).

To list all dangling arguments, the followed code can be used:

        for(unsigned int i=0;i<icl::utils::pa_get_count();++i){
          std::cout << icl::utils::pa(i) << std::endl;
        }

and Mandatory Arguments

As default, all arguments are optional. If you want to define an argument to be mandatory, simply prepend a '[m]'-prefix to the argument name alternative list. Example:

        // -size and -format are optional; -input or -i is mandatory
        icl::utils::pa_init(n,ppc,"-size(Size=VGA) -format(format=RGB) "
                    "[m]-input|-i(string,string)");

If mandatory arguments are not actually given to the program, a ProgArgException is thrown. As it does not make sense to define default values for mandatory arguments, a ProgArgException is thrown in this case as well. Furthermore, mandatory arguments must have sub-arguments (which is also sensible if you think about it).

ICLUtils_API void icl::utils::pa_set_help_text ( const std::string &  newHelpText)

Sets a applications help text that is used when applications are run with --help or with unknown arguments.

pasethelp has to be called before painit is called.

ICLUtils_API void icl::utils::pa_set_license ( const std::string &  newLicenseText)

Sets a license text, that is used when applications are run with --version or -v.

pasetlic has to be called before painit is called. Otherwise, only the default licese text is shown.

shows all given program arguments

ICLUtils_API void icl::utils::pa_show_usage ( const std::string &  msg = "")

shows current available programm arguments

 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines