.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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 "Parse::PlainConfig 3pm"
.TH Parse::PlainConfig 3pm "2008-07-07" "perl v5.10.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"
Parse::PlainConfig \- Parser for plain\-text configuration files
.SH "MODULE VERSION"
.IX Header "MODULE VERSION"
\&\f(CW$Id:\fR PlainConfig.pm,v 2.06 2008/07/07 22:59:35 acorliss Exp $
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Parse::PlainConfig;
\&
\&  $conf = new Parse::PlainConfig;
\&  $conf = Parse::PlainConfig\->new(
\&    \*(AqPARAM_DELIM\*(Aq => \*(Aq=\*(Aq,
\&    \*(AqFILE\*(Aq        => \*(Aq.myrc\*(Aq,
\&    \*(AqMAX_BYTES\*(Aq   => 65536,
\&    \*(AqSMART_PARSER => 1,
\&    );
\&
\&  $conf\->property(PARAM_DELIM => \*(Aq=\*(Aq);
\&
\&  $rv = $conf\->read(\*(Aqmyconf.conf\*(Aq);
\&  $rv = $conf\->read;
\&  $rv = $conf\->readIfNewer;
\&  $conf\->write(\*(Aq.myrc\*(Aq, 2);
\&
\&  $conf\->purge;
\&
\&  @parameters = $conf\->parameters;
\&  $conf\->parameter(FOO => "bar");
\&  $value = $conf\->parameter(FOO);
\&  $conf\->describe(FOO => \*(AqThis is foo\*(Aq);
\&  $conf\->coerce("string", qw(FOO BAR));
\&
\&  @order = $conf\->order;
\&  $conf\->order(@new_order);
\&
\&  $errstr = Parse::PlainConfig::ERROR;
\&
\&  $rv = $conf\->hasParameter(\*(AqFOO\*(Aq);
.Ve
.PP
The following methods are only supported for backwards compatibility reasons.
They will likely be removed at some point in the future.
.PP
.Vb 6
\&  # Use of the tags DELIM and PURGE are deprecated in favour of
\&  # PARAM_DELIM, LIST_DELIM, HASH_DELIM, and AUTOPURGE
\&  $conf = Parse::PlainConfig\->new(
\&    \*(AqDELIM\*(Aq => \*(Aq=\*(Aq,
\&    \*(AqPURGE\*(Aq => 1,
\&    );
\&
\&  # As is the delim method since it works only on the tag delimiter
\&  $conf\->delim(\*(Aq=\*(Aq);
\&
\&  # Auto\-purge should be enabled/disabled via the property method
\&  $conf\->purge(1);
\&
\&  # directives is replaced with parameters
\&  @directives = $conf\->directives;
\&
\&  # get/set methods are replaced with a unifed parameter method
\&  $field = $conf\->get(\*(AqKEY1\*(Aq);
\&  ($field1, $field2) = $conf\->get(qw(KEY1 KEY2));
\&  $conf\->set(KEY1 => \*(Aqfoo\*(Aq, KEY2 => \*(Aqbar\*(Aq);
\&
\&  # This was just a really bad idea to begin with, plus it\*(Aqs 
\&  # effective broken at this point (only returns a copy of the
\&  # internal hash now, so it\*(Aqs effectively read\-only)
\&  $hashref = $conf\->getRef;
\&
\&  # This is just a wrapper for the class function
\&  $errstr = $conf\->error
.Ve
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
.IP "\(bu" 4
Paranoid
.IP "\(bu" 4
Text::ParseWords
.IP "\(bu" 4
Text::Tabs
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Parse::PlainConfig provides \s-1OO\s0 objects which can parse and generate
human-readable configuration files.
.SH "FILE SYNTAX"
.IX Header "FILE SYNTAX"
.SS "\s-1TRADITIONAL\s0 \s-1USAGE\s0"
.IX Subsection "TRADITIONAL USAGE"
The plain parser supports the reconstructions of relatively simple data
structures.  Simple string assignments and one-dimensional arrays and hashes
are possible.  Below are are various examples of constructs:
.PP
.Vb 3
\&  # Scalar assignment
\&  FIRST_NAME: Joe
\&  LAST_NAME: Blow
\&
\&  # Array assignment
\&  FAVOURITE_COLOURS: red, yellow, green
\&  ACCOUNT_NUMBERS:  9956\-234\-9943211, \e
\&                    2343232\-421231445, \e
\&                    004422\-03430\-0343
\&  
\&  # Hash assignment
\&  CARS:  crown_vic => 1982, \e
\&         geo       => 1993
.Ve
.PP
As the example above demonstrates, all lines that begin with a '#' (leading
whitespace is allowed) are ignored as comments.  if '#" occurs in any other
position, it is accepted as part of the passed value.  This means that you
\&\fBcannot\fR place comments on the same lines as values.
.PP
All directives and associated values will have both leading and trailing 
whitespace stripped from them before being stored in the configuration hash.  
Whitespace is allowed within both.
.PP
In traditional mode (meaning no parameters are set to be coerced into a
specific datatype) one must encapsulate list and hash delimiters with
quotation marks in order to prevent the string from being split and stored as
a list or hash.  Quotation marks that are a literal part of the string must be
backslashed.
.SS "\s-1SMART\s0 \s-1PARSER\s0"
.IX Subsection "SMART PARSER"
The new parser now provides some options to make the file syntax more
convenient.  You can activate the smart parser by setting \fB\s-1SMART_PARSER\s0\fR to a
true value during object instantiation or via the \fBproperty\fR method.
.PP
With the traditional parser you had to backslach the end of all preceding
lines if you wanted to split a value into more than one line:
.PP
.Vb 2
\&  FOO:  This line starts here \e
\&        and ends here...
.Ve
.PP
With the smart parser enabled that is no longer necessary as long as the
following lines are indented further than the first line:
.PP
.Vb 2
\&  FOO:  This line starts here
\&        and ends here...
.Ve
.PP
\&\fBNote:\fR  The indentation is compared by byte count with no recognition of
tab stops.  That means if you indent with spaces on the first line and indent
with tabs on the following it may not concantenate those values.
.PP
Another benefit of the smart parser is found when you specify a parameter to
be of a specific datatype via the \fB\s-1COERCE\s0\fR hash during object instantiation
or the \fBcoerce\fR method.  For instance, the traditional parser requires you to
encapsulate strings with quotation marks if they contain list or hash
delimiters:
.PP
.Vb 1
\&  Quote:  "\e"It can\*(Aqt be that easy,\e" he said."
.Ve
.PP
Also note how you had to escape quotation marks if they were to be a literal
part of the string.  With this parameter set to be coerced to a scalar you can
simply write:
.PP
.Vb 1
\&  Quote:  "It can\*(Aqt be that easy," he said.
.Ve
.PP
Similarly, you don't have to quote hash delimiters in parameters set to be
coerced into lists.  Quotation marks as part of an element value must be
escaped, though, since unescaped quotation marks are assumed to encapsulate
strings containing list delimiters you don't want to split on.
.PP
\&\fBNote:\fR The previous versions of Parse::PlainConfig did not allow the user to
set keys like:
.PP
.Vb 2
\&  FOO: \e
\&      bar
.Ve
.PP
or save empty assignments like
.PP
.Vb 1
\&  FOO:
.Ve
.PP
This is no longer the case.  Both are now valid and honoured.
.SH "SECURITY"
.IX Header "SECURITY"
\&\fB\s-1WARNING:\s0\fR This parser will attempt to open what ever you pass to it for a
filename as is.  If this object is to be used in programs that run with
permissions other than the calling user, make sure you sanitize any
user-supplied filename strings before passing them to this object.
.PP
This also uses a blocking b<flock> call to open the file for reading and
writing.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "Parse::PlainConfig::ERROR"
.IX Subsection "Parse::PlainConfig::ERROR"
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 7
\&  $conf = new Parse::PlainConfig;
\&  $conf = Parse::PlainConfig\->new(
\&    \*(AqPARAM_DELIM\*(Aq => \*(Aq=\*(Aq,
\&    \*(AqFILE\*(Aq        => \*(Aq.myrc\*(Aq,
\&    \*(AqMAX_BYTES\*(Aq   => 65536,
\&    \*(AqSMART_PARSER => 1,
\&    );
.Ve
.PP
The object constructor can be called with or without arguments.  Arguments
available for use include:
.PP
.Vb 10
\&  Argument        Default    Purpose
\&  =============================================================
\&  ORDER           []         Specifies specific order of
\&                             fields to be used while writing
\&  FILE            undef      Filename for read/write ops
\&  PARAM_DELIM       \*(Aq:\*(Aq        Field/value delimiter
\&  LIST_DELIM      \*(Aq,\*(Aq        List delimiter within field values
\&  HASH_DELIM      \*(Aq=>\*(Aq       Hash key/value delimiter within
\&                             field values
\&  AUTOPURGE       0          Autopurge enabled/disabled
\&  COERCE          {}         Field coercion hash
\&  DEFAULTS        {}         Default field values
\&  SMART_PARSER    0          Smart parser enabled/disabled
\&  MAX_BYTES       16384      Integer denoting maximum bytes
\&                             to read in any given file
.Ve
.PP
\&\fB\s-1DELIM\s0\fR, \fB\s-1PURGE\s0\fR, and  \fB\s-1FORCE_SCALAR\s0\fR are still available for backwards 
compatibility, but may be removed in the future.  One should use 
\&\fB\s-1PARAM_DELIM\s0\fR \fB\s-1AUTOPURGE\s0\fR, and \fB\s-1COERCE\s0\fR instead.
.PP
\&\fB\s-1COERCE\s0\fR is a hash of field name/data type pairs.  If a field is listed in
this hash then their values will always be returned in the requested format of
either string, list, or hash.  Any field coerced to string, for instance, will
ignore list and hash delimiters and assume the entire value will always be
string value.
.PP
\&\fB\s-1DEFAULTS\s0\fR is a hash of field name/value pairs.  This ensures that even if a
field is not explicitly set (either in a conf file or programmatically) a
default value can still be retrieved.
.PP
\&\fB\s-1SMART_PARSER\s0\fR removes the need to backslash end-of-lines to continue the
value onto the next.  If the following line is indented further than the tag
was it will automatically assume that the next line is a continuation of the
previous.  It also affects the need to encapsulate coerced datatypes with
quotation marks for irrelevant delimiters.
.PP
\&\fB\s-1AUTOPURGE\s0\fR erases all stored parameters and values before reading a file.
This does not, however, erase any values set for \fB\s-1ORDER\s0\fR.
.SS "property"
.IX Subsection "property"
.Vb 1
\&  $conf\->property(PARAM_DELIM => \*(Aq=\*(Aq);
.Ve
.PP
This method sets or retrieves the specified property.  Please note
that this \fBoverwrites\fR the current value, even for those properties that are
references to lists and hashes.
.PP
If you're using this to set a property it will return a boolean true or false
depending on the success of the operation.  If you're just retrieving a
property it will return the value of the property.  If you ask for a
nonexistent property it will \fBcroak\fR.
.SS "purge"
.IX Subsection "purge"
.Vb 2
\&  $conf\->purge(1);
\&  $conf\->purge;
.Ve
.PP
\&\fB\s-1NOTE:\s0\fR  Use of this method to set the purge mode is deprecated and will be
removed in the future.  For that please use the \fBproperty\fR method instead.
.PP
This method either (re)sets the auto-purge mode, or performs an immediate manual
purge.  Auto-purge mode clears the configuration hash each time a
configuration file is read, so that the internal configuration data consists
solely of what is in that file.  If you wanted to combine the settings of
multiple files that each may exclusively hold some directives, setting this to
\&'off' will load the combined configuration as you read each file.
.PP
You can still clobber configuration values, of course, if the same directive
is defined in multiple files.  In that case, the last file's value will be the
one stored in the hash.
.PP
This does not clear the \fBorder\fR or \fBcoerce\fR properties.
.PP
Autopurge mode is disabled by default.
.SS "read"
.IX Subsection "read"
.Vb 2
\&  $rv = $conf\->read(\*(Aqmyconf.conf\*(Aq);
\&  $rv = $conf\->read;
.Ve
.PP
The read method is called initially with a filename as the only argument.
This causes the parser to read the file and extract all of the configuration
directives from it.
.PP
You'll notice that you can also call the read method without an argument.
The name of the file read is stored internally, and if already set to a valid
value (either by a previous call to \fBread\fR with a filename argument or by
setting the \fB\s-1FILE\s0\fR property) this will read that file's contents.
.PP
The return value will be one if the file was successfully read and parsed, 
or zero otherwise.  The reason for failure can be read via
\&\fBParse::PlainConfig::ERROR\fR.
.PP
This function will cause the program to croak if called without a filename 
ever being defined.
.SS "readIfNewer"
.IX Subsection "readIfNewer"
.Vb 1
\&  $rv = $conf\->readIfNewer;
.Ve
.PP
This method is used to reread & parse the file only if the mtime appears
newer than when last read.  If the file was successfully reread or appears to
be the same it will return true.  Any errors will be stored in
\&\fBParse::PlainConfig::ERROR\fR and it will return a false value.
.PP
You can determine whether or not the file was read by the true value.  If it
was re-read it will return 1.  If the file appears to be the same age it will 
return a 2.
.SS "write"
.IX Subsection "write"
.Vb 1
\&  $conf\->write(\*(Aq.myrc\*(Aq, 2);
.Ve
.PP
This method writes the current configuration stored in memory to the specified
file, either specified as the first argument, or as stored from an explicit or
implicit \fBread\fR call.
.PP
The second argument specifies what kind of whitespace padding, if any, to use
with the directive/value delimiter.  The following values are recognised:
.PP
.Vb 6
\&  Value    Meaning
\&  ================================================
\&  0        No padding (i.e., written as KEY:VALUE)
\&  1        Left padding (i.e., written as KEY :VALUE)
\&  2        Right padding (i.e., written as KEY: VALUE)
\&  3        Full padding (i.e., written as KEY : VALUE)
.Ve
.PP
Both arguments are optional.
.SS "parameters"
.IX Subsection "parameters"
.Vb 1
\&  @parameters = $conf\->parameters;
.Ve
.PP
This method returns a list of all the names of the directives currently 
stored in the configuration hash in no particular order.
.SS "parameter"
.IX Subsection "parameter"
.Vb 6
\&  $value = $conf\->parameter(\*(AqSCALAR1\*(Aq);
\&  @values = $conf\->parameter(\*(AqLIST1\*(Aq);
\&  %values = $conf\->parameter(\*(AqHASH1\*(Aq);
\&  $conf\->parameter(\*(AqSCALAR1\*(Aq, "foo");
\&  $conf\->parameter(\*(AqLIST1\*(Aq, [qw(foo bar)]);
\&  $conf\->parameter(\*(AqHASH1\*(Aq, { foo => \*(Aqbar\*(Aq });
.Ve
.PP
This method sets or retrieves the specified parameter.  Hash and list values
are copied and returned as a list.  If the specified parameter is set to be
coerced into a specific data type the specified value will be converted to
that datatype.   This means you can do something like:
.PP
.Vb 3
\&  # SCALAR1 will equal "foo , bar , roo" assuming LIST_DELIM is set to \*(Aq,\*(Aq
\&  $conf\->coerce(qw(string SCALAR1));
\&  $conf\->parameter(\*(AqSCALAR1\*(Aq, [qw(foo bar roo)]);
\&
\&  # SCALAR1 will equal "foo => bar : roo => \*(Aq\*(Aq" assuming HASH_DELIM is set
\&  # to \*(Aq=>\*(Aq and LIST_DELIM is set to \*(Aq:\*(Aq
\&  $conf\->parameter(\*(AqSCALAR1\*(Aq, { \*(Aqfoo\*(Aq => \*(Aqbar\*(Aq, \*(Aqroo\*(Aq => \*(Aq\*(Aq });
.Ve
.PP
In order for conversions to be somewhat predictable (in the case of hashes
coerced into other values) hash key/value pairs will be assigned to string
or list portions according to the alphabetic sort order of the keys.
.SS "coerce"
.IX Subsection "coerce"
.Vb 1
\&  $conf\->coerce("string", "FOO", "BAR");
.Ve
.PP
This method configures the parser to coerce values into the specified
datatype (either string, list, or hash) and immediately convert any existing
values and store them into that datatype as well.
.SS "describe"
.IX Subsection "describe"
.Vb 1
\&  $conf\->describe(KEY1 => \*(AqThis is foo\*(Aq, KEY2 => \*(AqThis is bar\*(Aq);
.Ve
.PP
The describe method takes any number of key/description pairs which will be
used as comments preceding the directives in any newly written conf file.  You
are responsible for prepending a comment character to each line, as well as
splitting along your desired text width.
.SS "order"
.IX Subsection "order"
.Vb 2
\&  @order = $conf\->order;
\&  $conf\->order(@new_order);
.Ve
.PP
This method returns the current order of the configuration directives as read 
from the file.   If called with a list as an argument, it will set the
directive order with that list.  This method is probably of limited use except 
when you wish to control the order in which directives are written in new conf 
files.
.PP
Please note that if there are more directives than are present in this list, 
those extra keys will still be included in the new file, but will appear in
alphabetically sorted order at the end, after all of the keys present in the
list.
.SS "hasParameter"
.IX Subsection "hasParameter"
.Vb 1
\&  $rv = $conf\->hasParameter(\*(AqFOO\*(Aq);
.Ve
.PP
This function allows you to see if a parameter has been defined or has a
default set for it.  Returns a boolean value.
.SH "DEPRECATED METHODS"
.IX Header "DEPRECATED METHODS"
.SS "delim"
.IX Subsection "delim"
.Vb 1
\&  $conf\->delim(\*(Aq=\*(Aq);
.Ve
.PP
This method gets and/or sets the parameter name/value delimiter to be used in the 
conf files.  The default delimiter is ':'.  This can be multiple characters.
.SS "directives"
.IX Subsection "directives"
.Vb 1
\&  @directives = $conf\->directives;
.Ve
.PP
This method returns a list of all the names of the directives currently 
stored in the configuration hash in no particular order.
.SS "get"
.IX Subsection "get"
.Vb 2
\&  $field = $conf\->get(\*(AqKEY1\*(Aq);
\&  ($field1, $field2) = $conf\->get(qw(KEY1 KEY2));
.Ve
.PP
The get method takes any number of directives to retrieve, and returns them.  
Please note that both hash and list values are passed by reference.  In order 
to protect the internal state information, the contents of either reference is
merely a copy of what is in the configuration object's hash.  This will \fBnot\fR
pass you a reference to data stored internally in the object.  Because of
this, it's perfectly safe for you to shift off values from a list as you
process it, and so on.
.SS "set"
.IX Subsection "set"
.Vb 1
\&  $conf\->set(KEY1 => \*(Aqfoo\*(Aq, KEY2 => \*(Aqbar\*(Aq);
.Ve
.PP
The set method takes any number of directive/value pairs and copies them into 
the internal configuration hash.
.SS "get_ref"
.IX Subsection "get_ref"
.Vb 1
\&  $href = $conf\->get_ref
.Ve
.PP
\&\fBNote\fR:  This used to give you a reference to the internal configuration hash
so you could manipulate it directly.  It now only gives you a \fBcopy\fR of the
internal hash (actually, it's reconstructed has to make it look like the old
data structure).  In short, any changes you make to this hash \fBwill be lost\fR.
.SS "error"
.IX Subsection "error"
.Vb 1
\&  warn $conf\->error;
.Ve
.PP
This method returns a zero-length string if no errors were registered with the
last operation, or a text message describing the error.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
Through the use of \fBParanoid::Debug\fR this module will produce internal
diagnostic output to \s-1STDERR\s0.  It begins logging at log level 7.  To enable
debugging output please see the pod for Paranoid::Debug.
.SH "HISTORY"
.IX Header "HISTORY"
.Vb 2
\&  2002/01/18:  Original public release (v1.1)
\&  2006/05/26:  Complete rewrite (v2.0)
.Ve
.SH "AUTHOR/COPYRIGHT"
.IX Header "AUTHOR/COPYRIGHT"
(c) 2002 Arthur Corliss (corliss@digitalmages.com)