.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "MooseX::Configuration 3pm" .TH MooseX::Configuration 3pm "2022-06-15" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" MooseX::Configuration \- Define attributes which come from configuration files .SH "VERSION" .IX Header "VERSION" version 0.02 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& package MyApp::Config; \& \& use Moose; \& use MooseX::Configuration; \& \& has database_name => ( \& is => \*(Aqro\*(Aq, \& isa => \*(AqStr\*(Aq, \& default => \*(AqMyApp\*(Aq, \& section => \*(Aqdatabase\*(Aq, \& key => \*(Aqname\*(Aq, \& documentation => \& \*(AqThe name of the database.\*(Aq, \& ); \& \& has database_username => ( \& is => \*(Aqro\*(Aq, \& isa => Str, \& default => q{}, \& section => \*(Aqdatabase\*(Aq, \& key => \*(Aqusername\*(Aq, \& documentation => \& \*(AqThe username to use when connecting to the database. By default, this is empty.\*(Aq, \& ); \& \& my $config = MyApp::Config\->new( config_file => \*(Aq/path/to/config/myapp.ini\*(Aq ); \& $config\->write_file( ... ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module lets you define attributes which can come from a configuration file. It also adds a role to your class which allows you to write a configuration file. .PP It is based on using a simple INI-style configuration file, which contains sections and keys: .PP .Vb 2 \& key1 = value \& key2 = 42 \& \& [section] \& key3 = 2 .Ve .SH "ATTRIBUTE API" .IX Header "ATTRIBUTE API" Simply using this module in your class changes your class's attribute metaclass to add support for defining attributes as configuration items. .PP There are two new parameters you can pass when defining an attribute, \&\f(CW\*(C`section\*(C'\fR and \f(CW\*(C`key\*(C'\fR. These tell the module how to find the attribute's value in the configuration file. The \f(CW\*(C`section\*(C'\fR parameter is optional. If you don't set it, but \fIdo\fR provide a key, then the section defaults to \f(CW\*(C`_\*(C'\fR, which is the main section of the config file. .PP If you pass a \f(CW\*(C`section\*(C'\fR you must also pass a \f(CW\*(C`key\*(C'\fR. .PP Defining an attribute as a configuration item has several effects. First, it changes the default value for the attribute. Before looking at a \f(CW\*(C`default\*(C'\fR or \&\f(CW\*(C`builder\*(C'\fR you define, the attribute will first look in the config file for a corresponding value. If one exists, it will use that, otherwise it will fall back to using a default you supply. .PP If you do supply a default, it must be a string (or number), not a reference or undefined value. .PP All configuration attributes are lazy. This is necessary because the configuration file needs to be loaded and parsed before looking up values. .PP The \f(CW\*(C`documentation\*(C'\fR string is used when generating a configuration file. See below for details. .SH "CLASS API" .IX Header "CLASS API" Your config class will do the MooseX::Configuration::Trait::Object role. This adds several attributes and methods to your class. .SS "config_file attribute" .IX Subsection "config_file attribute" The \f(CW\*(C`config_file\*(C'\fR attribute defines the location of the configuration file. The role supplies a builder method that you can replace, \&\f(CW\*(C`_build_config_file\*(C'\fR. It should return a string or Path::Class::File object pointing to the configuration file. It can also return \f(CW\*(C`undef\*(C'\fR. .PP If you \fIdon't\fR provide your own builder, then the \f(CW\*(C`config_file\*(C'\fR will default to \f(CW\*(C`undef\*(C'\fR. .ie n .SS "$config\->\fB_raw_config()\fP" .el .SS "\f(CW$config\fP\->\fB_raw_config()\fP" .IX Subsection "$config->_raw_config()" This returns the raw hash reference as read by Config::INI::Reader. If no config file was defined, then this simply returns an empty hash reference. .ie n .SS "$config\->write_config_file( ... )" .el .SS "\f(CW$config\fP\->write_config_file( ... )" .IX Subsection "$config->write_config_file( ... )" This method can be used to write a configuration file. It accepts several parameters: .IP "\(bu" 4 file .Sp This can be either a path or an open filehandle. The configuration text will be written to this file. This defaults to the value of \f(CW\*(C`$self\->config_file()\*(C'\fR. If no file is provided or already set in the object, this method will die. .IP "\(bu" 4 generated_by .Sp If this parameter is passed, it will be included as a comment at the top of the generated file. .IP "\(bu" 4 values .Sp This should be a hash reference of attribute names and values to write to the config file. It is optional. .PP When writing the configuration file, any configuration item that was set in the configuration file originally will be set in the new file, as will any value passed in the \f(CW\*(C`values\*(C'\fR key. An attribute value set in the constructor or by a default will \fInot\fR be included in the generated file. .PP Keys without a value will still be included in the file as a comment. .PP If an attribute includes a documentation string, that string will appear as a comment above the key. If the attribute defines a simple scalar default, that will also be included in the comment, unless the default is the empty string. Finally, if the attribute is required, that is also mentioned in the comment. .SH "DONATIONS" .IX Header "DONATIONS" If you'd like to thank me for the work I've done on this module, please consider making a \*(L"donation\*(R" to me via PayPal. I spend a lot of free time creating free software, and would appreciate any support you'd care to offer. .PP Please note that \fBI am not suggesting that you must do this\fR in order for me to continue working on this particular software. I will continue to do so, inasmuch as I have in the past, for as long as it interests me. .PP Similarly, a donation made in this way will probably not make me work on this software much more, unless I get so many donations that I can consider working on free software full time, which seems unlikely at best. .PP To donate, log into PayPal and send money to autarch@urth.org or use the button on this page: .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \&\f(CW\*(C`bug\-moosex\-configuration@rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "AUTHOR" .IX Header "AUTHOR" Dave Rolsky .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2010 by Dave Rolsky. .PP This is free software, licensed under: .PP .Vb 1 \& The Artistic License 2.0 .Ve