Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / Config::GitLike.3pm

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
.\"
.\" 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::GitLike 3"
.TH Config::GitLike 3 "2010-04-03" "perl v5.8.8" "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::GitLike \- git\-compatible config file parsing
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This module parses git-style config files, which look like this:
.PP
.Vb 10
\&    [core]
\&        repositoryformatversion = 0
\&        filemode = true
\&        bare = false
\&        logallrefupdates = true
\&    [remote "origin"]
\&        url = spang.cc:/srv/git/home.git
\&        fetch = +refs/heads/*:refs/remotes/origin/*
\&    [another\-section "subsection"]
\&        key = test
\&        key = multiple values are OK
\&        emptyvalue =
\&        novalue
.Ve
.PP
Code that uses this config module might look like:
.PP
.Vb 1
\&    use Config::GitLike;
\&
\&    my $c = Config::GitLike\->new(confname => \*(Aqconfig\*(Aq);
\&    $c\->load;
\&
\&    $c\->get( key => \*(Aqsection.name\*(Aq );
\&    # make the return value a Perl true/false value
\&    $c\->get( key => \*(Aqcore.filemode\*(Aq, as => \*(Aqbool\*(Aq );
\&
\&    # replace the old value
\&    $c\->set(
\&        key => \*(Aqsection.name\*(Aq,
\&        value => \*(Aqval1\*(Aq,
\&        filename => \*(Aq/home/user/.config\*(Aq,
\&    );
\&
\&    # make this key have multiple values rather than replacing the
\&    # old value
\&    $c\->set(
\&        key => \*(Aqsection.name\*(Aq,
\&        value => \*(Aqval2\*(Aq,
\&        filename => \*(Aq/home/user/.config\*(Aq,
\&        multiple => 1,
\&    );
\&
\&    # replace all occurrences of the old value for section.name with a new one
\&    $c\->set(
\&        key => \*(Aqsection.name\*(Aq,
\&        value => \*(Aqval3\*(Aq,
\&        filename => \*(Aq/home/user/.config\*(Aq,
\&        multiple => 1,
\&        replace_all => 1,
\&    );
\&
\&    # make sure to reload the config files before reading if you\*(Aqve set
\&    # any variables!
\&    $c\->load;
\&
\&    # get only the value of \*(Aqsection.name\*(Aq that matches \*(Aq2\*(Aq
\&    $c\->get( key => \*(Aqsection.name\*(Aq, filter => \*(Aq2\*(Aq );
\&    $c\->get_all( key => \*(Aqsection.name\*(Aq );
\&    # prefixing a search regexp with a ! negates it
\&    $c\->get_regexp( key => \*(Aq!na\*(Aq );
\&
\&    $c\->rename_section(
\&        from => \*(Aqsection\*(Aq,
\&        to => \*(Aqnew\-section\*(Aq,
\&        filename => \*(Aq/home/user/.config\*(Aq
\&    );
\&
\&    $c\->remove_section(
\&        section => \*(Aqsection\*(Aq,
\&        filename => \*(Aq/home/user/.config\*(Aq
\&    );
\&
\&    # unsets all instances of the given key
\&    $c\->set( key => \*(Aqsection.name\*(Aq, filename => \*(Aq/home/user/.config\*(Aq );
\&
\&    my %config_vals = $config\->dump;
\&    # string representation of config data
\&    my $str = $config\->dump;
\&    # prints rather than returning
\&    $config\->dump;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module handles interaction with configuration files of the style used
by the version control system Git. It can both parse and modify these
files, as well as create entirely new ones.
.PP
You only need to know a few things about the configuration format in order
to use this module. First, a configuration file is made up of key/value
pairs. Every key must be contained in a section. Sections can have
subsections, but they don't have to. For the purposes of setting and
getting configuration variables, we join the section name,
subsection name, and variable name together with dots to get a key
name that looks like \*(L"section.subsection.variable\*(R". These are the
strings that you'll be passing in to \f(CW\*(C`key\*(C'\fR arguments.
.PP
Configuration files inherit from each other. By default, \f(CW\*(C`Config::GitLike\*(C'\fR
loads data from a system-wide configuration file, a per-user
configuration file, and a per-directory configuration file, but by
subclassing and overriding methods you can obtain any combination of
configuration files. By default, configuration files that don't
exist are just skipped.
.PP
See
<http://www.kernel.org/pub/software/scm/git/docs/git\-config.html#_configuration_file>
for details on the syntax of git configuration files. We won't waste pixels
on the nitty gritty here.
.PP
While the behaviour of a couple of this module's methods differ slightly
from the \f(CW\*(C`git config\*(C'\fR equivalents, this module can read any config file
written by git. The converse is usually true, but only if you don't take
advantage of this module's increased permissiveness when it comes to key
names. (See \*(L"\s-1DIFFERENCES\s0 \s-1FROM\s0 GIT-CONFIG\*(R" for details.)
.PP
This is an object-oriented module using Any::Moose. All
subroutines are object method calls.
.PP
A few methods have parameters that are always used for the same purpose:
.SS "Filenames"
.IX Subsection "Filenames"
All methods that change things in a configuration file require a filename to
write to, via the \f(CW\*(C`filename\*(C'\fR parameter. Since a \f(CW\*(C`Config::GitLike\*(C'\fR object can
be working with multiple config files that inherit from each other, we don't
try to figure out which one to write to automatically and let you specify
instead.
.SS "Casting"
.IX Subsection "Casting"
All get and set methods can make sure the values they're returning or
setting are valid values of a certain type: \f(CW\*(C`bool\*(C'\fR, \f(CW\*(C`int\*(C'\fR,
\&\f(CW\*(C`num\*(C'\fR, or \f(CW\*(C`bool\-or\-int\*(C'\fR (or at least as close as Perl can get
to having these types). Do this by passing one of these types
in via the \f(CW\*(C`as\*(C'\fR parameter. The set method, if told to write
bools, will always write \*(L"true\*(R" or \*(L"false\*(R" (not anything else that
\&\f(CW\*(C`cast\*(C'\fR considers a valid bool).
.PP
Methods that are told to cast values will throw exceptions if
the values they're trying to cast aren't valid values of the
given type.
.PP
See the \*(L"cast\*(R" method documentation for more on what is considered valid
for each type.
.SS "Filtering"
.IX Subsection "Filtering"
All get and set methods can filter what values they return via their
\&\f(CW\*(C`filter\*(C'\fR parameter, which is expected to be a string that is a valid
regex. If you want to filter items \s-1OUT\s0 instead of \s-1IN\s0, you can
prefix your regex with a ! and that'll do the trick.
.PP
Now, on the the methods!
.SH "MAIN METHODS"
.IX Header "MAIN METHODS"
There are the methods you're likely to use the most.
.SS "new( confname => 'config' )"
.IX Subsection "new( confname => 'config' )"
Create a new configuration object with the base config name \f(CW\*(C`confname\*(C'\fR.
.PP
\&\f(CW\*(C`confname\*(C'\fR is used to construct the filenames that will be loaded; by
default, these are \f(CW\*(C`/etc/confname\*(C'\fR (global configuration file),
\&\f(CW\*(C`~/.confname\*(C'\fR (user configuration file), and \f(CW\*(C`<Cwd\*(C'\fR/.confname> (directory
configuration file).
.PP
You can override these defaults by subclassing \f(CW\*(C`Config::GitLike\*(C'\fR and
overriding the methods \f(CW\*(C`global_file\*(C'\fR, \f(CW\*(C`user_file\*(C'\fR, and \f(CW\*(C`dir_file\*(C'\fR. (See
\&\*(L"\s-1METHODS\s0 \s-1YOU\s0 \s-1MAY\s0 \s-1WISH\s0 \s-1TO\s0 \s-1OVERRIDE\s0\*(R" for details.)
.PP
If you wish to enforce only being able to read/write config files that
git can read or write, pass in \f(CW\*(C`compatible => 1\*(C'\fR to this
constructor. The default rules for some components of the config
file are more permissive than git's (see \*(L"\s-1DIFFERENCES\s0 \s-1FROM\s0 GIT-CONFIG\*(R").
.SS "confname"
.IX Subsection "confname"
The configuration filename that you passed in when you created
the \f(CW\*(C`Config::GitLike\*(C'\fR object. You can change it if you want by
passing in a new name (and then reloading via \*(L"load\*(R").
.SS "load"
.IX Subsection "load"
Load the global, local, and directory configuration file with the filename
\&\f(CW\*(C`confname\*(C'\fR(if they exist). Configuration variables loaded later
override those loaded earlier, so variables from the directory
configuration file have the highest precedence.
.PP
Pass in an optional path, and it will be passed on to \*(L"load_dirs\*(R" (which
loads the directory configuration file(s)).
.PP
Returns a hash copy of all loaded configuration data stored in the module
after the files have been loaded, or a hashref to this hash in
scalar context.
.SS "config_filenames"
.IX Subsection "config_filenames"
An array reference containing the absolute filenames of all config files
that are currently loaded, in the order they were loaded.
.SS "get"
.IX Subsection "get"
Parameters:
.PP
.Vb 3
\&    key => \*(Aqsect.subsect.key\*(Aq
\&    as => \*(Aqint\*(Aq
\&    filter => \*(Aq!foo
.Ve
.PP
Return the config value associated with \f(CW\*(C`key\*(C'\fR cast as an \f(CW\*(C`as\*(C'\fR.
.PP
The \f(CW\*(C`key\*(C'\fR option is required (will return undef if unspecified); the \f(CW\*(C`as\*(C'\fR
option is not (will return a string by default). Sections and subsections
are specified in the key by separating them from the key name with a .
character. Sections, subsections, and keys may all be quoted (double or
single quotes).
.PP
If \f(CW\*(C`key\*(C'\fR doesn't exist in the config, undef is returned. Dies with
the exception \*(L"Multiple values\*(R" if the given key has more than one
value associated with it. (Use \*(L"get_all\*(R" to retrieve multiple values.)
.PP
Calls \*(L"load\*(R" if it hasn't been done already. Note that if you've run any
\&\f(CW\*(C`set\*(C'\fR calls to the loaded configuration files since the last time they were
loaded, you \s-1MUST\s0 call \*(L"load\*(R" again before getting, or the returned
configuration data may not match the configuration variables on-disk.
.SS "get_all"
.IX Subsection "get_all"
Parameters:
.PP
.Vb 3
\&    key => \*(Aqsection.sub\*(Aq
\&    filter => \*(Aqregex\*(Aq
\&    as => \*(Aqint\*(Aq
.Ve
.PP
Like \*(L"get\*(R" but does not fail if the number of values for the key is not
exactly one.
.PP
Returns a list of values (or an arrayref in scalar context).
.SS "get_regexp"
.IX Subsection "get_regexp"
Parameters:
.PP
.Vb 3
\&    key => \*(Aqregex\*(Aq
\&    filter => \*(Aqregex\*(Aq
\&    as => \*(Aqbool\*(Aq
.Ve
.PP
Similar to \*(L"get_all\*(R" but searches for values based on a key regex.
.PP
Returns a hash of name/value pairs (or a hashref in scalar context).
.SS "dump"
.IX Subsection "dump"
In scalar context, return a string containing all configuration data, sorted in
\&\s-1ASCII\s0 order, in the form:
.PP
.Vb 2
\&    section.key=value
\&    section2.key=value
.Ve
.PP
If called in void context, this string is printed instead.
.PP
In list context, returns a hash containing all the configuration data.
.SS "set"
.IX Subsection "set"
Parameters:
.PP
.Vb 7
\&    key => \*(Aqsection.name\*(Aq
\&    value => \*(Aqbar\*(Aq
\&    filename => File::Spec\->catfile(qw/home user/, \*(Aq.\*(Aq.$config\->confname)
\&    filter => \*(Aqregex\*(Aq
\&    as => \*(Aqbool\*(Aq
\&    multiple => 1
\&    replace_all => 1
.Ve
.PP
Set the key \f(CW\*(C`foo\*(C'\fR in the configuration section \f(CW\*(C`section\*(C'\fR to the value \f(CW\*(C`bar\*(C'\fR
in the given filename.
.PP
Replace \f(CW\*(C`key\*(C'\fR's value if \f(CW\*(C`key\*(C'\fR already exists.
.PP
To unset a key, pass in \f(CW\*(C`key\*(C'\fR but not \f(CW\*(C`value\*(C'\fR.
.PP
Returns true on success.
.PP
If you need to have a . character in your variable name, you can surround the
name with quotes (single or double): \f(CW\*(C`key =&gt \*(Aqsection."foo.bar.com"\*(Aq\*(C'\fR
Don't do this unless you really have to.
.PP
\fImultiple values\fR
.IX Subsection "multiple values"
.PP
By default, set will replace the old value rather than giving a key multiple
values. To override this, pass in \f(CW\*(C`multiple => 1\*(C'\fR. If you want to replace
all instances of a multiple-valued key with a new value, you need to pass
in \f(CW\*(C`replace_all => 1\*(C'\fR as well.
.SS "group_set"
.IX Subsection "group_set"
Parameters:
.PP
.Vb 2
\&    filename => \*(Aq/home/foo/.bar\*(Aq
\&    args_ref => $ref
.Ve
.PP
Same as \*(L"set\*(R", but set a group of variables at the same time without
writing to disk separately for each.
.PP
\&\f(CW\*(C`args_ref\*(C'\fR is an array reference containing a list of hash references which
are essentially hashes of arguments to \f(CW\*(C`set\*(C'\fR, excluding the \f(CW\*(C`filename\*(C'\fR
argument since that is specified separately and the same file is used for all
variables to be set at once.
.SS "rename_section"
.IX Subsection "rename_section"
Parameters:
.PP
.Vb 3
\&    from => \*(Aqname.subname\*(Aq
\&    to => \*(Aqnew.subname\*(Aq
\&    filename => \*(Aq/file/to/edit\*(Aq
.Ve
.PP
Rename the section existing in \f(CW\*(C`filename\*(C'\fR given by \f(CW\*(C`from\*(C'\fR to the section
given by \f(CW\*(C`to\*(C'\fR.
.PP
Throws an exception \f(CW\*(C`No such section\*(C'\fR if the section in \f(CW\*(C`from\*(C'\fR doesn't exist
in \f(CW\*(C`filename\*(C'\fR.
.PP
If no value is given for \f(CW\*(C`to\*(C'\fR, the section is removed instead of renamed.
.PP
Returns true on success, false if \f(CW\*(C`filename\*(C'\fR didn't exist and thus
the rename did nothing.
.SS "remove_section"
.IX Subsection "remove_section"
Parameters:
.PP
.Vb 2
\&    section => \*(Aqsection.subsection\*(Aq
\&    filename => \*(Aq/file/to/edit\*(Aq
.Ve
.PP
Just a convenience wrapper around \*(L"rename_section\*(R" for readability's sake.
Removes the given section (which you can do by renaming to nothing as well).
.ie n .SS "cascade( $bool )"
.el .SS "cascade( \f(CW$bool\fP )"
.IX Subsection "cascade( $bool )"
Gets or sets if only the \fBdeepest\fR configuration file in a directory
tree is loaded, or if all of them are loaded, shallowest to deepest.
Alternately, \f(CW\*(C`cascade => 1\*(C'\fR can be passed to \f(CW\*(C`new\*(C'\fR.
.SH "METHODS YOU MAY WISH TO OVERRIDE"
.IX Header "METHODS YOU MAY WISH TO OVERRIDE"
If your application's configuration layout is different from the default, e.g.
if its home directory config files are in a directory within the home
directory (like \f(CW\*(C`~/.git/config\*(C'\fR) instead of just dot-prefixed, override these
methods to return the right directory names. For fancier things like altering
precedence, you'll need to override \*(L"load\*(R" as well.
.SS "dir_file"
.IX Subsection "dir_file"
Return a string containing the path to a configuration file with the
name \f(CW\*(C`confname\*(C'\fR in a directory. The directory isn't specified here.
.SS "global_file"
.IX Subsection "global_file"
Return the string \f(CW\*(C`/etc/confname\*(C'\fR, the absolute name of the system-wide
configuration file with name \f(CW\*(C`confname\*(C'\fR.
.SS "user_file"
.IX Subsection "user_file"
Return a string containing the path to a configuration file
in the current user's home directory with filename \f(CW\*(C`confname\*(C'\fR.
.SS "load_dirs"
.IX Subsection "load_dirs"
Parameters:
.PP
.Vb 1
\&    \*(Aq/path/to/look/in/\*(Aq
.Ve
.PP
Load the configuration file with the filename \*(L"dir_file\*(R" in the current
working directory into the memory or, if there is no config matching
\&\f(CW\*(C`dir_file\*(C'\fR in the current working directory, walk up the directory tree until
one is found. (No error is thrown if none is found.) If an optional path
is passed in, that directory will be used as the base directory instead
of the working directory.
.PP
You'll want to use \*(L"load_file\*(R" to load config files from your overridden
version of this subroutine.
.PP
Returns nothing of note.
.SH "OTHER METHODS"
.IX Header "OTHER METHODS"
These are mostly used internally in other methods, but could be useful anyway.
.SS "load_global"
.IX Subsection "load_global"
If a global configuration file with the absolute name given by
\&\*(L"global_file\*(R" exists, load its configuration variables into memory.
.PP
Returns the current contents of all the loaded configuration variables
after the file has been loaded, or undef if no global config file is found.
.SS "load_user"
.IX Subsection "load_user"
If a configuration file with the absolute name given by
\&\*(L"user_file\*(R" exists, load its config variables into memory.
.PP
Returns the current contents of all the loaded configuration variables
after the file has been loaded, or undef if no user config file is found.
.ie n .SS "load_file( $filename )"
.el .SS "load_file( \f(CW$filename\fP )"
.IX Subsection "load_file( $filename )"
Takes a string containing the path to a file, opens it if it exists, loads its
config variables into memory, and returns the currently loaded config
variables (a hashref).
.PP
Note that you ought to only call this subroutine with an argument that you
know exists, otherwise config files that don't exist will be recorded as
havind been loaded.
.SS "parse_content"
.IX Subsection "parse_content"
Parameters:
.PP
.Vb 3
\&    content => \*(Aqstr\*(Aq
\&    callback => sub {}
\&    error => sub {}
.Ve
.PP
Parses the given content and runs callbacks as it finds valid information.
.PP
Returns undef on success and \f(CW\*(C`error($content)\*(C'\fR (the original content) on
failure.
.PP
\&\f(CW\*(C`callback\*(C'\fR is called like:
.PP
.Vb 1
\&    callback(section => $str, offset => $num, length => $num, name => $str, value => $str)
.Ve
.PP
\&\f(CW\*(C`name\*(C'\fR and \f(CW\*(C`value\*(C'\fR may be omitted if the callback is not being called on a
key/value pair, or if it is being called on a key with no value.
.PP
\&\f(CW\*(C`error\*(C'\fR is called like:
.PP
.Vb 1
\&    error( content => $content, offset => $offset )
.Ve
.PP
Where \f(CW\*(C`offset\*(C'\fR is the point in the content where the parse error occurred.
.PP
If you need to use this method, you might be interested in \*(L"error_callback\*(R"
as well.
.SS "error_callback"
.IX Subsection "error_callback"
Parameters:
.PP
.Vb 3
\&    content => \*(Aqstr\*(Aq
\&    offset => 45
\&    filename => \*(Aq/foo/bar/.baz\*(Aq
.Ve
.PP
Made especially for passing to \*(L"parse_content\*(R", passed through the
\&\f(CW\*(C`error\*(C'\fR parameter like this:
.PP
.Vb 3
\&    error => sub {
\&        error_callback( @_, filename => \*(Aq/file/you/were/parsing\*(Aq )
\&    }
.Ve
.PP
It's used internally wherever \*(L"parse_content\*(R" is used and will throw
an exception with a useful message detailing the line number, position on
the line, and contents of the bad line; if you find the need to use
\&\*(L"parse_content\*(R" elsewhere, you may find it useful as well.
.ie n .SS "set_multiple( $name )"
.el .SS "set_multiple( \f(CW$name\fP )"
.IX Subsection "set_multiple( $name )"
Mark the key string \f(CW$name\fR as containing multiple values.
.PP
Returns nothing.
.ie n .SS "is_multiple( $name )"
.el .SS "is_multiple( \f(CW$name\fP )"
.IX Subsection "is_multiple( $name )"
Return a true value if the key string \f(CW$name\fR contains multiple values; false
otherwise.
.SS "define"
.IX Subsection "define"
Parameters:
.PP
.Vb 3
\&    section => \*(Aqstr\*(Aq
\&    name => \*(Aqstr\*(Aq
\&    value => \*(Aqstr\*(Aq
.Ve
.PP
Given a section, a key name, and a valueA\*^X store this information
in memory in the config object.
.PP
Returns the value that was just defined on success, or undef
if no name is given and thus the key cannot be defined.
.SS "cast"
.IX Subsection "cast"
Parameters:
.PP
.Vb 3
\&    value => \*(Aqfoo\*(Aq
\&    as => \*(Aqint\*(Aq
\&    human => 1
.Ve
.PP
Return \f(CW\*(C`value\*(C'\fR cast into the type specified by \f(CW\*(C`as\*(C'\fR.
.PP
Valid values for \f(CW\*(C`as\*(C'\fR are \f(CW\*(C`bool\*(C'\fR, \f(CW\*(C`int\*(C'\fR, \f(CW\*(C`num\*(C'\fR, or \f(CW\*(C`bool\-or\-num\*(C'\fR. For
\&\f(CW\*(C`bool\*(C'\fR, \f(CW\*(C`true\*(C'\fR, \f(CW\*(C`yes\*(C'\fR, \f(CW\*(C`on\*(C'\fR, \f(CW1\fR, and undef are translated into a true
value (for Perl); anything else is false. Specifying a true value for the
\&\f(CW\*(C`human\*(C'\fR arg will get you a human-readable 'true' or 'false' rather than a
value that plays along with Perl's definition of truthiness (0 or 1).
.PP
For \f(CW\*(C`int\*(C'\fRs and \f(CW\*(C`num\*(C'\fRs, if \f(CW\*(C`value\*(C'\fR ends in \f(CW\*(C`k\*(C'\fR, \f(CW\*(C`m\*(C'\fR, or \f(CW\*(C`g\*(C'\fR, it will be
multiplied by 1024, 1048576, and 1073741824, respectively, before being
returned. \f(CW\*(C`int\*(C'\fRs are truncated after being multiplied, if they have
a decimal portion.
.PP
\&\f(CW\*(C`bool\-or\-int\*(C'\fR, as you might have guessed, gives you either
a bool or an int depending on which one applies.
.PP
If \f(CW\*(C`as\*(C'\fR is unspecified, \f(CW\*(C`value\*(C'\fR is returned unchanged.
.SS "format_section"
.IX Subsection "format_section"
Parameters:
.PP
.Vb 2
\&    section => \*(Aqsection.subsection\*(Aq
\&    base => 1
.Ve
.PP
Return a string containing the section/subsection header, formatted
as it should appear in a config file. If \f(CW\*(C`bare\*(C'\fR is true, the returned
value is not followed be a newline.
.SS "format_definition"
.IX Subsection "format_definition"
Parameters:
.PP
.Vb 3
\&    key => \*(Aqstr\*(Aq
\&    value => \*(Aqstr\*(Aq
\&    bare => 1
.Ve
.PP
Return a string containing the key/value pair as they should be printed in the
config file. If \f(CW\*(C`bare\*(C'\fR is true, the returned value is not tab-indented nor
followed by a newline.
.SH "DIFFERENCES FROM GIT-CONFIG"
.IX Header "DIFFERENCES FROM GIT-CONFIG"
This module does the following things differently from git-config:
.PP
We are much more permissive about valid key names and section names.
For variables, instead of limiting variable names to alphanumeric characters
and \-, we allow any characters except for = and newlines, including spaces as
long as they are not leading or trailing, and . as long as the key name is
quoted. For sections, any characters but whitespace, [], and " are allowed.
You can enforce reading/writing only git-compatible variable names and section
headers by passing \f(CW\*(C`compatible => 1\*(C'\fR to the constructor.
.PP
When replacing variable values and renaming sections, we merely use
a substring replacement rather than writing out new lines formatted in the
default manner for new lines. Git's replacement/renaming (as of
1.6.3.2) is currently buggy and loses trailing comments and variables
that are defined on the same line as a section being renamed. Our
method preserves original formatting and surrounding information.
.PP
We also allow the 'num' type for casting, since in many cases we
might want to be more lenient on numbers.
.PP
We truncate decimal numbers that are cast to \f(CW\*(C`int\*(C'\fRs, whereas
Git just rejects them.
.PP
We don't support NUL-terminating output (the \-\-null flag to
git-config). Who needs it?
.SH "BUGS"
.IX Header "BUGS"
If you find any bugs in this module, report them at:
.PP
.Vb 1
\&  http://rt.cpan.org/
.Ve
.PP
Include the version of the module you're using and any relevant problematic
configuration files or code snippets.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
<http://www.kernel.org/pub/software/scm/git/docs/git\-config.html#_configuration_file>,
Config::GitLike::Git, <http://syncwith.us/> (\f(CW\*(C`Config::GitLike\*(C'\fR is
used in Prophet/SD and provides a working example)
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you may modify and/or redistribute it
under the same terms as Perl itself.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2010 Best Practical Solutions, \s-1LLC\s0
.SH "AUTHORS"
.IX Header "AUTHORS"
Alex Vandiver <alexmv@bestpractical.com>,
Christine Spang <spang@bestpractical.com>