App::Framework::Feature::Config - Configuration file read/write
use App::Framework '+Config' ;
Provides a standard interface for reading/writing application configuration files. When this feature is included into an application, it attempts to read a configuration file for the application (which may be stored in one of severeal places). If found, the configuartion file is processed and may update the application options (see App::Framework::Feature::Options).
Also, an application may create one or more extra instances of the feature to read addtional configuration files.
Configuration files are text files containing variable / value pairs. Optionally these variable/value pairs may be gouped into 'sections' (see "sections").
The simplest format consists of an optional description line followed immediately by a variable/value setting:
# description var=value
(NOTE: There can be no empty lines between the description "comment" and the variable).
An alternative to the simple format is as shown below. This contains additional information useful for checking the value setting.
## Summary: Configuration for Apache 2 ## Type: s # # Here you can name files, separated by spaces, that should be Include'd from # httpd.conf. # # This allows you to add e.g. VirtualHost statements without touching # /etc/apache2/httpd.conf itself, which makes upgrading easier. # apache_include_files="mod_dav"
The lines prefixed by ## are extra information about the variable and are used to specify a summary, and a variable type. The extra information prefixed by # is used as the description. The above example will be shown in the application man page as:
-apache_include_files <string> [Default: "mod_dav"] Config option:Here you can name files, separated by spaces, that should be Include'd from httpd.conf. This allows you to add e.g. VirtualHost statements without touching /etc/apache2/httpd.conf itself, which makes upgrading easier.
Any configuration variables specified in this manner will automatically be put into the application's options, but will also be available via the application's 'Config' feature.
Each section is defined by a string contained within '[]'. Where there are multiple sections with the same name, they are added to an array. All variables defined before the sections are treated as "global".
global=string [top] a=1 [instance] a=11 [instance] a=22
The above example will be stored as the HASH:
{ global => 'string' top => [ { a => 1 } ] instance => [ { a => 11 }, { a => 22 } ], }
Even if a section has only one instance, it is always stored as an array.
As stated above, any variables defined in the configuration file before the sections are treated as "global" (see "Sections"). These global variables have the additional property that they are automatically treated like options definitions (see App::Framework::Feature::Options).
This means that the global variables are indistinguishable from options (in fact all of the options variables appear in the global area of the configurations and vice versa). Also, you do not need to specify options in the application script - you can just define them once in the configuration file (although see "Writing").
The configuration file is searched for using the path specification. This path is actually one or more paths, specified in the order in which to search for the configuration file. The search is stopped as soon as the first valid file is found.
The application configuration search path is set to the following default, unless it is over-ridden by either the application script or by the user (via command line options):
$HOME/$app_dir
User-specific configuration. $HOME is replaced with the user's home directory, and $app_dir is replaced by ".name" (or "name" on Windows) where name is the name of the script.
This allows users to set up their own settings.
$SYSTEM/$name
System configuration. $SYSTEM is replaced with "/etc" (or "C:" on Windows), and $name is replaced by the name of the script.
This allows sysadmins to set up a common set of settings.
$app_path/config
Application-specific configuration. $app_path is replaced by the path to the installed script.
This allows script developers to bundle their settings with the installed script.
As an example, the script 'test_script' installed on a Linux under '/usr/local/bin' will, by default, have the following search path:
$HOME/.test_script /etc/test_script /usr/local/bin/config
In addition to the search path described above, there is also a write search path. This path is searched until a file (and it's path) can be written to by the script user. It is set, by default, to:
(i.e. the same as the read path, but without the application-bundle directory).
Uses App::Framework::Base::SearchPath to provide the path search.
You can, of course, just write your config files from scratch. Alternatively, if you predominantly use "global" settings, then you specify them as application options (App::Framework::Feature::Options). Run your script with '-config_write' and it will automatically create a formatted configuration file (see "ADDITIONAL COMMAND LINE OPTIONS" for other command line settings).
In addition to having the application tied in with it's own configuration file, you can create multiple extra configuration files and read/write then using this feature. To do this, create a new App::Framework::Feature::Config object instance per configuration file. You can then access the contents of the file using the object's methods.
For example:
sub app { my ($app, $opts_href, $args_href) = @_ ; ## use application config object to create a new one my $new_cfg = $app->feature('Config')->new( 'filename' => 'some_file.conf', 'path' => '$HOME,/etc/new_config', 'write_path' => '$HOME', ) ; $new_cfg->read() ; # do stuff with configuration ... # (debug) show configuration $app->prt_data("Readback config=", $new_cfg->config) ; ## write out file $new_cfg->write() ; }
Configuration files are stored in a HASH, where the keys are the variable names and the values are a HASH of information for that variable:
'summary' => Summary string 'default' => Default value 'description' => Description string 'type' => Variable option type (s, i, f) 'value' => Variable value
The following fields should be defined either in the call to 'new()', as part of a 'set()' call, or called by their accessor method (which is the same name as the field):
User-specified config filename. This is searched for using the search path
A comma seperated list (in scalar context), or an ARRAY ref list of paths to be searched (for a file).
A comma seperated list (in scalar context), or an ARRAY ref list of paths to be searched (for a file) when writing. If not set, then path is used.
Created when config file is read. Full path of configuration file accessed in last read or write.
Created when config file is read. ARRAY ref list of any section names.
Created when config file is read. This is a HASH ref to the raw configuration file entries
This feature adds the following additional command line options to any application:
Comma/semicolon separated list of search paths for the config file
Comma/semicolon separated list of paths for writing the config file. Uses -config_path setting if not specified.
Specify the configuration filename to use
When specified, writes the configuration file using the write path
Create a new Config object.
The %args are specified as they would be in the set method, for example:
'mmap_handler' => $mmap_handler
The full list of possible arguments are :
'fields' => Either ARRAY list of valid field names, or HASH of field names with default values
Initialises the Config object class variables.
Overrides the parent 'set()' method to send the parameters off to the App::Framework::Base::SearchPath object as well as itself.
Application hook: When application calls go() set up config options.
Application hook: When application calls getopts() initialise the object and read config.
Application hook: When application calls application() check options.
Returns the config object. If %args are specified they are used to set the "FIELDS"
Alias to "config"
Read in the config file (located somewhere in the searchable path). Expects the filename and path fields to already have been set. Optionally can specify these setting as part of the %args hash.
Updates the field 'file_path' with the full path to the read config file.
Returns the top-level HASH ref.
Writes the configuration information to the specified file.
Updates the field 'file_path' with the full path to the written config file.
Adds the contents of the specified HASH to the current configuration settings.
Clear out the current configuration settings.
Returns a "flat" HASH (of variable/value pairs) where any arrays are removed. If the $name is specified, returns the HASH that the named key refers to, unrolling it if it is an array.
Returns an empty HASH if $name does not exist.
Returns an ARRAY of HASHes of variable/value pairs. If the $name is specified, returns the ARRAY that the named key refers to. In either case, if the item is not an array, then it is rolled into a single entry ARRAY.
Returns an empty ARRAY if $name does not exist.
Returns a "flat" HASH (containing full config entry) where any arrays are removed. If the $name is specified, returns the HASH that the named key refers to, unrolling it if it is an array.
Returns an ARRAY of HASHes (containing full config entry). If the $name is specified, returns the ARRAY that the named key refers to. In either case, if the item is not an array, then it is rolled into a single entry ARRAY.
Given a HASH ref containing hashes of full config entries, convert into a hash of variable/value pairs
Setting the debug flag to level 1 prints out (to STDOUT) some debug messages, setting it to level 2 prints out more verbose messages.
Steve Price <sdprice at cpan.org>
<sdprice at cpan.org>
None that I know of!
To install App::Framework, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Framework
CPAN shell
perl -MCPAN -e shell install App::Framework
For more information on module installation, please visit the detailed CPAN module installation guide.