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)

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 ;