.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" 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 "ConfigReader::Simple 3pm" .TH ConfigReader::Simple 3pm "2021-01-15" "perl v5.32.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" ConfigReader::Simple \- A simple line\-oriented configuration file parser .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use ConfigReader::Simple; \& \& # parse one file \& $config = ConfigReader::Simple\->new("configrc", [qw(Foo Bar Baz Quux)]); \& \& # parse multiple files, in order \& $config = ConfigReader::Simple\->new_multiple( \& Files => [ "global", "configrc" ], \& Keys => [qw(Foo Bar Baz Quux)] \& ); \& \& my @directives = $config\->directives; \& \& $config\->get( "Foo" ); \& \& if( $config\->exists( "Bar" ) ) { \& print "Bar was in the config file\en"; \& } \& \& # copy an object to play with it separately \& my $clone = $config\->clone; \& \& # only affects clone \& $clone\->set( "Foo", "Buster" ); \& \& # save the config to a single file \& $clone\->save( "configrc" ) \& \& # save the config to a single file, but only with \& # certain directives \& $clone\->save( "configrc" => [qw(Foo Bar)] ) \& \& # save to multiple configuration files \& $clone\->save( \& "configrc" => [qw(Foo Bar)], \& "global" => [qw(Baz Quux)], \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`ConfigReader::Simple\*(C'\fR reads and parses simple configuration files. It is designed to be smaller and simpler than the \f(CW\*(C`ConfigReader\*(C'\fR module and is more suited to simple configuration files. .SS "The configuration file format" .IX Subsection "The configuration file format" The configuration file uses a line-oriented format, meaning that the directives do not have containers. The values can be split across lines with a continuation character, but for the most part everything ends up on the same line. .PP The first group of non-whitespace characters is the \&\*(L"directive\*(R", or the name of the configuration item. The linear whitespace after that separates the directive from the \*(L"value\*(R", which is the rest of the line, including any other whitespace. .PP In this example, the directive is \*(L"Camel\*(R" and the value is \&\*(L"Dromedary\*(R". .PP .Vb 1 \& Camel Dromedary .Ve .PP Optionally, you can use a equal sign to separate the directive from the value. .PP .Vb 1 \& Camel=Dromedary .Ve .PP The equal sign can also have whitespace on either or both sides. .PP .Vb 2 \& Camel = Dromedary \& Camel= Dromedary .Ve .PP In the next example, the directive is \*(L"Llama\*(R" and the value is \*(L"Live from Peru\*(R" .PP .Vb 1 \& Llama Live from Peru .Ve .PP This is the same, to \f(CW\*(C`ConfigReader::Simple\*(C'\fR, as the following which has more whitespace between the directive and the value. .PP .Vb 1 \& Llama Live from Peru .Ve .PP You can also enclose the value in single or double quotes. .PP .Vb 3 \& Llama "Live from Peru" \& Llama \*(AqLive from Peru\*(Aq \& Llama=\*(AqLive from Peru\*(Aq .Ve .PP In some cases you may want to split the logical line across two lines, perhaps to see it better in a terminal window. For that, use a \e followed only by whitespace. To split the last entry across two lines, we use the \e at the end of the line. These three entries are the same: .PP .Vb 1 \& Llama Live from Peru \& \& Llama Live from \e \& Peru \& \& Llama Live \e \& from \e \& Peru .Ve .PP If a line is only whitespace, or the first non-whitespace character is a #, the Perl comment character, \f(CW\*(C`ConfigReader::Simple\*(C'\fR ignores the line unless it is the continuation of the previous line. .SS "Methods" .IX Subsection "Methods" .IP "new ( \s-1FILENAME, DIRECTIVES\s0 )" 4 .IX Item "new ( FILENAME, DIRECTIVES )" Creates a \f(CW\*(C`ConfigReader::Simple\*(C'\fR object. .Sp \&\f(CW\*(C`FILENAME\*(C'\fR tells the instance where to look for the configuration file. If \s-1FILENAME\s0 cannot be found, an error message for the file is added to the \f(CW%ERROR\fR hash with the \&\s-1FILENAME\s0 as a key, and a combined error message appears in \&\f(CW$ERROR\fR. .Sp \&\f(CW\*(C`DIRECTIVES\*(C'\fR is an optional argument and is a reference to an array. Each member of the array should contain one valid directive. A directive is the name of a key that must occur in the configuration file. If it is not found, the method croaks. The directive list may contain all the keys in the configuration file, a sub set of keys or no keys at all. .Sp The \f(CW\*(C`new\*(C'\fR method is really a wrapper around \f(CW\*(C`new_multiple\*(C'\fR. .IP "new_multiple( Files => \s-1ARRAY_REF,\s0 Keys => \s-1ARRAY_REF\s0 )" 4 .IX Item "new_multiple( Files => ARRAY_REF, Keys => ARRAY_REF )" Create a configuration object from several files listed in the anonymous array value for the \f(CW\*(C`Files\*(C'\fR key. The module reads the files in the same order that they appear in the array. Later values override earlier ones. This allows you to specify global configurations which you may override with more specific ones: .Sp .Vb 3 \& ConfigReader::Simple\->new_multiple( \& Files => [ qw( /etc/config /usr/local/etc/config /home/usr/config ) ], \& ); .Ve .Sp This function croaks if the values are not array references. .Sp If this method cannot read a file, an error message for that file is added to the \f(CW%ERROR\fR hash with the filename as a key, and a combined error message appears in \f(CW$ERROR\fR. Processing the list of filenames continues if a file cannot be found, which may produced undesired results. You can disable this feature by setting the \f(CW$ConfigReader::Simple::Die\fR variable to a true value. .IP "new_string( Strings => \s-1ARRAY_REF,\s0 Keys => \s-1ARRAY_REF\s0 )" 4 .IX Item "new_string( Strings => ARRAY_REF, Keys => ARRAY_REF )" Create a configuration object from several strings listed in the anonymous array value for the \f(CW\*(C`Strings\*(C'\fR key. The module reads the strings in the same order that they appear in the array. Later values override earlier ones. This allows you to specify global configurations which you may override with more specific ones: .Sp .Vb 3 \& ConfigReader::Simple\->new_strings( \& Strings => [ \e$global, \e$local ], \& ); .Ve .Sp This function croaks if the values are not array references. .IP "add_config_file( \s-1FILENAME\s0 )" 4 .IX Item "add_config_file( FILENAME )" Parse another configuration file and add its directives to the current configuration object. Any directives already defined will be replaced with the new values found in \s-1FILENAME.\s0 .IP "files" 4 .IX Item "files" Return the list of configuration files associated with this object. The order of the return values is the order of parsing, so the first value is the first file parsed (and subsequent files may mask it). .IP "new_from_prototype(" 4 .IX Item "new_from_prototype(" Create a clone object. This is the same thing as calling \&\fBclone()\fR. .IP "parse( \s-1FILENAME\s0 )" 4 .IX Item "parse( FILENAME )" This does the actual work. .Sp This is automatically called from \f(CW\*(C`new()\*(C'\fR, although you can reparse the configuration file by calling \f(CW\*(C`parse()\*(C'\fR again. .IP "parse_string( \s-1SCALAR_REF\s0 )" 4 .IX Item "parse_string( SCALAR_REF )" Parses the string inside the reference \s-1SCALAR_REF\s0 just as if it found it in a file. .IP "get( \s-1DIRECTIVE\s0 )" 4 .IX Item "get( DIRECTIVE )" Returns the parsed value for that directive. For directives which did not have a value in the configuration file, \f(CW\*(C`get\*(C'\fR returns the empty string. .IP "set( \s-1DIRECTIVE, VALUE\s0 )" 4 .IX Item "set( DIRECTIVE, VALUE )" Sets the value for \s-1DIRECTIVE\s0 to \s-1VALUE.\s0 The \s-1DIRECTIVE\s0 need not already exist. This overwrites previous values. .Sp The \s-1VALUE\s0 must be a simple scalar. It cannot be a reference. If the \s-1VALUE\s0 is a reference, the function prints a warning and returns false. .IP "unset( \s-1DIRECTIVE\s0 )" 4 .IX Item "unset( DIRECTIVE )" Remove the value from \s-1DIRECTIVE,\s0 which will still exist. It's value is undef. If the \s-1DIRECTIVE\s0 does not exist, it will not be created. Returns \s-1FALSE\s0 if the \s-1DIRECTIVE\s0 does not already exist, and \s-1TRUE\s0 otherwise. .IP "remove( \s-1DIRECTIVE\s0 )" 4 .IX Item "remove( DIRECTIVE )" Remove the \s-1DIRECTIVE.\s0 Returns \s-1TRUE\s0 is \s-1DIRECTIVE\s0 existed and \s-1FALSE\s0 otherwise. .IP "\fBdirectives()\fR" 4 .IX Item "directives()" Returns a list of all of the directive names found in the configuration file. The keys are sorted ASCII-betically. .IP "exists( \s-1DIRECTIVE\s0 )" 4 .IX Item "exists( DIRECTIVE )" Return \s-1TRUE\s0 if the specified directive exists, and \s-1FALSE\s0 otherwise. .IP "clone" 4 .IX Item "clone" Return a copy of the object. The new object is distinct from the original so you can make changes to the new object without affecting the old one. .IP "save( \s-1FILENAME\s0 [ => \s-1ARRAY_REF\s0 [, \s-1FILENAME\s0 => \s-1ARRAY_REF\s0 ] ] );" 4 .IX Item "save( FILENAME [ => ARRAY_REF [, FILENAME => ARRAY_REF ] ] );" The save method works in three ways, depending on the argument list. .Sp With a single argument, the save function attempts to save all of the field-value pairs of the object to the file named by the argument. .Sp .Vb 1 \& $clone\->save( "configrc" ); .Ve .Sp With two arguments, the method expects the second argument to be an array reference which lists the directives to save in the file. .Sp .Vb 1 \& $clone\->save( "configrc" => [qw(Foo Bar)] ); .Ve .Sp With more than two arguments, the method expects filename-list pairs. The method will save in each file the values in their respective array references. .Sp .Vb 4 \& $clone\->save( \& "configrc" => [qw(Foo Bar)], \& "global" => [qw(Baz Quux)], \& ); .Ve .Sp In the last two cases, the method checks that the value for each pair is an array reference before it affects any files. It croaks if any value is not an array reference. .Sp Once the method starts writing files, it tries to write all of the specified files. Even if it has a problem with one of them, it continues onto the next one. The method does not necessarily write the files in the order they appear in the argument list, and it does not check if you specified the same file twice. .SS "Package variables" .IX Subsection "Package variables" .ie n .IP "$Die \- \s-1DEPRECATED\s0" 4 .el .IP "\f(CW$Die\fR \- \s-1DEPRECATED\s0" 4 .IX Item "$Die - DEPRECATED" If set to a true value, all errors are fatal. .ie n .IP "$ERROR" 4 .el .IP "\f(CW$ERROR\fR" 4 .IX Item "$ERROR" The last error message. .ie n .IP "%ERROR" 4 .el .IP "\f(CW%ERROR\fR" 4 .IX Item "%ERROR" The error messages from unreadable files. The key is the filename and the value is the error message. .ie n .IP "$Warn \- \s-1DEPRECATED\s0" 4 .el .IP "\f(CW$Warn\fR \- \s-1DEPRECATED\s0" 4 .IX Item "$Warn - DEPRECATED" If set to a true value, methods may output warnings. .SH "LIMITATIONS/BUGS" .IX Header "LIMITATIONS/BUGS" Directives are case-sensitive. .PP If a directive is repeated, the first instance will silently be ignored. .SH "CREDITS" .IX Header "CREDITS" Bek Oberin \f(CW\*(C`\*(C'\fR wote the original module .PP Kim Ryan \f(CW\*(C`\*(C'\fR adapted the module to make declaring keys optional. Thanks Kim. .PP Alan W. Jurgensen \f(CW\*(C`\*(C'\fR added a change to allow the NAME=VALUE format in the configuration file. .PP Andy Lester, \f(CW\*(C`\*(C'\fR, for maintaining the module while brian was on active duty. .PP Adam Trickett, \f(CW\*(C`\*(C'\fR, added multi-line support. You might want to see his \f(CW\*(C`Config::Trivial\*(C'\fR module. .PP Greg White has been a very patient user and tester. .SH "SOURCE AVAILABILITY" .IX Header "SOURCE AVAILABILITY" The source is in Github: .PP .Vb 1 \& http://github.com/briandfoy/ConfigReader\-Simple/ .Ve .SH "AUTHORS" .IX Header "AUTHORS" brian d foy, \f(CW\*(C`\*(C'\fR .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright © 2002\-2021, brian d foy . All rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the Artistic License 2.0.