.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" 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" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Config::Scoped 3pm" .TH Config::Scoped 3pm "2012-03-16" "perl v5.14.2" "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" Config::Scoped \- feature rich configuration file parser .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Config::Scoped; \& \& $cs = Config::Scoped\->new( file => $config_file, ... ); \& $cfg_hash = $cs\->parse; .Ve .SH "ABSTRACT" .IX Header "ABSTRACT" \&\fBConfig::Scoped\fR is a configuration file parser. .SS "Features" .IX Subsection "Features" .IP "\(bu" 4 recursive data structures with scalars, lists, and hashes .IP "\(bu" 4 simplified syntax with minimal punctuation .IP "\(bu" 4 parses many Perl data structures without \fBeval\fR, \fBdo\fR or \fBrequire\fR .IP "\(bu" 4 Perl quoting syntax: single quotes (\fB''\fR), double quotes(\fB""\fR), and here-docs (\fB<<\s-1EOF\s0\fR) .IP "\(bu" 4 Perl code evaluation in \fBSafe\fR compartments .IP "\(bu" 4 parses \s-1ISC\s0 named and dhcpd config files .IP "\(bu" 4 include files with recursion checks .IP "\(bu" 4 controlled macro expansion in double quoted tokens .IP "\(bu" 4 lexically scoped parameter assignments and directives .IP "\(bu" 4 duplicate macro, parameter, and declaration checks .IP "\(bu" 4 file permission and ownership safety checks .IP "\(bu" 4 fine control over error checking .IP "\(bu" 4 error messages report config file names and line numbers .IP "\(bu" 4 exception-based error handling .IP "\(bu" 4 based on \fBParse::RecDescent\fR .IP "\(bu" 4 configuration caching with \s-1MD5\s0 checksums on the original files .IP "\(bu" 4 may be subclassed to build parsers with specialized features .SH "REQUIRES" .IX Header "REQUIRES" .IP "\(bu" 4 \&\fBParse::RecDescent\fR .IP "\(bu" 4 \&\fBError\fR .SH "EXPORTS" .IX Header "EXPORTS" Nothing. .SH "METHODS" .IX Header "METHODS" .IP "\fBConfig::Scoped\->new\fR" 4 .IX Item "Config::Scoped->new" .Vb 7 \& $cs = Config::Scoped\->new( \& file => $config_file, \& lc => $lc, \& safe => $compartment, \& warnings => $warnings, \& your_key => $your_value, { ... }, \& ); .Ve .Sp Creates and returns a new \fBConfig::Scoped\fR object. The following parameters are optional. .RS 4 .ie n .IP "\fB\fB$config_file\fB\fR" 4 .el .IP "\fB\f(CB$config_file\fB\fR" 4 .IX Item "$config_file" The configuration file to parse. If omitted, then a \fB\f(CB$config_string\fB\fR must be provided to the \fBparse\fR method (see below). .ie n .IP "\fB\fB$lc\fB\fR" 4 .el .IP "\fB\f(CB$lc\fB\fR" 4 .IX Item "$lc" If true, all declaration and parameter names will be converted to lower case. .ie n .IP "\fB\fB$compartment\fB\fR" 4 .el .IP "\fB\f(CB$compartment\fB\fR" 4 .IX Item "$compartment" A \fBSafe\fR compartment for evaluating Perl code blocks in the configuration file. Defaults to a \fBSafe\fR compartment with no extra shares and the \fB:default\fR operator tag. .ie n .IP "\fB\fB$warnings\fB\fR" 4 .el .IP "\fB\f(CB$warnings\fB\fR" 4 .IX Item "$warnings" may be the literal string \fB'on'\fR or \fB'off'\fR to set all warnings simultan. .Sp Or define a hash reference with the following keys to set each warning as specified. .Sp .Vb 7 \& $warnings = { declaration => \*(Aqoff\*(Aq, \& digests => \*(Aqoff\*(Aq, \& macro => \*(Aqoff\*(Aq, \& parameter => \*(Aqoff\*(Aq, \& permissions => \*(Aqoff\*(Aq, \& your_warning => \*(Aqoff\*(Aq, \& }; .Ve .Sp All warnings are on by default. .IP "\fBArbitrary key/value pairs\fR" 4 .IX Item "Arbitrary key/value pairs" will be stored in the \fB\f(CB$cs\fB\fR object. This is useful primarily for subclassing. .RE .RS 4 .RE .ie n .IP "\fB\fB$cs\fB\->parse\fR" 4 .el .IP "\fB\f(CB$cs\fB\->parse\fR" 4 .IX Item "$cs->parse" .Vb 2 \& $cfg_hash = $cs\->parse; \& $cfg_hash = $cs\->parse(text => $config_string); .Ve .Sp Parses the configuration and returns a reference to the config hash. .Sp The first form parses the \fB\f(CB$config_file\fB\fR that was provided to the constructor. If \fB\f(CB$config_file\fB\fR was not provided to the constructor, this form \fBdie\fRs. .Sp The second form parses the \fB\f(CB$config_string\fB\fR. .Sp This method must only be called once. .ie n .IP "\fB\fB$cs\fB\->store_cache\fR" 4 .el .IP "\fB\f(CB$cs\fB\->store_cache\fR" 4 .IX Item "$cs->store_cache" .Vb 2 \& $cs\->store_cache; \& $cs\->store_cache(cache => $cache_file); .Ve .Sp Stores the config hash on disk for rapid retrieval. If \fB\f(CB$config_file\fB\fR was provided to the constructor, then the stored form includes checksums of \fB\f(CB$config_file\fB\fR and any included files. .Sp The first form writes to \fB\f(CB$config_file\fB.dump\fR The second form writes to \fB\f(CB$cache_file\fB\fR. .Sp If \fB\f(CB$config_file\fB\fR was not provided to the constructor, the first form \fBdie\fRs. .ie n .IP "\fB\fB$cs\fB\->retrieve_cache\fR" 4 .el .IP "\fB\f(CB$cs\fB\->retrieve_cache\fR" 4 .IX Item "$cs->retrieve_cache" .Vb 2 \& $cfg_hash = $cs\->retrieve_cache; \& $cfg_hash = $cs\->retrieve_cache>(cache => $cache_file); .Ve .Sp Retrieves the \fB\f(CB$config\fB\fR hash from a file that was created by \fBstore_cache\fR. .Sp The first form reads \fB\f(CB$config_file\fB.dump\fR The second form reads \fB\f(CB$cache_file\fB\fR. .Sp If \fB\f(CB$config_file\fB\fR was not provided to the constructor, the first form \fBdie\fRs. .Sp The stored file is subject to \fBdigests\fR and \fBpermissions\fR checks. .ie n .IP "\fB\fB$cs\fB\->set_warnings\fR" 4 .el .IP "\fB\f(CB$cs\fB\->set_warnings\fR" 4 .IX Item "$cs->set_warnings" .Vb 1 \& $cs\->set_warnings(name => $name, switch => \*(Aqon|off\*(Aq); .Ve .Sp Change warning for \fB\f(CB$name\fB\fR after construction. .ie n .IP "\fB\fB$cs\fB\->warnings_on\fR" 4 .el .IP "\fB\f(CB$cs\fB\->warnings_on\fR" 4 .IX Item "$cs->warnings_on" .Vb 1 \& $on = $cs\->warnings_on(name => $name); .Ve .Sp Returns true if warning \fB\f(CB$name\fB\fR is on. This is useful primarily for subclassing. .SH "EXCEPTIONS" .IX Header "EXCEPTIONS" All methods \fBdie\fR on error. .PP \&\fBConfig::Scoped::Error\fR defines a hierarchy of classes that represent \fBConfig::Scoped\fR errors. When a method detects an error, it creates an instance of the corresponding class and throws it. The error classes are all subclasses of \fBConfig::Scoped::Error\fR. See Config::Scoped::Error for the complete list. .PP If the exception is not caught, the program terminates, and \fBConfig::Scoped\fR prints the config file name and line number where the error was detected to \fB\s-1STDERR\s0\fR. .SH "CONFIG FILE FORMAT" .IX Header "CONFIG FILE FORMAT" \&\fBConfig::Scoped\fR parses configuration files. .PP If we have a config file like .PP .Vb 6 \& % cat host.cfg \& host { \& name = cpan.org \& port = 22 \& } \& % .Ve .PP we can parse it into Perl with code like .PP .Vb 2 \& $cs = Config::Scoped\->new( file => \*(Aqhost.cfg\*(Aq ); \& $cfg_hash = $cs\->parse; .Ve .PP The result is always a hash ref. We'll call this the \fBconfig hash\fR, and its contents for the example file above is: .PP .Vb 6 \& $cfg_hash = { \& host => { \& name => \*(Aqcpan.org\*(Aq, \& port => 22, \& } \& } .Ve .SS "Config files and config strings" .IX Subsection "Config files and config strings" As described, \fBConfig::Scoped\fR can obtain a configuration from a \fB\f(CB$config_file\fB\fR, passed to the constructor, or from a \fB\f(CB$config_string\fB\fR, passed to the \fBparse\fR method. For simplicity, we'll talk about parsing configuration files, distinguishing configuration strings only when necessary. .SS "File layout" .IX Subsection "File layout" Config files are free-form text files. Comments begin with \fB#\fR, and extend to the end of the line. .SS "Declarations" .IX Subsection "Declarations" The top-level elements of a config file are called \fBdeclarations\fR. A declaration consists of a name, followed by a block .PP .Vb 2 \& foo { \& } \& \& bar { \& } .Ve .PP The declaration names become keys in the config hash. The value of each key is another hash ref. The config shown above parses to .PP .Vb 4 \& $cfg_hash = { \& foo => {}, \& bar => {}, \& } .Ve .PP You can create additional levels in the config hash simply by listing successive declaration names before the block. This config .PP .Vb 2 \& dog hound { \& } \& \& dog beagle { \& } \& \& cat { \& } .Ve .PP parses to .PP .Vb 5 \& $cfg_hash = { \& dog => { \& hound => {}, \& beagle => {}, \& }, \& \& cat => {} \& } .Ve .PP Declarations may not be nested. .SS "Parameters" .IX Subsection "Parameters" The ultimate purpose of a configuration file is to provide data values for a program. These values are specified by \fBparameters\fR. .PP Parameters have the form .PP .Vb 1 \& name = value .Ve .PP and go inside declaration blocks. The .PP .Vb 1 \& name = value .Ve .PP parameters in a spec file become key and value pairs inside the declaration hashes in Perl code. .PP For example, this configuration .PP .Vb 4 \& dog { \& legs = 4 \& wings = 0 \& } \& \& bird { \& legs = 2 \& wings = 2 \& } .Ve .PP parses to .PP .Vb 5 \& $cfg_hash = { \& dog => { \& legs => 4, \& wings => 0, \& }, \& \& bird => { \& legs => 2, \& wings => 2, \& } \& } .Ve .PP \&\fBParameter values\fR can be \fBscalars\fR, \fBlists\fR or \fBhashes\fR. .PP Scalar values may be numbers or strings .PP .Vb 2 \& shape = square \& sides = 4 .Ve .PP Lists values are enclosed in square brackets .PP .Vb 2 \& colors = [ red green blue ] \& primes = [ 2 3 5 7 11 13 ] .Ve .PP Hash values are enclosed in curly brackets .PP .Vb 4 \& capitals = { \& England => London \& France => Paris \& } .Ve .PP A hash value is also called a \fBhash block\fR. .PP Lists and hashes can be nested to arbitrary depth .PP .Vb 2 \& Europe { \& currency = euro \& \& cities = { \& England => [ London Birmingham Liverpool ] \& France => [ Paris Canne Calais ] \& } \& } .Ve .PP parses to .PP .Vb 3 \& $cfg_hash = { \& Europe => { \& currency => \*(Aqeuro\*(Aq, \& \& cities => { \& England => [ \*(AqLondon\*(Aq, \*(AqBirmingham\*(Aq, \*(AqLiverpool\*(Aq ], \& France => [ \*(AqParis\*(Aq, \*(AqCanne\*(Aq, \*(AqCalais\*(Aq ], \& } \& } \& } .Ve .PP The \fBConfig::Scoped\fR data syntax is similar to the Perl data syntax, and \fBConfig::Scoped\fR will parse many Perl data structures. In general, \fBConfig::Scoped\fR requires less punctuation that Perl. Note that \fBConfig::Scoped\fR allows arrow (\fB=>\fR) or equals (\fB=\fR) between hash keys and values, but not comma (\fB,\fR) .PP .Vb 4 \& capitals = { England => London # OK \& France = Paris # OK \& Germany , Berlin # error \& } .Ve .SS "_GLOBAL" .IX Subsection "_GLOBAL" If a config file contains no declarations at all .PP .Vb 2 \& name = cpan.org \& port = 22 .Ve .PP then any parameters will be placed in a \fB_GLOBAL\fR declaration in the config hash .PP .Vb 6 \& $cfg_hash = { \& _GLOBAL => { \& name => \*(Aqcpan.org\*(Aq, \& port => 22, \& } \& } .Ve .PP This allows very simple config files with just parameters and no declarations. .SS "Blocks, scoping and inheritance" .IX Subsection "Blocks, scoping and inheritance" Each declaration block in a config file creates a lexical scope. Parameters inside a declaration are scoped to that block. Parameters are inherited by all following declarations within their scope. .PP If all your animals have four legs, you can save some typing by writing .PP .Vb 3 \& legs = 4 \& cat {} \& dog {} .Ve .PP which parses to .PP .Vb 4 \& $cfg_hash = { \& cat => { legs => 4 }, \& dog => { legs => 4 }, \& } .Ve .PP If some of your animals have two legs, you can create additional scopes with anonymous blocks to control inheritance .PP .Vb 9 \& { \& legs = 4 \& cat {} \& dog {} \& } \& { \& legs = 2 \& bird {} \& } .Ve .PP parses to .PP .Vb 5 \& $cfg_hash = { \& cat => { legs => 4 }, \& dog => { legs => 4 }, \& bird => { legs => 2 }, \& } .Ve .PP Anonymous blocks may be nested. .PP Each hash block also creates a scope. The hash does not inherit parameters from outside its own scope. .SS "Perl code evaluation" .IX Subsection "Perl code evaluation" If you can't express what you need within the \fBConfig::Scoped\fR syntax, your escape hatch is .PP .Vb 1 \& eval { ... } .Ve .PP This does a Perl \fBeval\fR on the block, and replaces the construct with the results of the \fBeval\fR. .PP .Vb 2 \& start = eval { localtime } \& foo = eval { warn \*(Aqfoo,\*(Aq if $debug; return \*(Aqbar\*(Aq } .Ve .PP The block is evaluated in scalar context. However, it may return a list or hash reference, and the underlying list or hash can become a parameter value. .PP For example .PP .Vb 4 \& foo { \& list = eval { [ 1 .. 3 ] } \& hash = eval { { a => 1, b => 2, c => 3 } } \& } .Ve .PP parses to .PP .Vb 6 \& $cfg_hash = { \& foo => { \& list => [ 1, 2, 3 ], \& hash => { a => 1, b => 2, c => 3 }, \& } \& } .Ve .PP The block is evaluated inside the parser's \fBSafe\fR compartment. Variables can be made available to the \fBeval\fR by sharing them with the compartment. .PP To set the \fB\f(CB$debug\fB\fR variable in the example above, do .PP .Vb 2 \& $compartment = Safe\->new(\*(AqMY_SHARE\*(Aq); \& $MY_SHARE::debug = 1; \& \& $cs = Config::Scoped\->new( \& file => \*(Aqconfig.txt\*(Aq, \& safe => $compartment, \& ); \& \& $cfg_hash = $cs\->parse; .Ve .PP Only global variables can be shared with a compartment; lexical variables cannot. .PP \&\fBperl_code\fR is a synonym for \fBeval\fR. .SS "Tokens and quoting" .IX Subsection "Tokens and quoting" A \fBtoken\fR is a .IP "\(bu" 4 declaration name .IP "\(bu" 4 parameter name .IP "\(bu" 4 hash key .IP "\(bu" 4 scalar value .IP "\(bu" 4 macro name .IP "\(bu" 4 macro value .IP "\(bu" 4 include path .IP "\(bu" 4 warning name .PP Any token may be quoted. .PP Tokens that contain special characters must be quoted. The special characters are .PP .Vb 1 \& \es {} [] <> () ; , \*(Aq " = # % .Ve .PP \&\fBConfig::Scoped\fR uses the Perl quoting syntax. .PP Tokens may be quoted with either single or double quotes .PP .Vb 2 \& a = \*(AqNew York\*(Aq \& b = "New Jersey\en" .Ve .PP Here-docs are supported .PP .Vb 4 \& a = < { bc => 1 } } .Ve .SH "DIRECTIVES" .IX Header "DIRECTIVES" \&\fBConfig::Scoped\fR has three directives: \fB\f(CB%macro\fB\fR, \fB\f(CB%warning\fB\fR, and \fB\f(CB%include\fB\fR. .SS "Macros" .IX Subsection "Macros" \&\fBConfig::Scoped\fR supports macros. A macro is defined with .PP .Vb 1 \& %macro name value .Ve .PP Macros may be defined .IP "\(bu" 4 at file scope .IP "\(bu" 4 within anonymous blocks .IP "\(bu" 4 within declaration blocks .IP "\(bu" 4 within hash blocks .PP Macros defined within blocks are lexically scoped to those blocks. .PP Macro substitution occurs .IP "\(bu" 4 within \fBany\fR double-quoted text .IP "\(bu" 4 within the \fBentirety\fR of Perl \fBeval\fR blocks .IP "\(bu" 4 nowhere else .SS "Include files" .IX Subsection "Include files" \&\fBConfig::Scoped\fR supports include files. .PP To include one config file within another, write .PP .Vb 1 \& %include path/to/file .Ve .PP \&\fB\f(CB%include\fB\fR directives may appear .IP "\(bu" 4 at file scope .IP "\(bu" 4 within anonymous blocks .IP "\(bu" 4 nowhere else .PP In particular, \fB\f(CB%include\fB\fR directives may not appear within declaration blocks or hash blocks. .PP Parameters and macros in include files are imported to the current scope. You can control this scope with an anonymous block .PP .Vb 5 \& { \& %include dog.cfg \& dog { } # sees imports from dog.cfg \& } \& bird { } # does not see imports from dog.cfg .Ve .PP Warnings are scoped to the included file and do not leak to the parent file. .PP Pathnames are either .IP "\(bu" 4 absolute .IP "\(bu" 4 relative to the dirname of the current configuration file .PP For example, this config .PP .Vb 2 \& # in configuration file /etc/myapp/global.cfg \& %include shared.cfg .Ve .PP includes the file \fI/etc/myapp/shared.cfg\fR. .PP When parsing a configuration string, the path is relative to the current working directory. .PP Include files are not actually included as text. Rather, they are processed by a recursive call to \fBConfig::Scoped\fR. Subclass implementers may need to be aware of this. .SS "Warnings" .IX Subsection "Warnings" \&\fBConfig::Scoped\fR can check for 5 problems with config files .IP "\(bu" 4 duplicate declaration names .IP "\(bu" 4 duplicate parameter definitions .IP "\(bu" 4 duplicate macro definitions .IP "\(bu" 4 insecure config file permissions .IP "\(bu" 4 invalid config cache digests .PP The \s-1API\s0 refers to these as \*(L"warnings\*(R", but they are actually errors, and if they occur, the parse fails and throws an exception. For consistency with the \s-1API\s0, we'll use the term \*(L"warning\*(R" in the \s-1POD\s0. .PP The five warnings are identified by five predefined \fBwarning names\fR .IP "\(bu" 4 \&\fBdeclaration\fR .IP "\(bu" 4 \&\fBparameter\fR .IP "\(bu" 4 \&\fBmacro\fR .IP "\(bu" 4 \&\fBpermissions\fR .IP "\(bu" 4 \&\fBdigests\fR .PP The \fBpermissions\fR check requires that the config file .IP "\(bu" 4 be owned by root or the real \s-1UID\s0 of the running process \s-1AND\s0 .IP "\(bu" 4 have no group or world write permissions .PP These restrictions help prevent an attacker from subverting a program by altering its config files. .PP The \fBstore_cache\fR method computes \s-1MD5\s0 checksums for the config file and all included files. These checksums are stored with the cached configuration. .PP The \fBretrieve_cache\fR method recomputes the checksums of the files and compares them to the stored values. .PP The \fBdigests\fR check requires that the checksums agree. This helps prevent programs from relying on stale configuration caches. .PP All warnings are enabled by default. .PP Warnings can be disabled by passing the \fBwarning\fR key to the constructor or with the \fBset_warnings\fR method. .PP Warnings can also be controlled with the \fB\f(CB%warnings\fB\fR directive, which has the form .PP \&\fB\f(CB%warnings\fB\fR [\fBname\fR] \fBoff\fR|\fBon\fR .PP A \fB\f(CB%warnings\fB\fR directive applies to the \fBname\fRd warning, or to all warnings, if \fBname\fR is omitted. .PP \&\fB\f(CB%warnings\fB\fR directives allow warnings to be turned on and off as necessary throughout the config file. A \fB\f(CB%warnings\fB\fR directive may appear .IP "\(bu" 4 at file scope .IP "\(bu" 4 within anonymous blocks .IP "\(bu" 4 within declaration blocks .IP "\(bu" 4 within hash blocks .PP Each \fB\f(CB%warnings\fB\fR directive is lexically scoped to its enclosing file or block. .PP Example .PP .Vb 7 \& legs = 4 \& cat {} \& dog {} \& bird \& { \& legs = 2 \& } .Ve .PP fails with a duplicate parameter warning, but .PP .Vb 8 \& legs = 4 \& cat {} \& dog {} \& bird \& { \& %warnings parameter off; \& legs = 2 \& } .Ve .PP successfully parses to .PP .Vb 5 \& $cfg_hash = { \& cat => { legs => 4 }, \& dog => { legs => 4 }, \& bird => { legs => 2 }, \& } .Ve .SH "Best practices" .IX Header "Best practices" As with all things Perl, there's more than one way to write configuration files. Here are some suggestions for writing config files that are concise, readable, and maintainable. .SS "Perl data" .IX Subsection "Perl data" \&\fBConfig::Scoped\fR accepts most Perl data syntax. This allows Perl data to pulled into config files largely unaltered .PP .Vb 7 \& foo \& { \& a = 1; \& b = [ \*(Aqred\*(Aq, \*(Aqgreen\*(Aq, \*(Aqblue\*(Aq ]; \& c = { x => 5, \& y => 6 }; \& } .Ve .PP However, \fBConfig::Scoped\fR doesn't require as much punctuation as Perl, and config files written from scratch will be cleaner without it .PP .Vb 7 \& foo \& { \& a = 1 \& b = [ red green blue ] \& c = { x => 5 \& y => 6 } \& } .Ve .SS "Anonymous blocks" .IX Subsection "Anonymous blocks" Don't use anonymous blocks unless you need to restrict the scope of something. In particular, there is no need for a top-level anonymous block around the whole config file .PP .Vb 3 \& { # unnecessary \& foo { } \& } .Ve .SS "Inheritance" .IX Subsection "Inheritance" Parameters that are outside of a declaration are inherited by \fBall\fR following declarations in their scope. Don't do this unless you mean it .PP .Vb 9 \& wheels = 4 \& car \& { \& # OK \& } \& cat \& { \& # I can haz weelz? \& } .Ve .SS "Blocks, blocks, we got blocks..." .IX Subsection "Blocks, blocks, we got blocks..." \&\fBConfig::Scoped\fR has four different kinds of blocks .IP "\(bu" 4 anonymous .IP "\(bu" 4 declaration .IP "\(bu" 4 eval .IP "\(bu" 4 hash .PP They all look the same, but they aren't, and they have different rules and restrictions. See \*(L"\s-1CONFIG\s0 \s-1FILE\s0 \s-1FORMAT\s0\*(R" for descriptions of each. .SS "Macros" .IX Subsection "Macros" Macros are evil, and \fBConfig::Scoped\fR macros are specially evil, because .IP "\(bu" 4 they don't respect token boundaries .IP "\(bu" 4 where multiple substitutions are possible, the substitution order is undefined .IP "\(bu" 4 substituted text may or may not be rescanned for further substitutions .PP Caveat scriptor. .SH "SUBCLASSING" .IX Header "SUBCLASSING" \&\fBConfig::Scoped\fR has no formally defined subclass interface. Here are some guidelines for writing subclasses. Implementers who override (or redefine) base class methods may need to read the \fBConfig::Scoped\fR sources for more information. .PP Arbitrary .PP .Vb 1 \& $your_key => $value .Ve .PP pairs may be passed to the \fBConfig::Scoped\fR constructor. They will be stored in the \fB\f(CB$cs\fB\->{local}\fR hashref, and methods may access them with code like .PP .Vb 1 \& $cs\->{local}{$your_key} .Ve .PP To avoid conflict with existing keys in the \fBlocal\fR hash, consider distinguishing your keys with a unique prefix. .PP Arbitrary warning names may be defined, set with \fBnew\fR and \fBset_warnings\fR, used in \fB\f(CB%warnings\fB\fR directives, and tested with \fBwarnings_on\fR. Methods can call \fBwarnings_on\fR to find out whether a warning is currently enabled. .PP All methods throw exceptions (\fBdie\fR) on error. The exception object should be a subclass of \fBConfig::Scoped::Error\fR. You can use one of the classes defined in \fBConfig::Scoped::Error\fR, or you can derive your own. This code .PP .Vb 5 \& Config::Scoped::Error\->throw( \& \-file => $cs\->_get_file(%args), \& \-line => $cs\->_get_line(%args), \& \-text => $message, \& ); .Ve .PP will generate an error message that reports the location in the config file where the error was detected, rather than a location in Perl code. .PP \&\fBConfig::Scoped\fR performs validation checks on the elements of configuration files (declarations, parameters, macros, etc). Here are the interfaces to the validation methods. Subclasses can override these methods to modify or extend the validation checks. .ie n .IP "\fB\fB$macro_value\fB = \f(BI$cs\fB\->macro_validate>(name => \f(CB$name\fB, value => \f(CB$value\fB)\fR" 4 .el .IP "\fB\f(CB$macro_value\fB = \f(CB$cs\fB\->macro_validate>(name => \f(CB$name\fB, value => \f(CB$value\fB)\fR" 4 .IX Item "$macro_value = $cs->macro_validate>(name => $name, value => $value)" Called for each \fB\f(CB%macro\fB\fR directive. .Sp Receives the \fB\f(CB$name\fB\fR and \fB\f(CB$value\fB\fR from the directive. The returned \fB\f(CB$macro_value\fB\fR becomes the actual value of the macro. .Sp If the macro is invalid, throws a \fBConfig::Scoped::Error::Validate::Macro\fR exception. .ie n .IP "\fB\fB$param_value\fB = \f(BI$cs\fB\->parameter_validate>(name => \f(CB$name\fB, value => \f(CB$value\fB)\fR" 4 .el .IP "\fB\f(CB$param_value\fB = \f(CB$cs\fB\->parameter_validate>(name => \f(CB$name\fB, value => \f(CB$value\fB)\fR" 4 .IX Item "$param_value = $cs->parameter_validate>(name => $name, value => $value)" Called for each parameter definition. .Sp Receives the \fB\f(CB$name\fB\fR and \fB\f(CB$value\fB\fR from the definition. The returned \fB\f(CB$param_value\fB\fR becomes the actual value of the parameter. .Sp If the parameter is invalid, throws a \fBConfig::Scoped::Error::Validate::Parameter\fR exception. .ie n .IP "\fB\fB$cs\fB\->declaration_validate(name => \f(BI$name\fB, value => \f(CB$value\fB, tail => \f(CB$tail\fB)\fR" 4 .el .IP "\fB\f(CB$cs\fB\->declaration_validate(name => \f(CB$name\fB, value => \f(CB$value\fB, tail => \f(CB$tail\fB)\fR" 4 .IX Item "$cs->declaration_validate(name => $name, value => $value, tail => $tail)" Called for each declaration. .Sp \&\fB\f(CB$name\fB\fR is an array ref giving the chain of names for the declaration block. \fB\f(CB$value\fB\fR is a hash ref containing all the parameters in the declaration block. \fB\f(CB$tail\fB\fR is a hash ref containing all the parameters in any previously defined declaration with the same name(s). .Sp For example, the declaration .Sp .Vb 1 \& foo bar baz { a=1 b=2 } .Ve .Sp leads to the call .Sp .Vb 3 \& $cs\->declaration_validate(name => [ qw(foo bar baz) ], \& value => { a => \*(Aq1\*(Aq, b => \*(Aq2\*(Aq }, \& tail => $cs\->{local}{config}{foo}{bar}{baz}); .Ve .Sp The method can test %$tail to discover if there is an existing, non-empty declaration with the same name(s). .Sp The method has no return value. However, the method can alter the contents of %$value. Upon return, the parameters in %$value become the actual contents of the declaration block. .Sp If the declaration is invalid, throws a \fBConfig::Scoped::Error::Validate::Declaration\fR exception. .ie n .IP "\fB\fB$cs\fB\->permissions_validate(file => \f(BI$file\fB, handle => \f(CB$handle\fB)\fR" 4 .el .IP "\fB\f(CB$cs\fB\->permissions_validate(file => \f(CB$file\fB, handle => \f(CB$handle\fB)\fR" 4 .IX Item "$cs->permissions_validate(file => $file, handle => $handle)" Called for the config file, each included file, and each retrieved cache file. One of \fB\f(CB$file\fB\fR or \fB\f(CB$handle\fB\fR must be non-null. .Sp Throws a \fBConfig::Scoped::Error::Validate::Permissions\fR exception if the file is not safe to read. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 \&\fBError\fR .IP "\(bu" 4 \&\fBSafe\fR .IP "\(bu" 4 \&\fBConfig::Scoped::Error\fR .IP "\(bu" 4 \&\fBParse::RecDescent\fR .IP "\(bu" 4 \&\*(L"Quote and Quote-like Operators\*(R" in perlop .SH "TODO" .IX Header "TODO" .IP "Tests" 4 .IX Item "Tests" Still more tests needed. .SH "BUGS" .IX Header "BUGS" If you find parser bugs, please send the stripped down config file and additional version information to the author. .SH "CREDITS" .IX Header "CREDITS" \&\s-1POD\s0 by Steven W. McDougall .SH "AUTHOR" .IX Header "AUTHOR" Karl Gaissmaier .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (c) 2004\-2012 by Karl Gaissmaier .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.