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



TODO


Provide support for remembering property format and order when parsed



AUTHOR


Mithun Ayachit [email protected]



LICENSE AND COPYRIGHT


Copyright (c) 2014, 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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.