.\" 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 "Config::Record 3pm"
.TH Config::Record 3pm "2022-10-22" "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"
Config::Record \- Configuration file access
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Config::Record;
\&
\&
\&  # Create an empty record & then load from file
\&  my $config = Config::Record\->new();
\&  $config\->load("/etc/myapp.cfg");
\&
\&  # Create & load, then save to filename
\&  my $config = Config::Record\->new(file => "/etc/myapp.cfg");  
\&  $config\->save("/etc/myapp.cfg");
\&
\&  # Load / save from filehandle
\&  my $fh = IO::File\->new("/etc/myapp.cfg");
\&  my $config = Config::Record\->new(file => $fh);
\&  $config\->save($fh);
\&
\&  # Get a config value, throw error if not found
\&  my $value = $config\->get("foo");
\&
\&  # Get a config value, return \*(Aqeek\*(Aq if not found
\&  my $value = $config\->get("foo", "eek");
\&
\&  # Set a value
\&  $config\->set("foobar", "wizz");
\&
\&  # Get a deep config value (ie nested hash)
\&  my $value = $config\->get("foo/bar", "eek");
\&
\&  # Get first element of an array param
\&  my $value = $config\->get("people/[0]/forename");
\&
\&  # Get the raw hash reference forming the record
\&  my $record = $config\->record();
\&
\&  # Get a new config object rooted at a sub\-hash
\&  my $config = $config\->view("foo");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides an \s-1API\s0 for loading and saving of simple configuration
file records. Entries in the configuration file are essentially key,value 
pairs, with the key and values separated by a single equals symbol. The 
\&\f(CW\*(C`key\*(C'\fR consists only of alphanumeric characters. There are three types of 
values, scalar values can contain anything except newlines. Trailing 
whitespace will be trimmed unless the value is surrounded in double 
quotes. eg
.PP
.Vb 2
\&  foo = Wizz
\&  foo = "Wizz....    "
.Ve
.PP
Long lines can be split with a backslash character, without introducing
newlines. Without double quotes, whitespace at beginning and end of lines
will be trimmed eg
.PP
.Vb 4
\&  foo = This is a long \e
\&        line of text
\&  foo = "This is a long " \e
\&        "line of text"
.Ve
.PP
Multi-line strings can be provided as '\s-1HERE\s0' documents, eg
.PP
.Vb 5
\&  foo = <<EOF
\&This is a multiple paragraph
\&block of text with newlines
\&preserved
\&EOF
.Ve
.PP
Array values  consist of a single right round bracket, following by
one \f(CW\*(C`value\*(C'\fR per line, terminated by a single left round bracket. eg
.PP
.Vb 4
\&  foo = (
\&    Wizz
\&    "Wizz...    "
\&  )
.Ve
.PP
Hash values consist of a single right curly bracket, followed by one
key,value pair per line, terminated by a single left curly bracket.
eg
.PP
.Vb 4
\&  foo = {
\&    one = Wizz
\&    two = "Wizz....  "
\&  }
.Ve
.PP
Arrays and hashes can be nested to arbitrary depth.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.Vb 10
\&  name = Foo
\&  title = "Wizz bang wallop"
\&  eek = (
\&    OOhh
\&    Aahhh
\&    Wizz
\&  )
\&  people = (
\&    {
\&      forename = John
\&      surnamne = Doe
\&    }
\&    {
\&      forename = Some
\&      surname = One
\&    }
\&  )
\&  wizz = {
\&    foo = "Elk"
\&    ooh = "fds"
\&  }
.Ve
.SH "EXTRA PARSER FEATURES"
.IX Header "EXTRA PARSER FEATURES"
The syntax described thus far is classed as the base feature set. By
passing the \f(CW\*(C`features\*(C'\fR parameter when creating an instance of the
\&\f(CW\*(C`Config::Record\*(C'\fR class, it is possible to turn on certain extra
features
.SS "\s-1QUOTED\s0 NON-ALPHANUMERIC \s-1KEYS\s0"
.IX Subsection "QUOTED NON-ALPHANUMERIC KEYS"
The keys for configuration parameters are normally restricted to only
contain the characters 'a\-Z', '0\-9', '_', '\-' and '.'. Sometimes it
is desirable to allow arbitrary characters for keys. If this capability
is required then the \f(CW\*(C`quotedkeys\*(C'\fR parameter can be set.
.PP
\fI\s-1EXAMPLE\s0\fR
.IX Subsection "EXAMPLE"
.PP
.Vb 8
\&  name = Foo
\&  title = "Wizz bang wallop"
\&  " some parameter " = (
\&     foo
\&     bar
\&  }
\&  "an embedded \e" quote" = bar
\&  "an embedded \e\e backslash" = wizz
.Ve
.SS "\s-1EXTERNAL INCLUDE FILES\s0"
.IX Subsection "EXTERNAL INCLUDE FILES"
With large configuration files it can be desirable to split them into
a number of smaller files. If this capability is required, then the
\&\f(CW\*(C`includes\*(C'\fR feature can be requested. Each included file must follow
the syntax rules already described.
.PP
\fI\s-1EXAMPLE\s0\fR
.IX Subsection "EXAMPLE"
.PP
In the main file
.PP
.Vb 3
\&  name = Foo
\&  title = "Wizz bang wallop"
\&  foo = @include(somefile.cfg)
.Ve
.PP
And in somefile.cfg
.PP
.Vb 2
\&  firstname = Joe
\&  lastname = Blogs
.Ve
.PP
Is equivalent to
.PP
.Vb 6
\&  name = Foo
\&  title = "Wizz bang wallop"
\&  foo = {
\&    firstname = Joe
\&    lastname = Blogs
\&  }
.Ve
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "my $config = Config::Record\->new([file => $file], [features => \e%features]);" 4
.el .IP "my \f(CW$config\fR = Config::Record\->new([file => \f(CW$file\fR], [features => \e%features]);" 4
.IX Item "my $config = Config::Record->new([file => $file], [features => %features]);"
Creates a new config object, loading parameters from the file specified
by the \f(CW\*(C`file\*(C'\fR parameter. The \f(CW\*(C`file\*(C'\fR parameter can either be a string
representing a fully qualified filename, or a IO::Handle object. If the
\&\f(CW\*(C`file\*(C'\fR parameter is a string, this filename will be saved and future
calls to \f(CW\*(C`load\*(C'\fR or \f(CW\*(C`save\*(C'\fR are permitted to omit the filename. If the
\&\f(CW\*(C`file\*(C'\fR parameter is not supplied then an empty configuration record
is created.
.Sp
The \f(CW\*(C`features\*(C'\fR parameter allows extra parser features to be enabled.
The two valid keys for the associated hash as \f(CW\*(C`includes\*(C'\fR and
\&\f(CW\*(C`quotedkeys\*(C'\fR as described earlier in this document.
.ie n .IP "$config\->load([$file]);" 4
.el .IP "\f(CW$config\fR\->load([$file]);" 4
.IX Item "$config->load([$file]);"
Loads and parses a configuration record. The \f(CW\*(C`file\*(C'\fR parameter can either
be a string representing a fully qualified filename, or an IO::Handle 
object. The \f(CW$file\fR parameter may be omitted, if a filename was specified 
in the constructor, or in previous calls to \f(CW\*(C`load\*(C'\fR or \f(CW\*(C`save\*(C'\fR. Prior to 
loading the record, the current contents of this configuration are cleared.
.ie n .IP "$config\->save([$file]);" 4
.el .IP "\f(CW$config\fR\->save([$file]);" 4
.IX Item "$config->save([$file]);"
Saves the configuration record to a file. The \f(CW\*(C`file\*(C'\fR parameter can either
be a string representing a fully qualified filename, or an IO::Handle
object opened for writing. The \f(CW$file\fR parameter may be omitted, if a 
filename was specified  in the constructor, or in previous calls to \f(CW\*(C`load\*(C'\fR 
or \f(CW\*(C`save\*(C'\fR.
.ie n .IP "my $value = $config\->get($key[, $default]);" 4
.el .IP "my \f(CW$value\fR = \f(CW$config\fR\->get($key[, \f(CW$default\fR]);" 4
.IX Item "my $value = $config->get($key[, $default]);"
Gets the value of a configuration parameter corresponding to the name
\&\f(CW\*(C`key\*(C'\fR. If there is no value in the record, then the optional \f(CW\*(C`default\*(C'\fR 
is returned.
.ie n .IP "$config\->set($key, $value);" 4
.el .IP "\f(CW$config\fR\->set($key, \f(CW$value\fR);" 4
.IX Item "$config->set($key, $value);"
Sets the value of a configuration parameter corresponding to the
name \f(CW\*(C`key\*(C'\fR.
.ie n .IP "$config\->view($key)" 4
.el .IP "\f(CW$config\fR\->view($key)" 4
.IX Item "$config->view($key)"
Return a new Config::Record object, rooted at the specified key.
If the key doesn't resolve to a hash reference an error will be
raised.
.ie n .IP "my $record = $config\->\fBrecord()\fR;" 4
.el .IP "my \f(CW$record\fR = \f(CW$config\fR\->\fBrecord()\fR;" 4
.IX Item "my $record = $config->record();"
Retrieves a hash reference for the entire configuration record. Currently
this is the actual internal storage record, so changes will modify the
configuration. In the next release this will be changed to be a deep clone
of the internal storage record.
.SH "BUGS"
.IX Header "BUGS"
Config::Record has the following limitations
.IP "\(bu" 4
If you load and then save a configuration file all comments are
removed & whitespace normalized.
.IP "\(bu" 4
Ordering of elements in hash ref are not preserved across load
and save sequence
.PP
These limitations may be fixed in a future release if there is
demand from users...
.SH "AUTHORS"
.IX Header "AUTHORS"
Daniel Berrange <dan@berrange.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2000\-2007 Daniel P. Berrange <dan@berrange.com>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\f(CWperl(1)\fR