1MooseX::Configuration(3U)ser Contributed Perl DocumentatiMoonoseX::Configuration(3)
2
3
4

NAME

6       MooseX::Configuration - Define attributes which come from configuration
7       files
8

VERSION

10       version 0.02
11

SYNOPSIS

13         package MyApp::Config;
14
15         use Moose;
16         use MooseX::Configuration;
17
18         has database_name => (
19             is      => 'ro',
20             isa     => 'Str',
21             default => 'MyApp',
22             section => 'database',
23             key     => 'name',
24             documentation =>
25                 'The name of the database.',
26         );
27
28         has database_username => (
29             is      => 'ro',
30             isa     => Str,
31             default => q{},
32             section => 'database',
33             key     => 'username',
34             documentation =>
35                 'The username to use when connecting to the database. By default, this is empty.',
36         );
37
38         my $config = MyApp::Config->new( config_file => '/path/to/config/myapp.ini' );
39         $config->write_file( ... );
40

DESCRIPTION

42       This module lets you define attributes which can come from a
43       configuration file. It also adds a role to your class which allows you
44       to write a configuration file.
45
46       It is based on using a simple INI-style configuration file, which
47       contains sections and keys:
48
49         key1 = value
50         key2 = 42
51
52         [section]
53         key3 = 2
54

ATTRIBUTE API

56       Simply using this module in your class changes your class's attribute
57       metaclass to add support for defining attributes as configuration
58       items.
59
60       There are two new parameters you can pass when defining an attribute,
61       "section" and "key". These tell the module how to find the attribute's
62       value in the configuration file. The "section" parameter is optional.
63       If you don't set it, but do provide a key, then the section defaults to
64       "_", which is the main section of the config file.
65
66       If you pass a "section" you must also pass a "key".
67
68       Defining an attribute as a configuration item has several effects.
69       First, it changes the default value for the attribute. Before looking
70       at a "default" or "builder" you define, the attribute will first look
71       in the config file for a corresponding value. If one exists, it will
72       use that, otherwise it will fall back to using a default you supply.
73
74       If you do supply a default, it must be a string (or number), not a
75       reference or undefined value.
76
77       All configuration attributes are lazy. This is necessary because the
78       configuration file needs to be loaded and parsed before looking up
79       values.
80
81       The "documentation" string is used when generating a configuration
82       file. See below for details.
83

CLASS API

85       Your config class will do the MooseX::Configuration::Trait::Object
86       role. This adds several attributes and methods to your class.
87
88   config_file attribute
89       The "config_file" attribute defines the location of the configuration
90       file. The role supplies a builder method that you can replace,
91       "_build_config_file". It should return a string or Path::Class::File
92       object pointing to the configuration file. It can also return "undef".
93
94       If you don't provide your own builder, then the "config_file" will
95       default to "undef".
96
97   $config->_raw_config()
98       This returns the raw hash reference as read by Config::INI::Reader. If
99       no config file was defined, then this simply returns an empty hash
100       reference.
101
102   $config->write_config_file( ... )
103       This method can be used to write a configuration file. It accepts
104       several parameters:
105
106       •   file
107
108           This can be either a path or an open filehandle. The configuration
109           text will be written to this file. This defaults to the value of
110           "$self->config_file()". If no file is provided or already set in
111           the object, this method will die.
112
113       •   generated_by
114
115           If this parameter is passed, it will be included as a comment at
116           the top of the generated file.
117
118       •   values
119
120           This should be a hash reference of attribute names and values to
121           write to the config file. It is optional.
122
123       When writing the configuration file, any configuration item that was
124       set in the configuration file originally will be set in the new file,
125       as will any value passed in the "values" key. An attribute value set in
126       the constructor or by a default will not be included in the generated
127       file.
128
129       Keys without a value will still be included in the file as a comment.
130
131       If an attribute includes a documentation string, that string will
132       appear as a comment above the key. If the attribute defines a simple
133       scalar default, that will also be included in the comment, unless the
134       default is the empty string. Finally, if the attribute is required,
135       that is also mentioned in the comment.
136

DONATIONS

138       If you'd like to thank me for the work I've done on this module, please
139       consider making a "donation" to me via PayPal. I spend a lot of free
140       time creating free software, and would appreciate any support you'd
141       care to offer.
142
143       Please note that I am not suggesting that you must do this in order for
144       me to continue working on this particular software. I will continue to
145       do so, inasmuch as I have in the past, for as long as it interests me.
146
147       Similarly, a donation made in this way will probably not make me work
148       on this software much more, unless I get so many donations that I can
149       consider working on free software full time, which seems unlikely at
150       best.
151
152       To donate, log into PayPal and send money to autarch@urth.org or use
153       the button on this page:
154       <http://www.urth.org/~autarch/fs-donation.html>
155

BUGS

157       Please report any bugs or feature requests to
158       "bug-moosex-configuration@rt.cpan.org", or through the web interface at
159       <http://rt.cpan.org>.  I will be notified, and then you'll
160       automatically be notified of progress on your bug as I make changes.
161

AUTHOR

163       Dave Rolsky <autarch@urth.org>
164
166       This software is Copyright (c) 2010 by Dave Rolsky.
167
168       This is free software, licensed under:
169
170         The Artistic License 2.0
171
172
173
174perl v5.38.0                      2023-07-20          MooseX::Configuration(3)
Impressum