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.

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 at https://github.com/mithun/perl-config-properties-commons/issues

TODO

Provide support for remembering property format and order when parsed

AUTHOR

Mithun Ayachit mithun@cpan.org

LICENSE AND COPYRIGHT

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

To install Config::Properties::Commons, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Config::Properties::Commons

CPAN shell

perl -MCPAN -e shell
install Config::Properties::Commons

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

PROPERITES FILE SYNTAX

METHODS

new(%options)

Options

Reading and Writing Files

load($file, \%options)

save($file, \%options)

save_to_string(\%options)

get_files_loaded()

Get Properties

get_property($key)

require_property($key)

properties($prefix, $separator)

property_names()

is_empty()

has_property($key)

Set Properties

add_propertry( key => 'value' )

delete_property($key)

reset_property( key => 'value' )

clear_properties()

SEE ALSO

DEPENDENCIES

BUGS AND LIMITATIONS

TODO

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions

`new(%options)`

`load($file, \%options)`

`save($file, \%options)`

`save_to_string(\%options)`

`get_files_loaded()`

`get_property($key)`

`require_property($key)`

`properties($prefix, $separator)`

`property_names()`

`is_empty()`

`has_property($key)`

`add_propertry( key => 'value' )`

`delete_property($key)`

`reset_property( key => 'value' )`

`clear_properties()`