NAME

App::Options - combine command line options, environment vars, and option file values

SYNOPSIS

    #!/usr/local/bin/perl

    BEGIN {
        use App::Options;
        App::Options->init();  # reads into %App::options by default
    }

    print "Options:\n";
    foreach $var (sort keys %App::options) {
        printf "    %-20s => [%s]\n", $var, $App::options{$var};
    }

  or a more full-featured example...

    #!/usr/local/bin/perl

    BEGIN {
        use App::Options;
        App::Options->init(
            values => \%MyPackage::some_hash,
            options => [ "option_file", "prefix", "app", "app_path_info",
                        "perlinc", "debug_options", "import", ],
            option => {
                option_file   => "~/.app/app.conf",         # set default
                app           => "default=app;type=string", # default & type
                app_path_info => {default=>"",type=>"string"}, # as a hashref
                prefix        => "type=string;required",
                perlinc       => undef,         # no default
                debug_options => "type=integer",
                import        => "type=string",
                flush_imports => 1,
            },
            no_cmd_args => 1,
            no_env_vars => 1,
            no_option_file => 1,
            print_usage => sub { my ($values, $init_options) = @_; print "Use it right!\n"; },
        );
    }

    print "Options:\n";
    foreach $var (sort keys %MyPackage::some_hash) {
        printf "    %-20s => [%s]\n", $var, $MyPkg::my_hash{$var};
    }

DESCRIPTION

App::Options combines command-line arguments, environment variables, option files, and program defaults to produce a hash of option values.

All of this may be done within the BEGIN block so that the @INC variable can be modified in time to affect "use" statements within the regular code. This is particularly important to support the installation of multiple versions of a Perl application on the same physical computer.

App::Options supports the P5EE/App-Context variant of the Perl 5 Enterprise Environment. See the P5EE web sites for more information.

    http://www.officevision.com/pub/p5ee
    http://p5ee.perl.org

App::Options is in its own distribution because it will be very stable and can be installed in the default perl places on the system. This is different than the App-Context, App-Repository, and App-Widget distributions which are expected to evolve significantly.

A developer writing an application based on the P5EE/App-Context framework will want to install App-Options in the default perl places. The other distributions will be installed in release-specific locations.

Methods

init()

    * Signature: App::Options->init();
    * Signature: App::Options->init(%named);
    * Signature: App::Options->init($myvalues);
    * Signature: App::Options->init($myvalues, %named);
    * Param:  $myvalues     HASH
    * Param:  values        HASH
    * Return: void
    * Throws: <none>
    * Since:  0.01

    Sample Usage: 

    BEGIN {
        use App::Options;
        App::Options->init();
    }

    ... or, to use every option available ...

    BEGIN {
        use App::Options;
        App::Options->init(
            values => \%MyPackage::options,
            options => [ "option_file", "prefix", "app", "app_path_info",
                         "perlinc", "debug_options", "import", ],
            option => {
                option_file   => "~/.app/app.conf",         # set default
                app           => "default=app;type=string", # default & type
                app_path_info => {default=>"",type=>"string"}, # as a hashref
                prefix        => "type=string;required",
                perlinc       => undef,         # no default
                debug_options => "type=int",
                import        => "type=string",
                flush_imports => 1,
            },
            no_cmd_args => 1,
            no_env_vars => 1,
            no_option_file => 1,
            print_usage => sub { my ($values, $init_options) = @_; print "Use it right!\n"; },
        );
    }

The init() method reads the command line args (@ARGV), finds an options file, and loads it, all in a way which can be done in a BEGIN block. This is important to be able to modify the @INC array so that normal "use" and "require" statements will work with the configured @INC path.

The various named parameters of the init() method are as follows.

    values - specify a hash reference other than %App::options to
        put configuration values in.
    options - specify a limited, ordered list of options to be
        displayed when the "--help" or "-?" options are invoked
    option - specify optional additional information about any of
        the various options to the program (see below)
    no_cmd_args - do not process command line arguments
    no_env_vars - do not read environment variables
    no_option_file - do not read in the option file
    print_usage - provide an alternate print_usage() function

The additional information that can be specified about any individual option variable is as follows.

    default - the default variable if none supplied on the command
        line, in an environment variable, or in an option file
    required - the program will not run unless a value is provided
        for this option
    type - if a value is provided, the program will not run unless
        the value matches the type ("string", "integer", "float",
        "boolean", "date", "time", "datetime", regexp).
    description - printed next to the option in the "usage" page

The init() method stores command line options and option file values all in the global %App::options hash (unless the "values" argument specifies another reference to a hash to use). The special keys to this resulting hash are as follows.

    option_file - specifies the exact file name of the option file useful
       for command line usage (i.e. "app --option_file=/path/to/app.conf")
       "option_file" is automatically set with the option file that it found
       if it is not supplied at the outset as an argument.

    app - specifies the tag that will be used when searching for
       a option file. (i.e. "app --app=myapp" will search for "myapp.conf"
       before it searches for "app.conf")
       "app" is automatically set with the stem of the program file that 
       was run (or the first part of PATH_INFO) if it is not supplied at
       the outset as an argument.

    app_path_info - this is the remainder of PATH_INFO after the first
       part is taken off to make the app.

    prefix - This represents the base directory of the software
       installation (i.e. "/usr/myproduct/1.3.12").  If it is not
       set explicitly, it is detected from the following places:
          1. PREFIX environment variable
          2. the real path of the program with /bin or /cgi-bin stripped
          3. the current directory
       If it is autodetected from one of those three places, that is
       only provisional, in order to find the "option_file".  The "prefix"
       variable should be set authoritatively in the "option_file" if it
       is desired to be in the $values structure.

    perlinc - a path of directories to prepend to the @INC search path.
       This list of directories is separated by any combination of
       [,; ] characters.

    debug_options - if this is set, a variety of debug information is
       printed out during the option processing.  This helps in debugging
       which option files are being used and what the resulting variable
       values are.

    import - a list of additional option files to be processed

ACKNOWLEDGEMENTS

 * Author:  Stephen Adkins <stephen.adkins@officevision.com>
 * License: This is free software. It is licensed under the same terms as Perl itself.

SEE ALSO