Using AppConfig in 10 minutes

This is a short HOWTO for the AppConfig module. It assumes some knowledge of how to use Perl modules.

What it is
AppConfig is a Perl module that allows you to manage a program's configuration in a simple way, with both configuration files and command line options.

AppConfig configurations support scalar variables, arrays and hashes, which naturally translate into Perl variables. …How to use it
First, you need to "use" the module. I recommend to use the "expand" and "argcount" options. Their functionalities are explained below.

use AppConfig qw(:expand :argcount);

You can now create AppConfig objects. I usually use the following options to the new() method:

CASE     => 1,
PEDANTIC => 1,
GLOBAL   => {
		ARGCOUNT => ARGCOUNT_ONE,
		EXPAND   => EXPAND_VAR,
},

  • CASE means that the variable names are case-sensitive
  • PEDANTIC means that parsing errors throw an exception
  • GLOBAL defines defaults for all variables; in this specific case:
    • ARGCOUNT => ARGCOUNT_ONE means that you can assign only a value to the variable (that is: it maps to a Perl scalar)
    • EXPAND => EXPAND_VAR means that in the configuration file you can refer to an already defined variable (e.g.: var2 = $var1

    [/LIST]
    Should any variable have any default value, set it right after creating the object, like this:

    $conf->define(q{encoding},  { DEFAULT => q{utf-8}     }) ;
    $conf->define(q{outfile},   { DEFAULT => q{query.xml} }) ;
    $conf->define(q{querydata}, { DEFAULT => q{query.xml} }) ;

    Then, I usually parse the command line arguments using the args() method. Done that, I import the information from the configuration file with the file() method. I usually provide the configuration file name on the command line (-config command line option in the example). Then, I parse the command line again, so that I can override variables set in the file. This three-step process allows me to solve the chicken-and-egg problem of the configuration file name.

    # Keep a copy to reprocess command-line arguments. This will allow
    # you to take advantage of the -config option, while keeping a chance
    # to override configuration file directives with command-line options
    my $command_line_args = [ @ARGV ] ;
    $conf->args() ;
    
    if (not $conf->get('config')) {
      # config parameter is mandatory
      croak qq{Undefined mandatory parameter "config"} ;
    }
    
    $conf->file($conf->get('config')) ;
    
    # Now reprocess command line and override defaults set in the
    # configuration files
    $conf->args($command_line_args) ;
    

    That's all there is to it: you can now get the variable values with $conf->get(q{variabile})

    expand
    The manual page says it all

           :expand
               The ’:expand’ tagset defines the following constants:
    
                   EXPAND_NONE
                   EXPAND_VAR
                   EXPAND_UID
                   EXPAND_ENV
                   EXPAND_ALL       # EXPAND_VAR │ EXPAND_UID │ EXPAND_ENV
                   EXPAND_WARN
    
               See AppConfig::File for full details of the use of these constants.
    
           EXPAND
               The EXPAND option specifies how the AppConfig::File processor
               should expand embedded variables in the configuration file values
               it reads.  By default, EXPAND is turned off (EXPAND_NONE) and no
               expansion is made.
    
               The EXPAND_* constants can be imported from the AppConfig module:
    
                   use AppConfig ’:expand’;
    
                   $state->define(’foo’, { EXPAND => EXPAND_VAR });
    
               or can be accessed directly from the AppConfig package:
    
                   use AppConfig;
    
                   $state->define(’foo’, { EXPAND => AppConfig::EXPAND_VAR });
    
               The following values for EXPAND may be specified.  Multiple values
               should be combined with vertical bars , ’│’, e.g. "EXPAND_UID │
               EXPAND_VAR").
    
               EXPAND_NONE
                   Indicates that no variable expansion should be attempted.
    
               EXPAND_VAR
                   Indicates that variables embedded as $var or $(var) should be
                   expanded to the values of the relevant AppConfig::State vari‐
                   ables.
    
               EXPAND_UID
                   Indicates that ’~’ or ’~uid’ patterns in the string should be
                   expanded to the current users ($<), or specified user’s home
                   directory.
    
               EXPAND_ENV
                   Inidicates that variables embedded as ${var} should be expanded
                   to the value of the relevant environment variable.
    
               EXPAND_ALL
                   Equivalent to "EXPAND_VARS │ EXPAND_UIDS │ EXPAND_ENVS").
    
               EXPAND_WARN
                   Indicates that embedded variables that are not defined should
                   raise a warning.  If PEDANTIC is set, this will cause the
                   read() method to return 0 immediately.

    argcount

           :argcount
               The ’:argcount’ tagset defines the following constants:
    
                   ARGCOUNT_NONE
                   ARGCOUNT_ONE
                   ARGCOUNT_LIST
                   ARGCOUNT_HASH
    
               See AppConfig::State for full details of the use of these con‐
               stants.
           ARGCOUNT
               The ARGCOUNT option specifies the number of arguments that should
               be supplied for this variable.  By default, no additional arguments
               are expected for variables (ARGCOUNT_NONE).
    
               The ARGCOUNT_* constants can be imported from the AppConfig module:
    
                   use AppConfig ’:argcount’;
    
                   $state->define(’foo’, { ARGCOUNT => ARGCOUNT_ONE });
    
               or can be accessed directly from the AppConfig package:
    
                   use AppConfig;
    
                   $state->define(’foo’, { ARGCOUNT => AppConfig::ARGCOUNT_ONE });
    
               The following values for ARGCOUNT may be specified.
    
               ARGCOUNT_NONE (0)
                   Indicates that no additional arguments are expected.  If the
                   variable is identified in a confirguration file or in the com‐
                   mand line arguments, it is set to a value of 1 regardless of
                   whatever arguments follow it.
    
               ARGCOUNT_ONE (1)
                   Indicates that the variable expects a single argument to be
                   provided.  The variable value will be overwritten with a new
                   value each time it is encountered.
    
               ARGCOUNT_LIST (2)
                   Indicates that the variable expects multiple arguments.  The
                   variable value will be appended to the list of previous values
                   each time it is encountered.
    
               ARGCOUNT_HASH (3)
                   Indicates that the variable expects multiple arguments and that
                   each argument is of the form "key=value".  The argument will be
                   split into a key/value pair and inserted into the hash of val‐
                   ues each time it is encountered.

    Full example

    use AppConfig qw(:expand :argcount);
    
    ### CONFIGURATION ######################################################
    my @config_vars = qw{
    		     config
    
    		     user        password    server      SID
    		     queryfile   report_name country     encoding
    		     outfile     port
    
    		     envelope_sender sender          recipient
    		     stylesheet      querydata       subject_stylesheet
    		   } ;
    my $conf =
      AppConfig->new({
    		  CASE     => 1,
    		  PEDANTIC => 1,
    		  GLOBAL   => {
    			       ARGCOUNT => ARGCOUNT_ONE,
    			       EXPAND   => EXPAND_VAR,
    			      },
    		 },
    		 @config_vars
    		) ;
    
    $conf->define(q{encoding},  { DEFAULT => q{utf-8}     }) ;
    $conf->define(q{outfile},   { DEFAULT => q{query.xml} }) ;
    $conf->define(q{querydata}, { DEFAULT => q{query.xml} }) ;
    
    
    # Keep a copy to reprocess command-line arguments. This will allow
    # you to take advantage of the -config option, while keeping a chance
    # to override configuration file directives with command-line options
    my $command_line_args = [ @ARGV ] ;
    $conf->args() ;
    
    if (not $conf->get('config')) {
      # config parameter is mandatory
      croak qq{Undefined mandatory parameter "config"} ;
    }
    
    $conf->file($conf->get('config')) ;
    
    # Now reprocess command line and override defaults set in the
    # configuration files
    $conf->args($command_line_args) ;
    
    
    my %config = map { $_ => $conf->get($_) } @config_vars ;
    
    Advertisements

    Leave a Reply

    Fill in your details below or click an icon to log in:

    WordPress.com Logo

    You are commenting using your WordPress.com account. Log Out / Change )

    Twitter picture

    You are commenting using your Twitter account. Log Out / Change )

    Facebook photo

    You are commenting using your Facebook account. Log Out / Change )

    Google+ photo

    You are commenting using your Google+ account. Log Out / Change )

    Connecting to %s