Debian Codegraph @

README

raw
1 NAME
2 CGI::Application::Plugin::Config::Simple - Add Config::Simple support to
3 CGI::Application
4
5 SYNOPSIS
6 in your CGI::Application based module
7
8 use CGI::Application::Plugin::Config::Simple;
9
10 sub cgiapp_init {
11 my $self = shift;
12 #set my config file
13 $self->config_file('myapp.conf');
14
15 #
16 #do other stuff
17 #
18 }
19
20 #later on in a run mode
21 sub run_mode1 {
22 my $self = shift;
23
24 #just get a single parameter from my config file
25 my $value = $self->config_param('my_param');
26
27 #get a parameter in a block (if using ini style files)
28 $value = $self->config_param('my_block.my_param');
29
30 #the entire config hash reference
31 my $config_vars = $self->config_param();
32
33 #get my Config::Simple object for direct access
34 my $config = $self->config;
35 }
36
37 DESCRIPTION
38 This module acts as a plugin for Config::Simple to be easily used inside
39 of a CGI::Application module. It does not provide every method available
40 from Config::Simple but rather easy access to your configuration
41 variables. It does however provide direct access to the underlying
42 Config::General object created if you want to use it's full power.
43
44 The module tries to make the getting and setting of configuration
45 variables as easy as possible. Only three methods are exported into your
46 CGI::Application module and they are described below.
47
48 Before I wrote this module sometimes I would put my code that read in
49 the configuration file into the cgiapp_init() or cgiapp_prerun() methods
50 but then if I had a run mode that didn't need those config variables it
51 was run anyway. This module helps to solve this is. The Config::Simple
52 object is not created (and the config file is not read and parsed) until
53 after your first call to config() or config_param() to either
54 retrieve/set values, or get the Config::Simple object. This lazy loading
55 idea came from Cees Hek's CGI::Application::Plugin::Session module.
56
57 METHODS
58 config_param()
59
60 This method acts as an accessor/mutator for configuration variables
61 coming from the configuration file.
62
63 This method will behave in three different ways depending on how many
64 parameters it is passed. If 0 parameters are passed then the entire
65 config structure will be returned as a hash ref. If 1 parameters is
66 passed then the value of that parameter in the config file will be
67 returned. If more than 1 parameter is passed then it will treat them as
68 name value pairs and will set the parameters in the config file
69 accordingly. In this case, if we successfully set the parameters then a
70 true value will be returned.
71
72 #get the complete config hash
73 my $config_hash = $self->config_param();
74 #just get one config value
75 my $value = $self->config_param($parameter);
76 #set multiple config values
77 my $success = $self->config_param(param1 => $value1, param2 => $value2);
78
79 This method uses Config::Simple so if you are using ini-files then you
80 can set the values of variables inside blocks as well using the '.'
81 notation. See Config::Simple;
82
83 You must set the name of the configuration file either using the
84 config_file() method or the CGIAPP_CONFIG_FILE environment variable
85 before calling this method or it will 'die'.
86
87 config()
88
89 This method will return the underlying Config::Simple object for more
90 direct use by your application. You must set the name of the
91 configuration file either using the config_file() method or the
92 CGIAPP_CONFIG_FILE environment variable before calling this method or it
93 will 'die'.
94
95 my $conf = $self->config();
96
97 config_file([$file_name])
98
99 This method acts as an accessor/mutator to either get the name of the
100 current config file or to change/initialize it. This method must be
101 called to initialize the name of the config file before any call can be
102 made to either config() or config_param() unless the
103 'CGIAPP_CONFIG_FILE' environment variable has been set. If this
104 environment variable is set it will be used as the initial value of the
105 config file. This is useful if we are running in a mod_perl environment
106 when can use a statement like this in your httpd.conf file:
107
108 PerlSetEnv CGIAPP_CONFIG_FILE /path/to/my/conf
109
110 It is typical to set the name of the config file in the cgiapp_init()
111 phase of your application.
112
113 If a value is passed as a parameter then the config file with that name
114 is used. It will always return the name of the current config file.
115
116 #get the value of the CGIAPP_CONFIG_FILE environment variable (if there is one)
117 #since we haven't set the config file's name with config_file() yet.
118 my $file_name = $self->config_file();
119
120 #set the config file's name
121 $self->config_file('myapp.conf');
122
123 #get the name of the config file
124 $file_name = $self->config_file();
125
126 CAVEATS
127 The CGI::Application object is implemented as a hash and we store the
128 variables used by this module's methods inside of it as a hash named
129 __CONFIG_SIMPLE. If you use any other CGI::Application plugins there
130 would be problems if they also used $self->{__CONFIG_SIMPLE} but in
131 practice this should never actually happen.
132
133 AUTHOR
134 Michael Peters <[email protected]>
135
136 Thanks to Plus Three, LP (http://www.plusthree.com) for sponsoring my
137 work on this module
138
139 SEE ALSO
140 * CGI::Application
141 * Config::Simple
142 LICENSE
143 This library is free software; you can redistribute it and/or modify it
144 under the same terms as Perl itself.
145