SCAN_OPTION 3.02

[Back] [Japanese Page]

NAME

scan_option - Routine to analyze command-line option

SYNOPSIS

#include <option.h>
int scan_option(int argc, char *argv[], char *key, ...);
argc - the number of command-line arguments
argv - command-line arguments
key, ... - key string and multi-variable arguments

DESCRIPTION

• If there is the key string to scan in command-line options, true is returned. For an example, if there is "-help" in command-line options,

scan_option(argc, argv, "-help")

returns true.
• If there is the key string to scan with scanf-style format, variables are set by scanf style and true is returned. For an example, if there is "-geom 100x100" in command-line options,

scan_option(argc, argv, "-geom %dx%d", &width, &height)

sets 100 and 100 to width and height, respectively, and returns true.
• If there is the key string to scan with scanf-style format of "%s", a variable is set at the next string of the argument matched to key and returns true. For an example, if there is "-title A string" in command-line options and "A string" is one element in the command-line arguments,

scan_option(argc, argv, "-title %s", title)

sets "A string" to title and returns true.
• If there is the key string to scan with scanf-style format of "\"%s\"", a variable is set at the next double-quoted strings of the argument matched to key and returns true. For an example, if there is '-title \"A string\"' in command-line options and whether "A string" is one element or not,

scan_option(argc, argv, "-title \"%s\"", title)

sets "A string" to title and returns true. If there is no double-quoted string at the previous argument of the matched key, it processes the same as "-title %s" does.
• If the key string is such as "-on[-]", it is considered to be flag-type option and multi-variable arguments need a int-type pointer. For an example, if there is "-on" or "-on-" in command-line options,

scan_option(argc, argv, "-on[-]", &flag)

substitutes !0 or 0 into flag and returns true.
• In addition, if the key string is such as "[-+]mode" or "[+-]mode", it is also considered to be flag-type option and multi-variable arguments need a int-type pointer. For an example, if there is "-mode" or "+mode" in command-line options,

scan_option(argc, argv, "[-+]mode", &flag)

substitutes !0 or 0 into flag and returns true. On the other hand, if there is "+mode" or "-mode" in command-line options,

scan_option(argc, argv, "[+-]mode", &flag)

substitutes !0 or 0 into flag and returns true.
• If the key string is such as "-color Red Green Blue" which includes some blanks without scanf-style format, it is considered to be enumerate-type option and multi-variable arguments need a int-type pointer. For an example, there is "-color Blue" in command-line options,

scan_option(argc, argv, "-color Red Green Blue", &color)

substitutes 2 into color and returns true.
• If the key string is such as "-plot None|Line|Dot|Point" which includes some "|"s without scanf-style format, it is considered to be bit-mask-type option and multi-variable arguments need a 'unsigned long'-type pointer. For an example, there is "-plot Line|Point" in command-line options,

scan_option(argc, argv, "-plot None|Line|Dot|Point", &plot)

substitutes (1L<<0|1L<<2) into plot and returns true.
• If the key string is such as "-v %lf,.." which includes one type descriptor and the string ",...", it is considered to be arbitrary-length vector option and multi-variable arguments need a pointer of an array of given type. For an example, there is "-v 0.1,1,10" in command-line options,

scan_option(argc, argv, "-v %lf,..", &v, &nl,&nh)

allocates a double-type array of the region [0..2(=nh)] with v=NULL and nl=0, and sets values to the variables according to command-line arguments, and substitutes the address of the array into v, and returns true. In this case that v=NULL it allocates memory of vector according to command-line arguments and sets the upper index to nh, otherwise, in the case that v!=NULL it sets values to the region restricted to [nl..nh] of the vector v.
• If the key string is such as "-m (%lf,..),.." which includes one type descriptor and the strings "(",",...","),.."",...", it is considered to be arbitrary-size matrix option and multi-variable arguments need a pointer of an 2-dimensional array of given type. For an example, there is "-m (0.1,1,10),(0.2,2,20),(0.3,3,30)" in command-line options,

scan_option(argc, argv, "-m (%lf,..),..", &m, &nrl,&nrh, &ncl,&nch)

allocates a double-type and 2-dimensional array of the region [0..2(=nrh)][0..2(=nch)] with m=NULL and nrl=ncl=0, and sets values to the variables according to command-line arguments, and substitutes the address of the array into m, and returns true. In this case that m=NULL it allocates memory of matrix according to command-line arguments and sets the upper indices to nrh and nch, otherwise, in the case that m!=NULL it sets values to the region restricted to [nrl..nrh][ncl..nch] of the matrix m.
• In addition to a returned value of scan_option, the above true value is, to put it more precisely, the index of argument matched to key string. To use this specification, for an example, the following usage is available.

 
if ((c=scan_option(argc, argv, "-f")) {
  c++; n = 0;
  while (c<argc)
    strcpy(files[n++], argv[c++]);
}

Author

Taiji Yamada <taiji@aihara.co.jp>