NAME
====

Config::Properties::Commons - Read and write Apache Commons
Configuration style Properties

SYNOPSIS
========

    use Config::Properties::Commons;

    # Read
    # =====

    # Init
    my $cpc = Config::Properties::Commons->new();

    # Load
    $cpc->load('conf.properties');

    # Access
    my $value = $cpc->get_property('key');

    # Flattened hash
    my %properties = $cpc->properties();

    # Write
    # =====

    # Init
    my $cpc = Config::Properties::Commons->new();

    # Set
    $cpc->set_property( key => 'value' );

    # Save
    $cpc->save('conf.properties');

DESCRIPTION
===========

Config::Properties::Commons is an attempt to provide a Perl API to read
and write Apache Commons Configuration style .properties files.

This module is an extension of Config::Properties and provides a similar
API, but is not fully backwards compatible.

PROPERITES FILE SYNTAX
======================

A sample file syntax recognized by this module is shown below.

    # This line is a comment
    ! This is a comment as well

    # Key value pairs can be separated by '=', ':' or whitespace
    key1 = value1
    key2 : value2
    key3   value3

    # Keys can contain multiple values that are either
    #   1. Specified on multiple lines
    #   2. OR delimiter(',') separated
    key1 = value1.1
    key1 = value1.2
    key2 = value2.1, value2.2

    # Long values can span multiple lines by including a
    # '\' escape at the end of a line
    key = this is a \
            multi-line value

    # Property files can _include_ other files as well
    include = file1, file2, ....

    # Values can reference previous parsed properties
    base   = /etc/myapp
    config = ${base}/config

The complete syntax reference can be found at the
PropertiesConfiguration API Doc.

METHODS
=======

new(%options)
-------------

    my $cpc = Config::Properties::Commons->new(\%options);

This creates and returns a Config::Properties::Commons object.

Options
-------

The following options can be provided to the constructor.

-   token_delimiter

    This option specifies the delimiter used to split a value into
    multiple tokens. The default is a ','. You can set this to undef to
    disable splitting.

-   include_keyword

    Use this option to set the keyword that identifies additional files
    to load. The default is include.

-   includes_basepath

    Use this option to set the base path for files being loaded via an
    include. By default, files are expected to be in the same directory
    as the parent file being loaded. If we are loading from a file
    handle, then additional files are expected to be in the current
    directory.

-   process_includes

    Use this option to toggle whether additional files are loaded via
    include or not. Defaults to true.

-   cache_files

    Use this option to toggle file caching. If enabled, then files are
    loaded only once. Disabling this is not recommended as it might lead
    to circular references. Default is enabled.

-   interpolation

    Use this option to toggle property references/interpolation.
    Defaults to true.

-   force_value_arrayref

    When set to true, all values are stored as an array-ref. Otherwise,
    single values are stored as a scalar and multiple values are stored
    as an array-ref. Default is false.

-   callback

    This should be a code reference, which is called when a key/value
    pair is parsed. The callback is called with 2 arguments for $key and
    $value respectively, and expects the same to be returned as a list.

    This allows you to hook into the parsing process to normalize or
    perform additional operations when a key/value is parsed.

        # Example to read case-insensitve properties
        my $cpc = Config::Properties::Commons->new({
            callback => sub {
                my ($_k, $_v) = @_;
                $_k = lc($_k);
                return ( $_k, $_v );
            },
        });

-   defaults

    You can provide a default set of properties as a hash-ref to the
    object.

-   load_file

    Requires a filename. This is a short-circuit for
    new(); load($file);. When used with the constructor, the file is
    loaded before returning.

-   save_combine_tokens

    When true, keys with multiple values are joined using the
    token_delimiter and written to a single line. Otherwise they are
    saved/written on multiple lines. Defaults to false.

-   save_wrapped

    When true, long values are wrapped before being saved. Defaults to
    true.

-   save_wrapped_len

    Use this option to set the maximum line length when wrapping long
    values. This option is ignored if wrapping is disabled. Defaults to
    76.

-   save_separator

    Use this option to set the key/value separator to be used when
    saving. Defaults to ' = '.

-   save_sorter

    This option should provide a sort SUBNAME as specified by sort.

    This is used for sorting property names to decide the order in which
    they are saved. Defaults to a case-insensitive alphabetical sort.

-   save_header

    You can use this to specify a header used when saving.

-   save_footer

    You can use this to specify a footer used when saving.

-   Option Aliases

    The following aliases can be used for the options specified above.
    This is mainly available for API compatibility and ease of use.

        # Option Name           Aliases
        # ------------          ----------------------------------
        token_delimiter         delimiter       setListDelimiter
        include_keyword         include         setInclude
        includes_basepath       basepath        setBasePath
        process_includes        includes_allow  setIncludesAllowed
        cache_files             cache
        interpolation           interpolate
        force_value_arrayref    force_arrayref
        callback                validate
        load_file               filename
        save_combine_tokens     single_line
        save_wrapped            wrap
        save_wrapped_len        columns
        save_separator          separator
        save_header             header
        save_footer             footer

Reading and Writing Files
-------------------------

load($file, \%options)

    $cpc->load($file); # Parse and Load properties from a file
    $cpc->load($fh);   # Parse and Load properties from a file handle

This method reads, parses and loads the properties from a file-name or a
file-handle. The file is read through a ':utf8' layer. An exception is
thrown in case of parse failures.

load() is an additive operation. i.e, you can load multiple files and
any previously loaded properties are either updated or preserved.

    $cpc->load('file1');
    $cpc->load('file2');

Any options provided to the constructor can be set/overridden here as
well.

This method can also be called using the load_fh() or load_file()
aliases.

save($file, \%options)

    $cpc->save($file); # Saves properties to a file
    $cpc->save($fh);   # Saves properties to a file-handle

This method saves all properties set to a provided file or file-handle
via a ':utf8' layer. Existing files are overwritten. Original file
format or the order of properties set is not preserved.

Any options provided to the constructor can be set/overridden here as
well.

This method can also be called using the store() alias.

save_to_string(\%options)

    my $text = $cpc->save_to_string();

This is identical to save(), but returns a single string with the
content.

Any options provided to the constructor can be set/overridden here as
well.

This method can also be called using the save_as_string() or
saveToString() aliases.

get_files_loaded()

    my @file_list = $cpc->get_files_loaded();

This method returns a list of files loaded by the object. This, of
course, is available only when properties were loaded via file-names and
not handles. This also includes any include-ded files.

This method can also be called using the getFileNames() alias.

Get Properties
--------------

get_property($key)

    my $value = $cpc->get_property($key);

This method returns the value for $key or undef if a property for $key
is not set.

This method can also be called using the getProperty() alias.

require_property($key)

This method is similar to get_property(), but throws an exception if a
property for $key is not set.

This method can also be called using the requireProperty() alias.

properties($prefix, $separator)

    my %properties = $cpc->properties();

This method returns a flattened hashref (or hash in list context) of the
properties set in the object.

If a $prefix is specified, only properties that begin with $prefix is
returned with the $prefix removed. For e.g.,

    # Properties
    env.key1 = value1
    env.key2 = value2

    # Get all 'env' properties
    my %env_props = $cpc->properties('env');

    # Now %env_props looks like -
    %env_props = (
        key1 => 'value1',
        key2 => 'value2',
    );

The default seaparator '.' can be overridden using the second argument.

This method can also be called using the getProperties() or subset()
aliases.

property_names()

    my @names = $cpc->propery_names();

This method returns a list of property names set in the object.

This method can also be called using the propertyNames() or getKeys()
aliases.

is_empty()

    say "No properties set" if $cpc->is_empty();

This method returns true if there are no properties set. False
otherwise.

This method can also be called using the isEmpty() alias.

has_property($key)

    say "foo is set" if $cpc->has_property('foo');

This method returns true if a property for $key is set. False otherwise.

This method can also be called using the containsKey() alias.

Set Properties
--------------

add_propertry( key => 'value' )

    $cpc->add_property( key  => 'value1' );
    $cpc->add_property( key  => 'value2' );
    $cpc->add_property( key2 => [ 'value1', 'value2' ] );

This method sets a new property or adds values to existing properties.
Old properties are not forgotten.

Values can be a scalar or an array-ref for multiple values.

This method can also be called using the addProperty() alias.

delete_property($key)

    $cpc->delete_property('foo');

This method deletes a property specified by $key from the object.

This method can also be called using the clearProperty() or
deleteProperty() aliases.

reset_property( key => 'value' )

This method is equivalent to
delete_property('key'); add_property(key => 'value' ); - which means any
previously set property is forgotten.

This method can also be called using the set_property(), setProperty(),
or changeProperty() aliases.

clear_properties()

    $cpc->clear_properties();

This method deletes all properties loaded.

This method can also be called using the clear() alias.

SEE ALSO
========

-   Config::Properties
-   PropertiesConfiguration JavaDoc

DEPENDENCIES
============

-   perl-5.8.1
-   Encode
-   File::Basename
-   File::Slurp
-   File::Spec
-   List::Util
-   Params::Validate
-   String::Util
-   Text::Wrap

BUGS AND LIMITATIONS
====================

Please report any bugs or feature requests to
bug-config-properties-commons@rt.cpan.org, or through the web interface
at
http://rt.cpan.org/Public/Dist/Display.html?Name=Config-Properties-Commons

TODO
====

Provide support for remembering property format and order when parsed

AUTHOR
======

Mithun Ayachit mithun@cpan.org

LICENSE AND COPYRIGHT
=====================

Copyright (c) 2012, Mithun Ayachit. All rights reserved.

This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See perlartistic.
