view release on metacpan or  search on metacpan

lib/Config/GitLike.pm  view on Meta::CPAN

=head1 OTHER METHODS

These are mostly used internally in other methods, but could be useful anyway.

=head2 load_global

If a global configuration file with the absolute name given by
L<"global_file"> exists, load its configuration variables into memory.

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.

=head2 load_user

If a configuration file with the absolute name given by
L<"user_file"> exists, load its config variables into memory.

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.

=head2 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).

This method can also be called as a class method, which will die if the
file cannot be read.  If called as an instance method, returns undef on
failure.

This method may also be passed additional key-value parameters which
control how the file is loaded:

=over

=item silent

Defaults to off; if set, merely returns instead of die'ing if the file
cannot be found or read.

=item includes

Defaults to on; if passed a false value, ignores the L</include>
directive.

=item force

Defaults to off; if set, will re-load a file even if it was previously
loaded.

=back

=head2 parse_content

Parameters:

    content => 'str'
    callback => sub {}
    error => sub {}

Parses the given content and runs callbacks as it finds valid information.

Returns undef on success and C<error($content)> (the original content) on
failure.

C<callback> is called like:

    callback(section => $str, offset => $num, length => $num, name => $str, value => $str)

C<name> and C<value> 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.

C<error> is called like:

    error( content => $content, offset => $offset )

Where C<offset> is the point in the content where the parse error occurred.

If you need to use this method, you might be interested in L<"error_callback">
as well.

=head2 error_callback

Parameters:

    content => 'str'
    offset => 45
    filename => '/foo/bar/.baz'

Made especially for passing to L<"parse_content">, passed through the
C<error> parameter like this:

    error => sub {
        error_callback( @_, filename => '/file/you/were/parsing' )
    }

It's used internally wherever L<"parse_content"> 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"> elsewhere, you may find it useful as well.

=head2 include ( $name )

When reading configuration files, Git versions 1.7.10 and later parse
the C<include.path> key as a directive to include an additional
configuration file.  This option controls the equivalent behavior;
setting it to a false value will disable inclusion, and any true value
will be taken as the name of the configuration parameter which controls
inclusion.  Defaults to C<include.path>, as Git does.

=head2 set_multiple( $name )

Mark the key string C<$name> as containing multiple values.

Returns nothing.

=head2 is_multiple( $name )

Return a true value if the key string C<$name> contains multiple values; false
otherwise.