Kelp::Module::Config - Configuration for Kelp applications
This is one of the two modules that are automatically loaded for each and every Kelp application. It reads configuration files containing Perl-style hashes, and merges them depending on the value of the application's mode attribute.
mode
The main configuration file name is config.pl, and it will be searched in the conf and ../conf directories. You can also set the KELP_CONFIG_DIR environmental variable with the path to the configuration files.
config.pl
conf
../conf
KELP_CONFIG_DIR
This module comes with some default values, so if there are no configuration files found, those values will be used. Any values from configuration files will add to or override the default values.
First the module will look for conf/config.pl, then for ../conf/config.pl. If found, they will be parsed and merged into the default values. The same order applies to the mode file too, so if the application mode is development, then conf/development.pl and ../conf/development.pl will be looked for. If found, they will also be merged to the config hash.
conf/config.pl
../conf/config.pl
conf/development.pl
../conf/development.pl
The first configuration file this module will look for is config.pl. This is where you should keep configuration options that apply to all running environments. The mode-specific configuration file will be merged to this config, and it will take priority. Merging is done as follows:
+ in front of the name will add the elements to the array:
+
# in config.pl { middleware => [qw/Bar Foo/] } # in development.pl { '+middleware' => ['Baz'] # Add 'Baz' in development }
- in front of the name will remove the elements from the array:
-
# in config.pl { modules => [qw/Template JSON Logger/] } # in test.pl { '-modules' => [qw/Logger/] # Remove the Logger modules in test mode }
No sigil will cause the array to be completely replaced:
# in config.pl { middleware => [qw/Bar Foo/] } # in cli.pl { middleware => [] # No middleware in CLI }
This module registers the following methods into the underlying app:
A wrapper for the /get method.
/get
# Somewhere in the app my $pos = $self->config('row.col.position'); # Gets {row}->{col}->{position} from the config hash
A reference to the entire configuration hash.
my $pos = $self->config_hash->{row}->{col}->{position};
Using this or config is entirely up to the application developer.
config
This module implements some attributes, which can be overridden by subclasses.
The file extension of the configuration files. Default is pl.
pl
A regular expression for the value separator used by "get". The default is qr/\./, i.e. a dot.
qr/\./
Specifies a path, or an array of paths where to look for configuration files. This is particularly useful when writing tests, because you can set a custom path to a peculiar configuration.
The hashref with data contained in all of the merged configurations.
The module also implements some methods for parsing the config files, which can be overridden in extending classes.
get($string)
Get a value from the config using a separated string.
my $value = $c->get('bar.foo.baz'); my $same = $c->get('bar')->{foo}->{baz}; my $again = $c->data->{bar}->{foo}->{baz};
By default the separator is a dot, but this can be changed via the "separator" attribute.
load(filename)
Loads, and parses the file $filename and returns a hash reference.
$filename
This module sets certain default values. All of them may be overridden in any of the conf/ files. It probably pays to view the code of this module and look and the defaults sub to see what is being set by default, but here is the short version:
conf/
defaults
UTF-8
http://localhost:5000
An arrayrf with module names to load on startup. The default value is ['JSON', 'Template']
['JSON', 'Template']
A hashref with initializations for each of the loaded modules, except this one, ironically.
An arrayref with middleware to load on startup. The default value is an empty array.
A hashref with initialization arguments for each of the loaded middleware.
You can subclass this module and use other types of configuration files (for example YAML). You need to override the ext attribute and the load subroutine.
ext
load
package Kelp::Module::Config::Custom; use Kelp::Parent 'Kelp::Module::Config'; # Set the config file extension to .cus attr ext => 'cus'; sub load { my ( $self, $filename ) = @_; # Load $filename, parse it and return a hashref } 1;
Later ...
# app.psgi use MyApp; my $app = MyApp->new( config_module => 'Config::Custom' ); run;
The above example module will look for config/*.cus to load as configuration.
config/*.cus
Since the config files are searched in both conf/ and ../conf/, you can use the same configuration set of files for your application and for your tests. Assuming the all of your test will reside in t/, they should be able to load and find the config files at ../conf/.
../conf/
t/
To install Kelp, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Kelp
CPAN shell
perl -MCPAN -e shell install Kelp
For more information on module installation, please visit the detailed CPAN module installation guide.