PROCESS_OPTIONS(OC )

Shore Programmer's Manual - 3 November 94

NAME

SYNOPSIS

#include <ShoreApp.h>

main( int argc, char **argv,...)
{
    ...

    char *program_name = argv[0];

    //
    // minimal required options handling ...
    // but don't do this if your program is called a.out
    //
    // The SH_DO macro (defined in Shore.h) checks return codes
    //
	SH_DO(Shore::init(program_name, ".rcfile"));

    // rest of main()
    ... 
}

//
// OR... 
// less simple but a little bit more flexible...
//

shrc	my_options(option_group_t *o); 

main( int argc, ...)
{
    ...

    // next-to-minimal required options handling :
    // this allows the application to add its
    // own options, to specify options class,
    // program name, name of file of commands, etc.

    char	*usage_string = "usage: how-to-use-this-command";
    shrc	rc;	// return code
    option_group_t *options;

    rc = Shore::process_options(
	    // type is "shore"
	    "client",	// class of options
	    argv[0],	// program name 
	    		// - does not have to be argv[0]
	    ".rcfile",	// file to search-- can be null
	    usage, 	// string to print if error
	    my_options, // optional - can be 0
	    &options);  // return value returned here

    if(rc){
         cerr << "Cannot process options:" << rc << endl;
         exit (1);
    }

	SH_DO(Shore::init(program_name));

    // rest of main()
    ... 
}

DESCRIPTION

NB: Your application must be called by a name that does not include a period if you wish to set any options with a file with the 4-part command names. For example, a.out does not work with the 4-part command names but it does work with the wild-card command:

*.option: value

If you want your application to add its own options, to specify the program class or program name for options, or to read a configuration file other than that determined by $SHORE_RC, you can have your main() call the function process_options , which calls the lower layers of Shore to establish default values for all the options that have defaults, and looks in a file for values for those options. It also allows your program to create options before the command line and the file are searched.

Each Shore option has a name; its name is composed of four parts:

type.class.program.option

When a file or command line is searched for option values, the options are identified by their full 4-part names or by pattern-matching expressions that include wild cards ('*' and '?').

For example, to set the option shore.oo7.bench.configfile to the value ./script in the program bench, the function main() in bench calls

    ... Shore::process_options("oo7", argv[0], ".oo7rc", usage_string,
        oo7_options, &options)

shore.oo7.bench.configfile:./script

?.oo7.bench.configfile:./script

shore.oo7.?.configfile:./script

*.configfile:./script

The bench program also has to add the option configfile to the list of options used by the lower layers of Shore. This is done by providing a non-null fifth argument to process_options. Benchdoes this with its function oo7_options, which looks like this:

shrc oo7_options(option_group_t *options)
{
    static option_t    *configfile_opt;
    shrc    e =
    options->add_option(
        "configfile",  // 4th part of option name
        "string",      // description of syntax of value
        "-",           // default value
        "name of configuration file", // meaning of option
        false,         // Boolean: is it a mandatory option?
        option_t::set_value_charstr, 
                       // function to check the syntax of the value
        configfile_opt // return value - ptr to an option_t
                       // that describes this option
    );
    return e;
}
 

Finally, if you want even more control of the options processing, or if you want to take option values from the command line, you can use any of the functions from the options service, found in #include <option.h>.

BUGS

The function process_options should also look at the command line.

VERSION

SPONSORSHIP

COPYRIGHT