{
    "mode": "perldoc",
    "parameter": "AppConfig",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/AppConfig/json",
    "generated": "2026-06-09T16:08:07Z",
    "synopsis": "use AppConfig;\n# create a new AppConfig object\nmy $config = AppConfig->new( \\%cfg );\n# define a new variable\n$config->define( $varname => \\%varopts );\n# create/define combined\nmy $config = AppConfig->new( \\%cfg,\n$varname => \\%varopts,\n$varname => \\%varopts,\n...\n);\n# set/get the value\n$config->set( $varname, $value );\n$config->get($varname);\n# shortcut form\n$config->varname($value);\n$config->varname;\n# read configuration file\n$config->file($file);\n# parse command line options\n$config->args(\\@args);      # default to \\@ARGV\n# advanced command line options with Getopt::Long\n$config->getopt(\\@args);    # default to \\@ARGV\n# parse CGI parameters (GET method)\n$config->cgi($query);       # default to $ENV{ QUERYSTRING }",
    "sections": {
        "NAME": {
            "content": "AppConfig - Perl5 module for reading configuration files and parsing command line arguments.\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use AppConfig;\n\n# create a new AppConfig object\nmy $config = AppConfig->new( \\%cfg );\n\n# define a new variable\n$config->define( $varname => \\%varopts );\n\n# create/define combined\nmy $config = AppConfig->new( \\%cfg,\n$varname => \\%varopts,\n$varname => \\%varopts,\n...\n);\n\n# set/get the value\n$config->set( $varname, $value );\n$config->get($varname);\n\n# shortcut form\n$config->varname($value);\n$config->varname;\n\n# read configuration file\n$config->file($file);\n\n# parse command line options\n$config->args(\\@args);      # default to \\@ARGV\n\n# advanced command line options with Getopt::Long\n$config->getopt(\\@args);    # default to \\@ARGV\n\n# parse CGI parameters (GET method)\n$config->cgi($query);       # default to $ENV{ QUERYSTRING }\n",
            "subsections": []
        },
        "OVERVIEW": {
            "content": "AppConfig is a Perl5 module for managing application configuration information. It maintains the\nstate of any number of variables and provides methods for parsing configuration files, command\nline arguments and CGI script parameters.\n\nVariables values may be set via configuration files. Variables may be flags (On/Off), take a\nsingle value, or take multiple values stored as a list or hash. The number of arguments a\nvariable expects is determined by its configuration when defined.\n\n# flags\nverbose\nnohelp\ndebug = On\n\n# single value\nhome  = /home/abw/\n\n# multiple list value\nfile = /tmp/file1\nfile = /tmp/file2\n\n# multiple hash value\nbook  camel = Programming Perl\nbook  llama = Learning Perl\n\nThe '-' prefix can be used to reset a variable to its default value and the '+' prefix can be\nused to set it to 1\n",
            "subsections": [
                {
                    "name": "-verbose",
                    "content": "+debug\n\nVariable, environment variable and tilde (home directory) expansions can be applied\n(selectively, if necessary) to the values read from configuration files:\n\nhome = ~                    # home directory\nnntp = ${NNTPSERVER}        # environment variable\nhtml = $home/html           # internal variables\nimg  = $html/images\n\nConfiguration files may be arranged in blocks as per the style of Win32 \"INI\" files.\n\n[file]\nsite = kfs\nsrc  = ~/websrc/docs/$site\nlib  = ~/websrc/lib\ndest = ~/publichtml/$site\n\n[page]\nheader = $lib/header\nfooter = $lib/footer\n\nYou can also use Perl's \"heredoc\" syntax to define a large block of text in a configuration\nfile.\n\nmultiline = <<FOOBAR\nline 1\nline 2\nFOOBAR\n\npaths  exe  = \"${PATH}:${HOME}/.bin\"\npaths  link = <<'FOO'\n${LDLIBARRAYPATH}:${HOME}/lib\nFOO\n\nVariables may also be set by parsing command line arguments.\n\nmyapp -verbose -site kfs -file f1 -file f2\n\nAppConfig provides a simple method (args()) for parsing command line arguments. A second method\n(getopt()) allows more complex argument processing by delegation to Johan Vroman's Getopt::Long\nmodule.\n\nAppConfig also allows variables to be set by parameters passed to a CGI script via the URL (GET\nmethod).\n\nhttp://www.nowhere.com/cgi-bin/myapp?verbose&site=kfs\n"
                }
            ]
        },
        "PREREQUISITES": {
            "content": "AppConfig requires Perl 5.005 or later.\n\nThe Getopt::Long and Test::More modules should be installed. If you are using a recent version\nof Perl (e.g. 5.8.0) then these should already be installed.\n\nOBTAINING AND INSTALLING THE AppConfig MODULE BUNDLE\nThe AppConfig module bundle is available from CPAN. As the 'perlmod' manual page explains:\n\nCPAN stands for the Comprehensive Perl Archive Network.\nThis is a globally replicated collection of all known Perl\nmaterials, including hundreds of unbundled modules.\n\n[...]\n\nFor an up-to-date listing of CPAN sites, see\nhttp://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ .\n\nWithin the CPAN archive, AppConfig is in the category:\n\n12) Option, Argument, Parameter and Configuration File Processing\n\nThe module is available in the following directories:\n\n/modules/by-module/AppConfig/AppConfig-<version>.tar.gz\n/authors/id/ABW/AppConfig-<version>.tar.gz\n\nAppConfig is distributed as a single gzipped tar archive file:\n\nAppConfig-<version>.tar.gz\n\nNote that \"<version>\" represents the current AppConfig version number, of the form \"n.nn\", e.g.\n\"3.14\". See the REVISION section below to determine the current version number for AppConfig.\n\nUnpack the archive to create a AppConfig installation directory:\n\ngunzip AppConfig-<version>.tar.gz\ntar xvf AppConfig-<version>.tar\n\n'cd' into that directory, make, test and install the modules:\n\ncd AppConfig-<version>\nperl Makefile.PL\nmake\nmake test\nmake install\n\nThe 't' sub-directory contains a number of test scripts that are run when a 'make test' is run.\n\nThe 'make install' will install the module on your system. You may need administrator privileges\nto perform this task. If you install the module in a local directory (for example, by executing\n\"perl Makefile.PL LIB=~/lib\" in the above - see \"perldoc MakeMaker\" for full details), you will\nneed to ensure that the PERL5LIB environment variable is set to include the location, or add a\nline to your scripts explicitly naming the library location:\n\nuse lib '/local/path/to/lib';\n\nThe 'examples' sub-directory contains some simple examples of using the AppConfig modules.\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "USING THE AppConfig MODULE\nTo import and use the AppConfig module the following line should appear in your Perl script:\n\nuse AppConfig;\n\nTo import constants defined by the AppConfig module, specify the name of one or more of the\nconstant or tag sets as parameters to \"use\":\n\nuse AppConfig qw(:expand :argcount);\n\nSee \"CONSTANT DEFINITIONS\" below for more information on the constant tagsets defined by\nAppConfig.\n\nAppConfig is implemented using object-oriented methods. A new AppConfig object is created and\ninitialized using the new() method. This returns a reference to a new AppConfig object.\n\nmy $config = AppConfig->new();\n\nThis will create and return a reference to a new AppConfig object.\n\nIn doing so, the AppConfig object also creates an internal reference to an AppConfig::State\nobject in which to store variable state. All arguments passed into the AppConfig constructor are\npassed directly to the AppConfig::State constructor.\n\nThe first (optional) parameter may be a reference to a hash array containing configuration\ninformation.\n\nmy $config = AppConfig->new( {\nCASE   => 1,\nERROR  => \\&myerror,\nGLOBAL => {\nDEFAULT  => \"<unset>\",\nARGCOUNT => ARGCOUNTONE,\n},\n} );\n\nSee AppConfig::State for full details of the configuration options available. These are, in\nbrief:\n\nCASE\nUsed to set case sensitivity for variable names (default: off).\n\nCREATE\nUsed to indicate that undefined variables should be created automatically (default: off).\n\nGLOBAL\nReference to a hash array of global values used by default when defining variables. Valid\nglobal values are DEFAULT, ARGCOUNT, EXPAND, VALIDATE and ACTION.\n\nPEDANTIC\nUsed to indicate that command line and configuration file parsing routines should return\nimmediately on encountering an error.\n\nERROR\nUsed to provide a error handling routine. Arguments as per printf().\n\nSubsequent parameters may be variable definitions. These are passed to the define() method,\ndescribed below in \"DEFINING VARIABLES\".\n\nmy $config = AppConfig->new(\"foo\", \"bar\", \"baz\");\nmy $config = AppConfig->new( { CASE => 1 }, qw(foo bar baz) );\n\nNote that any unresolved method calls to AppConfig are automatically delegated to the\nAppConfig::State object. In practice, it means that it is possible to treat the AppConfig object\nas if it were an AppConfig::State object:\n\n# create AppConfig\nmy $config = AppConfig->new('foo', 'bar');\n\n# methods get passed through to internal AppConfig::State\n$config->foo(100);\n$config->set('bar', 200);\n$config->define('baz');\n$config->baz(300);\n\nDEFINING VARIABLES\nThe \"define()\" method (delegated to AppConfig::State) is used to pre-declare a variable and\nspecify its configuration.\n\n$config->define(\"foo\");\n\nVariables may also be defined directly from the AppConfig new() constructor.\n\nmy $config = AppConfig->new(\"foo\");\n\nIn both simple examples above, a new variable called \"foo\" is defined. A reference to a hash\narray may also be passed to specify configuration information for the variable:\n\n$config->define(\"foo\", {\nDEFAULT   => 99,\nALIAS     => 'metavar1',\n});\n\nConfiguration items specified in the GLOBAL option to the module constructor are applied by\ndefault when variables are created. e.g.\n\nmy $config = AppConfig->new( {\nGLOBAL => {\nDEFAULT  => \"<undef>\",\nARGCOUNT => ARGCOUNTONE,\n}\n} );\n\n$config->define(\"foo\");\n$config->define(\"bar\", { ARGCOUNT => ARGCOUNTNONE } );\n\nis equivalent to:\n\nmy $config = AppConfig->new();\n\n$config->define( \"foo\", {\nDEFAULT  => \"<undef>\",\nARGCOUNT => ARGCOUNTONE,\n} );\n\n$config->define( \"bar\",\nDEFAULT  => \"<undef>\",\nARGCOUNT => ARGCOUNTNONE,\n} );\n\nMultiple variables may be defined in the same call to define(). Configuration hashes for\nvariables can be omitted.\n\n$config->define(\"foo\", \"bar\" => { ALIAS = \"boozer\" }, \"baz\");\n\nSee AppConfig::State for full details of the configuration options available when defining\nvariables. These are, in brief:\n\nDEFAULT\nThe default value for the variable (default: undef).\n\nALIAS\nOne or more (list reference or \"list|like|this\") alternative names for the variable.\n\nARGCOUNT\nSpecifies the number and type of arguments that the variable expects. Constants in\n\":argcount\" tag set define ARGCOUNTNONE - simple on/off flag (default), ARGCOUNTONE -\nsingle value, ARGCOUNTLIST - multiple values accessed via list reference, ARGCOUNTHASH -\nhash table, \"key=value\", accessed via hash reference.\n\nARGS\nUsed to provide an argument specification string to pass to Getopt::Long via\nAppConfig::Getopt. E.g. \"=i\", \":s\", \"=s@\". This can also be used to implicitly set the\nARGCOUNT value (\"/^!/\" = ARGCOUNTNONE, \"/@/\" = ARGCOUNTLIST, \"/%/\" = ARGCOUNTHASH,\n\"/[=:].*/\" = ARGCOUNTONE)\n\nEXPAND\nSpecifies which variable expansion policies should be used when parsing configuration files.\nConstants in \":expand\" tag set define:\n\nEXPANDNONE - no expansion (default)\nEXPANDVAR  - expand C<$var> or C<$(var)> as other variables\nEXPANDUID  - expand C<~> and C<~uid> as user's home directory\nEXPANDENV - expand C<${var}> as environment variable\nEXPANDALL - do all expansions.\n\nVALIDATE\nRegex which the intended variable value should match or code reference which returns 1 to\nindicate successful validation (variable may now be set).\n\nACTION\nCode reference to be called whenever variable value changes.\n\nCOMPACT FORMAT DEFINITION\nVariables can be specified using a compact format. This is identical to the specification format\nof Getopt::Long and is of the form:\n\n\"name|alias|alias<argopts>\"\n\nThe first element indicates the variable name and subsequent ALIAS values may be added, each\nseparated by a vertical bar '|'.\n\nThe <argopts> element indicates the ARGCOUNT value and may be one of the following;\n\n!                  ARGCOUNTNONE\n=s                 ARGCOUNTONE\n=s@                ARGCOUNTLIST\n=s%                ARGCOUNTHASH\n\nAdditional constructs supported by Getopt::Long may be specified instead of the \"=s\" element\n(e.g. \"=f\"). The entire <argopts> element is stored in the ARGS parameter for the variable and\nis passed intact to Getopt::Long when the getopt() method is called.\n\nThe following examples demonstrate use of the compact format, with their equivalent full\nspecifications:\n\n$config->define(\"foo|bar|baz!\");\n\n$config->define(\n\"foo\" => {\nALIAS    => \"bar|baz\",\nARGCOUNT => ARGCOUNTNONE,\n});\n\n$config->define(\"name=s\");\n\n$config->define(\n\"name\" => {\nARGCOUNT => ARGCOUNTONE,\n});\n\n$config->define(\"file|filelist|f=s@\");\n\n$config->define(\n\"file\" => {\nALIAS    => \"filelist|f\",\nARGCOUNT => ARGCOUNTLIST,\n});\n\n$config->define(\"user|u=s%\");\n\n$config->define(\n\"user\" => {\nALIAS    => \"u\",\nARGCOUNT => ARGCOUNTHASH,\n});\n\nAdditional configuration options may be specified by hash reference, as per normal. The compact\ndefinition format will override any configuration values provided for ARGS and ARGCOUNT.\n\n$config->define(\"file|filelist|f=s@\", { VALIDATE => \\&checkfile } );\n\nREADING AND MODIFYING VARIABLE VALUES\nAppConfig defines two methods (via AppConfig::State) to manipulate variable values\n\nset($variable, $value);\nget($variable);\n\nOnce defined, variables may be accessed directly as object methods where the method name is the\nsame as the variable name. i.e.\n\n$config->set(\"verbose\", 1);\n\nis equivalent to\n\n$config->verbose(1);\n\nNote that AppConfig defines the following methods:\n\nnew();\nfile();\nargs();\ngetopt();\n\nAnd also, through delegation to AppConfig::State:\n\ndefine()\nget()\nset()\nvarlist()\n\nIf you define a variable with one of the above names, you will not be able to access it directly\nas an object method. i.e.\n\n$config->file();\n\nThis will call the file() method, instead of returning the value of the 'file' variable. You can\nwork around this by explicitly calling get() and set() on a variable whose name conflicts:\n\n$config->get('file');\n\nor by defining a \"safe\" alias by which the variable can be accessed:\n\n$config->define(\"file\", { ALIAS => \"fileopt\" });\nor\n$config->define(\"file|fileopt\");\n\n...\n$config->fileopt();\n\nWithout parameters, the current value of the variable is returned. If a parameter is specified,\nthe variable is set to that value and the result of the set() operation is returned.\n\n$config->age(29);        # sets 'age' to 29, returns 1 (ok)\nprint $config->age();    # prints \"29\"\n\nThe varlist() method can be used to extract a number of variables into a hash array. The first\nparameter should be a regular expression used for matching against the variable names.\n\nmy %vars = $config->varlist(\"^file\");   # all \"file*\" variables\n\nA second parameter may be specified (any true value) to indicate that the part of the variable\nname matching the regex should be removed when copied to the target hash.\n\n$config->filename(\"/tmp/file\");\n$config->filepath(\"/foo:/bar:/baz\");\n\nmy %vars = $config->varlist(\"^file\", 1);\n\n# %vars:\n#    name => /tmp/file\n#    path => \"/foo:/bar:/baz\"\n\nREADING CONFIGURATION FILES\nThe AppConfig module provides a streamlined interface for reading configuration files with the\nAppConfig::File module. The file() method automatically loads the AppConfig::File module and\ncreates an object to process the configuration file or files. Variables stored in the internal\nAppConfig::State are automatically updated with values specified in the configuration file.\n\n$config->file($filename);\n\nMultiple files may be passed to file() and should indicate the file name or be a reference to an\nopen file handle or glob.\n\n$config->file($filename, $filehandle, \\*STDIN, ...);\n\nThe file may contain blank lines and comments (prefixed by '#') which are ignored. Continutation\nlines may be marked by ending the line with a '\\'.\n\n# this is a comment\ncallsign = alpha bravo camel delta echo foxtrot golf hipowls \\\nindia juliet kilo llama mike november oscar papa  \\\nquebec romeo sierra tango umbrella victor whiskey \\\nx-ray yankee zebra\n\nVariables that are simple flags and do not expect an argument (ARGCOUNT = ARGCOUNTNONE) can be\nspecified without any value. They will be set with the value 1, with any value explicitly\nspecified (except \"0\" and \"off\") being ignored. The variable may also be specified with a \"no\"\nprefix to implicitly set the variable to 0.\n\nverbose                              # on  (1)\nverbose = 1                          # on  (1)\nverbose = 0                          # off (0)\nverbose off                          # off (0)\nverbose on                           # on  (1)\nverbose mumble                       # on  (1)\nnoverbose                            # off (0)\n\nVariables that expect an argument (ARGCOUNT = ARGCOUNTONE) will be set to whatever follows the\nvariable name, up to the end of the current line (including any continuation lines). An optional\nequals sign may be inserted between the variable and value for clarity.\n\nroom = /home/kitchen\nroom   /home/bedroom\n\nEach subsequent re-definition of the variable value overwrites the previous value.\n\nprint $config->room();               # prints \"/home/bedroom\"\n\nVariables may be defined to accept multiple values (ARGCOUNT = ARGCOUNTLIST). Each subsequent\ndefinition of the variable adds the value to the list of previously set values for the variable.\n\ndrink = coffee\ndrink = tea\n\nA reference to a list of values is returned when the variable is requested.\n\nmy $beverages = $config->drink();\nprint join(\", \", @$beverages);      # prints \"coffee, tea\"\n\nVariables may also be defined as hash lists (ARGCOUNT = ARGCOUNTHASH). Each subsequent\ndefinition creates a new key and value in the hash array.\n\nalias l=\"ls -CF\"\nalias e=\"emacs\"\n\nA reference to the hash is returned when the variable is requested.\n\nmy $aliases = $config->alias();\nforeach my $k (keys %$aliases) {\nprint \"$k => $aliases->{ $k }\\n\";\n}\n\nThe '-' prefix can be used to reset a variable to its default value and the '+' prefix can be\nused to set it to 1\n",
            "subsections": [
                {
                    "name": "-verbose",
                    "content": "+debug\n\nVARIABLE EXPANSION\nVariable values may contain references to other AppConfig variables, environment variables\nand/or users' home directories. These will be expanded depending on the EXPAND value for each\nvariable or the GLOBAL EXPAND value.\n\nThree different expansion types may be applied:\n\nbin = ~/bin          # expand '~' to home dir if EXPANDUID\ntmp = ~abw/tmp       # as above, but home dir for user 'abw'\n\nperl = $bin/perl     # expand value of 'bin' variable if EXPANDVAR\nripl = $(bin)/ripl   # as above with explicit parens\n\nhome = ${HOME}       # expand HOME environment var if EXPANDENV\n\nSee AppConfig::State for more information on expanding variable values.\n\nThe configuration files may have variables arranged in blocks. A block header, consisting of the\nblock name in square brackets, introduces a configuration block. The block name and an\nunderscore are then prefixed to the names of all variables subsequently referenced in that\nblock. The block continues until the next block definition or to the end of the current file.\n\n[block1]\nfoo = 10             # block1foo = 10\n\n[block2]\nfoo = 20             # block2foo = 20\n\nPARSING COMMAND LINE OPTIONS\nThere are two methods for processing command line options. The first, args(), is a small and\nefficient implementation which offers basic functionality. The second, getopt(), offers a more\npowerful and complete facility by delegating the task to Johan Vroman's Getopt::Long module. The\ntrade-off between args() and getopt() is essentially one of speed/size against flexibility. Use\nas appropriate. Both implement on-demand loading of modules and incur no overhead until used.\n\nThe args() method is used to parse simple command line options. It automatically loads the\nAppConfig::Args module and creates an object to process the command line arguments. Variables\nstored in the internal AppConfig::State are automatically updated with values specified in the\narguments.\n\nThe method should be passed a reference to a list of arguments to parse. The @ARGV array is used\nif args() is called without parameters.\n\n$config->args(\\@myargs);\n$config->args();               # uses @ARGV\n\nArguments are read and shifted from the array until the first is encountered that is not\nprefixed by '-' or '--'. At that point, the method returns 1 to indicate success, leaving any\nunprocessed arguments remaining in the list.\n\nEach argument should be the name or alias of a variable prefixed by '-' or '--'. Arguments that\nare not prefixed as such (and are not an additional parameter to a previous argument) will cause\na warning to be raised. If the PEDANTIC option is set, the method will return 0 immediately.\nWith PEDANTIC unset (default), the method will continue to parse the rest of the arguments,\nreturning 0 when done.\n\nIf the variable is a simple flag (ARGCOUNT = ARGCOUNTNONE) then it is set to the value 1. The\nvariable may be prefixed by \"no\" to set its value to 0.\n\nmyprog -verbose --debug -notaste     # $config->verbose(1)\n# $config->debug(1)\n# $config->taste(0)\n\nVariables that expect an additional argument (ARGCOUNT != 0) will be set to the value of the\nargument following it.\n\nmyprog -f /tmp/myfile                # $config->file('/tmp/file');\n\nVariables that expect multiple values (ARGCOUNT = ARGCOUNTLIST or ARGCOUNTHASH) will have\nsuccessive values added each time the option is encountered.\n\nmyprog -file /tmp/foo -file /tmp/bar # $config->file('/tmp/foo')\n# $config->file('/tmp/bar')\n\n# file => [ '/tmp/foo', '/tmp/bar' ]\n\nmyprog -door \"jim=Jim Morrison\" -door \"ray=Ray Manzarek\"\n# $config->door(\"jim=Jim Morrison\");\n# $config->door(\"ray=Ray Manzarek\");\n\n# door => { 'jim' => 'Jim Morrison', 'ray' => 'Ray Manzarek' }\n\nSee AppConfig::Args for further details on parsing command line arguments.\n\nThe getopt() method provides a way to use the power and flexibility of the Getopt::Long module\nto parse command line arguments and have the internal values of the AppConfig object updates\nautomatically.\n\nThe first (non-list reference) parameters may contain a number of configuration string to pass\nto Getopt::Long::Configure. A reference to a list of arguments may additionally be passed or\n@ARGV is used by default.\n\n$config->getopt();                       # uses @ARGV\n$config->getopt(\\@myargs);\n$config->getopt(qw(autoabbrev debug));  # uses @ARGV\n$config->getopt(qw(debug), \\@myargs);\n\nSee Getopt::Long for details of the configuration options available.\n\nThe getopt() method constructs a specification string for each internal variable and then\ninitializes Getopt::Long with these values. The specification string is constructed from the\nname, any aliases (delimited by a vertical bar '|') and the value of the ARGS parameter.\n\n$config->define(\"foo\", {\nARGS  => \"=i\",\nALIAS => \"bar|baz\",\n});\n\n# Getopt::Long specification: \"foo|bar|baz=i\"\n\nErrors and warning generated by the Getopt::Long module are trapped and handled by the AppConfig\nerror handler. This may be a user-defined routine installed with the ERROR configuration option.\n\nPlease note that the AppConfig::Getopt interface is still experimental and may not be 100%\noperational. This is almost undoubtedly due to problems in AppConfig::Getopt rather than\nGetopt::Long.\n\nPARSING CGI PARAMETERS\nThe cgi() method provides an interface to the AppConfig::CGI module for updating variable values\nbased on the parameters appended to the URL for a CGI script. This is commonly known as the CGI\n\"GET\" method. The CGI \"POST\" method is currently not supported.\n\nParameter definitions are separated from the CGI script name by a question mark and from each\nother by ampersands. Where variables have specific values, these are appended to the variable\nwith an equals sign:\n\nhttp://www.here.com/cgi-bin/myscript?foo=bar&baz=qux&verbose\n\n# $config->foo('bar');\n# $config->baz('qux');\n# $config->verbose(1);\n\nCertain values specified in a URL must be escaped in the appropriate manner (see CGI\nspecifications at http://www.w3c.org/ for full details). The AppConfig::CGI module automatically\nunescapes the CGI query string to restore the parameters to their intended values.\n\nhttp://where.com/mycgi?title=%22The+Wrong+Trousers%22\n\n# $config->title('\"The Wrong Trousers\"');\n\nPlease be considerate of the security implications of providing writable access to script\nvariables via CGI.\n\nhttp://rebel.alliance.com/cgi-bin/...\n.../sendreport?file=%2Fetc%2Fpasswd&email=darth%40empire.com\n\nTo avoid any accidental or malicious changing of \"private\" variables, define only the \"public\"\nvariables before calling the cgi() (or any other) method. Further variables can subsequently be\ndefined which can not be influenced by the CGI parameters.\n\n$config->define('verbose', 'debug')\n$config->cgi();             # can only set verbose and debug\n\n$config->define('email', 'file');\n$config->file($cfgfile);    # can set verbose, debug, email + file\n"
                }
            ]
        },
        "CONSTANT DEFINITIONS": {
            "content": "A number of constants are defined by the AppConfig module. These may be accessed directly (e.g.\nAppConfig::EXPANDVARS) or by first importing them into the caller's package. Constants are\nimported by specifying their names as arguments to \"use AppConfig\" or by importing a set of\nconstants identified by its \"tag set\" name.\n\nuse AppConfig qw(ARGCOUNTNONE ARGCOUNTONE);\n\nuse AppConfig qw(:argcount);\n\nThe following tag sets are defined:\n\n:expand\nThe ':expand' tagset defines the following constants:\n\nEXPANDNONE\nEXPANDVAR\nEXPANDUID\nEXPANDENV\nEXPANDALL       # EXPANDVAR | EXPANDUID | EXPANDENV\nEXPANDWARN\n\nSee AppConfig::File for full details of the use of these constants.\n\n:argcount\nThe ':argcount' tagset defines the following constants:\n\nARGCOUNTNONE\nARGCOUNTONE\nARGCOUNTLIST\nARGCOUNTHASH\n\nSee AppConfig::State for full details of the use of these constants.\n",
            "subsections": []
        },
        "REPOSITORY": {
            "content": "<https://github.com/neilbowers/AppConfig>\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Andy Wardley, <abw@wardley.org>\n\nWith contributions from Dave Viner, Ijon Tichy, Axel Gerstmair and many others whose names have\nbeen lost to the sands of time (reminders welcome).\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright (C) 1997-2007 Andy Wardley. All Rights Reserved.\n\nCopyright (C) 1997,1998 Canon Research Centre Europe Ltd.\n\nThis module is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "AppConfig::State, AppConfig::File, AppConfig::Args, AppConfig::Getopt, AppConfig::CGI,\nGetopt::Long\n",
            "subsections": []
        }
    },
    "summary": "AppConfig - Perl5 module for reading configuration files and parsing command line arguments.",
    "flags": [
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "+debug VARIABLE EXPANSION 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 EXPANDUID tmp = ~abw/tmp # as above, but home dir for user 'abw' perl = $bin/perl # expand value of 'bin' variable if EXPANDVAR ripl = $(bin)/ripl # as above with explicit parens home = ${HOME} # expand HOME environment var if EXPANDENV 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 # block1foo = 10 [block2] foo = 20 # block2foo = 20 PARSING COMMAND LINE OPTIONS There are two methods for processing command line options. The first, args(), is a small and efficient implementation which offers basic functionality. The second, getopt(), offers a more powerful and complete facility by delegating the task to Johan Vroman's Getopt::Long module. The trade-off between args() and getopt() is essentially one of speed/size against flexibility. Use as appropriate. Both implement on-demand loading of modules and incur no overhead until used. The args() method is used to parse simple command line options. It automatically loads the AppConfig::Args module and creates an object to process the command line arguments. Variables stored in the internal AppConfig::State are automatically updated with values specified in the arguments. The method should be passed a reference to a list of arguments to parse. The @ARGV array is used if args() is called without parameters. $config->args(\\@myargs); $config->args(); # uses @ARGV Arguments are read and shifted from the array until the first is encountered that is not prefixed by '-' or '--'. At that point, the method returns 1 to indicate success, leaving any unprocessed arguments remaining in the list. Each argument should be the name or alias of a variable prefixed by '-' or '--'. Arguments that are not prefixed as such (and are not an additional parameter to a previous argument) will cause a warning to be raised. If the PEDANTIC option is set, the method will return 0 immediately. With PEDANTIC unset (default), the method will continue to parse the rest of the arguments, returning 0 when done. If the variable is a simple flag (ARGCOUNT = ARGCOUNTNONE) then it is set to the value 1. The variable may be prefixed by \"no\" to set its value to 0. myprog -verbose --debug -notaste # $config->verbose(1) # $config->debug(1) # $config->taste(0) Variables that expect an additional argument (ARGCOUNT != 0) will be set to the value of the argument following it. myprog -f /tmp/myfile # $config->file('/tmp/file'); Variables that expect multiple values (ARGCOUNT = ARGCOUNTLIST or ARGCOUNTHASH) will have successive values added each time the option is encountered. myprog -file /tmp/foo -file /tmp/bar # $config->file('/tmp/foo') # $config->file('/tmp/bar') # file => [ '/tmp/foo', '/tmp/bar' ] myprog -door \"jim=Jim Morrison\" -door \"ray=Ray Manzarek\" # $config->door(\"jim=Jim Morrison\"); # $config->door(\"ray=Ray Manzarek\"); # door => { 'jim' => 'Jim Morrison', 'ray' => 'Ray Manzarek' } See AppConfig::Args for further details on parsing command line arguments. The getopt() method provides a way to use the power and flexibility of the Getopt::Long module to parse command line arguments and have the internal values of the AppConfig object updates automatically. The first (non-list reference) parameters may contain a number of configuration string to pass to Getopt::Long::Configure. A reference to a list of arguments may additionally be passed or @ARGV is used by default. $config->getopt(); # uses @ARGV $config->getopt(\\@myargs); $config->getopt(qw(autoabbrev debug)); # uses @ARGV $config->getopt(qw(debug), \\@myargs); See Getopt::Long for details of the configuration options available. The getopt() method constructs a specification string for each internal variable and then initializes Getopt::Long with these values. The specification string is constructed from the name, any aliases (delimited by a vertical bar '|') and the value of the ARGS parameter. $config->define(\"foo\", { ARGS => \"=i\", ALIAS => \"bar|baz\", }); # Getopt::Long specification: \"foo|bar|baz=i\" Errors and warning generated by the Getopt::Long module are trapped and handled by the AppConfig error handler. This may be a user-defined routine installed with the ERROR configuration option. Please note that the AppConfig::Getopt interface is still experimental and may not be 100% operational. This is almost undoubtedly due to problems in AppConfig::Getopt rather than Getopt::Long. PARSING CGI PARAMETERS The cgi() method provides an interface to the AppConfig::CGI module for updating variable values based on the parameters appended to the URL for a CGI script. This is commonly known as the CGI \"GET\" method. The CGI \"POST\" method is currently not supported. Parameter definitions are separated from the CGI script name by a question mark and from each other by ampersands. Where variables have specific values, these are appended to the variable with an equals sign: http://www.here.com/cgi-bin/myscript?foo=bar&baz=qux&verbose # $config->foo('bar'); # $config->baz('qux'); # $config->verbose(1); Certain values specified in a URL must be escaped in the appropriate manner (see CGI specifications at http://www.w3c.org/ for full details). The AppConfig::CGI module automatically unescapes the CGI query string to restore the parameters to their intended values. http://where.com/mycgi?title=%22The+Wrong+Trousers%22 # $config->title('\"The Wrong Trousers\"'); Please be considerate of the security implications of providing writable access to script variables via CGI. http://rebel.alliance.com/cgi-bin/... .../sendreport?file=%2Fetc%2Fpasswd&email=darth%40empire.com To avoid any accidental or malicious changing of \"private\" variables, define only the \"public\" variables before calling the cgi() (or any other) method. Further variables can subsequently be defined which can not be influenced by the CGI parameters. $config->define('verbose', 'debug') $config->cgi(); # can only set verbose and debug $config->define('email', 'file'); $config->file($cfgfile); # can set verbose, debug, email + file"
        }
    ],
    "examples": [],
    "see_also": []
}