AppConfig::File - phpMan

NAME
    AppConfig::File - Perl5 module for reading configuration files.

SYNOPSIS
        use AppConfig::File;

        my $state   = AppConfig::State->new(\%cfg1);
        my $cfgfile = AppConfig::File->new($state, $file);

        $cfgfile->parse($file);            # read config file

OVERVIEW
    AppConfig::File is a Perl5 module which reads configuration files and
    use the contents therein to update variable values in an
    AppConfig::State object.

    AppConfig::File is distributed as part of the AppConfig bundle.

DESCRIPTION
  USING THE AppConfig::File MODULE
    To import and use the AppConfig::File module the following line should
    appear in your Perl script:

        use AppConfig::File;

    AppConfig::File is used automatically if you use the AppConfig module
    and create an AppConfig::File object through the file() method.

    AppConfig::File is implemented using object-oriented methods. A new
    AppConfig::File object is created and initialised using the
    AppConfig::File->new() method. This returns a reference to a new
    AppConfig::File object. A reference to an AppConfig::State object should
    be passed in as the first parameter:

        my $state   = AppConfig::State->new();
        my $cfgfile = AppConfig::File->new($state);

    This will create and return a reference to a new AppConfig::File object.

  READING CONFIGURATION FILES
    The "parse()" method is used to read a configuration file and have the
    contents update the STATE accordingly.

        $cfgfile->parse($file);

    Multiple files maye be specified and will be read in turn.

        $cfgfile->parse($file1, $file2, $file3);

    The method will return an undef value if it encounters any errors
    opening the files. It will return immediately without processing any
    further files. By default, the PEDANTIC option in the AppConfig::State
    object, $self->{ STATE }, is turned off and any parsing errors (invalid
    variables, unvalidated values, etc) will generated warnings, but not
    cause the method to return. Having processed all files, the method will
    return 1 if all files were processed without warning or 0 if one or more
    warnings were raised. When the PEDANTIC option is turned on, the method
    generates a warning and immediately returns a value of 0 as soon as it
    encounters any parsing error.

    Variables values in the configuration files may be expanded depending on
    the value of their EXPAND option, as determined from the App::State
    object. See AppConfig::State for more information on variable expansion.

  CONFIGURATION FILE FORMAT
    A configuration file may contain blank lines and comments which are
    ignored. Comments begin with a '#' as the first character on a line or
    following one or more whitespace tokens, and continue to the end of the
    line.

        # this is a comment
        foo = bar               # so is this
        url = index.html#hello  # this too, but not the '#welcome'

    Notice how the '#welcome' part of the URL is not treated as a comment
    because a whitespace character doesn't precede it.

    Long lines can be continued onto the next line by ending the first line
    with a '\'.

        callsign = alpha bravo camel delta echo foxtrot golf hipowls \
                   india juliet kilo llama mike november oscar papa  \
                   quebec romeo sierra tango umbrella victor whiskey \
                   x-ray yankee zebra

    Variables that are simple flags and do not expect an argument (ARGCOUNT
    = ARGCOUNT_NONE) can be specified without any value. They will be set
    with the value 1, with any value explicitly specified (except "0" and
    "off") being ignored. The variable may also be specified with a "no"
    prefix to implicitly set the variable to 0.

        verbose                              # on  (1)
        verbose = 1                          # on  (1)
        verbose = 0                          # off (0)
        verbose off                          # off (0)
        verbose on                           # on  (1)
        verbose mumble                       # on  (1)
        noverbose                            # off (0)

    Variables that expect an argument (ARGCOUNT = ARGCOUNT_ONE) will be set
    to whatever follows the variable name, up to the end of the current
    line. An equals sign may be inserted between the variable and value for
    clarity.

        room = /home/kitchen
        room   /home/bedroom

    Each subsequent re-definition of the variable value overwrites the
    previous value.

        print $config->room();               # prints "/home/bedroom"

    Variables may be defined to accept multiple values (ARGCOUNT =
    ARGCOUNT_LIST). Each subsequent definition of the variable adds the
    value to the list of previously set values for the variable.

        drink = coffee
        drink = tea

    A reference to a list of values is returned when the variable is
    requested.

        my $beverages = $config->drinks();
        print join(", ", @$beverages);      # prints "coffee, tea"

    Variables may also be defined as hash lists (ARGCOUNT = ARGCOUNT_HASH).
    Each subsequent definition creates a new key and value in the hash
    array.

        alias l="ls -CF"
        alias h="history"

    A reference to the hash is returned when the variable is requested.

        my $aliases = $config->alias();
        foreach my $k (keys %$aliases) {
            print "$k => $aliases->{ $k }\n";
        }

    A large chunk of text can be defined using Perl's "heredoc" quoting
    style.

       scalar = <<BOUNDARY_STRING
       line 1
       line 2: Space/linebreaks within a HERE document are kept.
       line 3: The last linebreak (\n) is stripped.
       BOUNDARY_STRING

       hash   key1 = <<'FOO'
         * Quotes (['"]) around the boundary string are simply ignored.
         * Whether the variables in HERE document are expanded depends on
           the EXPAND option of the variable or global setting.
       FOO

       hash = key2 = <<"_bar_"
       Text within HERE document are kept as is.
       # comments are treated as a normal text.
       The same applies to line continuation. \
       _bar_

    Note that you cannot use HERE document as a key in a hash or a name of a
    variable.

    The '-' prefix can be used to reset a variable to its default value and
    the '+' prefix can be used to set it to 1

        -verbose
        +debug

    Variable, environment variable and tilde (home directory) expansions
    Variable values may contain references to other AppConfig variables,
    environment variables and/or users' home directories. These will be
    expanded depending on the EXPAND value for each variable or the GLOBAL
    EXPAND value.

    Three different expansion types may be applied:

        bin = ~/bin          # expand '~' to home dir if EXPAND_UID
        tmp = ~abw/tmp       # as above, but home dir for user 'abw'

        perl = $bin/perl     # expand value of 'bin' variable if EXPAND_VAR
        ripl = $(bin)/ripl   # as above with explicit parens

        home = ${HOME}       # expand HOME environment var if EXPAND_ENV

    See AppConfig::State for more information on expanding variable values.

    The configuration files may have variables arranged in blocks. A block
    header, consisting of the block name in square brackets, introduces a
    configuration block. The block name and an underscore are then prefixed
    to the names of all variables subsequently referenced in that block. The
    block continues until the next block definition or to the end of the
    current file.

        [block1]
        foo = 10             # block1_foo = 10

        [block2]
        foo = 20             # block2_foo = 20

AUTHOR
    Andy Wardley, <abw AT wardley.org>

COPYRIGHT
    Copyright (C) 1997-2007 Andy Wardley. All Rights Reserved.

    This module is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

SEE ALSO
    AppConfig, AppConfig::State