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