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 mithun@cpan.org 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.