MMDS::Properties 1.902

MMDS::Properties Perl module contains flexible properties handling for MMDS.
use MMDS::Properties;
my $cfg = new MMDS::Properties;
# Preset a property.
$cfg->set_property("config.version", "1.23");
# Parse a properties file.
$cfg->parsefile("config.prp");
# Get a property value
$version = $cfg->get_property("config.version");
# Same, but with a default value.
$version = $cfg->get_property("config.version", "1.23");
# Get the list of subkeys for a property, and process them.
my $aref = $cfg->get_property_keys("item.list");
foreach my $item ( @$aref ) {
if ( $cfg->get_property("item.list.$item") ) {
....
}
}
The property mechanism is modelled after the Java implementation of properties.
In general, a property is a string value that is associated with a key. A key is a series of names (identifiers) separated with periods. Names are treated case insensitive. Unlike in Java, the properties are really hierarchically organized. This means that for a given property you can fetch the list of its subkeys, and so on. Moreover, the list of subkeys is returned in the order the properties were defined.
Property lookup can use a preset property context. If a context ctx has been set using set_context(ctx), get_property(foo.bar) will first try ctx.foo.bar and then foo.bar. get_property(.foo.bar) (note the leading period) will only try ctx.foo.bar and raise an exception if no context was set.
Design goals:
- properties must be hierarchical of unlimited depth;
- manual editing of the property files (hence unambiguous syntax and lay out);
- it must be possible to locate all subkeys of a property in the order they appear in the property file(s);
- lightweight so shell scripts can use it to query properties.
METHODS
new
new is the standard constructor. new doesnt require any arguments, but you can pass it a list of initial properties to store in the resultant properties object.
new
clone is like new, but it takes an existing properties object as its invocant and returns a new object with the contents copied.
WARNING This is not yet a deep copy, so take care.
parsefile file [ , path [ , context ] ]
parsefile reads a properties file and adds the contents to the properties object.
file is the name of the properties file. This file is searched in all elements of path (an array reference) unless the name starts with a slash. Default path is . (current directory).
context can be used to designate an initial context where all properties from the file will be subkeys of.
For the detailed format of properties files see below.
get_property prop [ , default ]
Get the value for a given property prop.
If a context ctx has been set using set_context(ctx), get_property(foo.bar) will first try ctx.foo.bar and then foo.bar. get_property(.foo.bar) (note the leading period) will only try ctx.foo.bar and raise an exception if no context was set.
If no value can be found, default is used.
In either case, the resultant value is examined for references to other properties or environment variables. Such a reference looks like
${name}
${name:default}
name can be the name of an environment variable or property. If name is found in the environment, its value is substituted and the expansion process continues, re-examining the new contents, until no further substitutions can be made. If a non-empty value exists for the property name its value is used in a similar way. Hence an empty value for a property will be ignored. If no value can be found, the default string (not to be confused with the default parameter) will be returned.
As an additional service, a tilde ~ in what looks like a file name will be expanded to ${HOME}.
The method result_in_context can be used to determine how the result was obtained. It will return a non-empty string indicating the context in which the result was found, an emptry string indicating the result was found without context, or undef if no value was found at all.
get_property_noexpand prop [ , default ]
This is like get_property, but does not do any expansion.
gps prop [ , default ]
This is like get_property, but raises an exception if no value could be established.
This is probably the best and safest method to use.
get_property_keys prop
Returns an array reference with the names of the (sub)keys for the given property. The names are unqualified, e.g., when properties foo.bar and foo.blech exist, get_property_keys(foo) would return [bar, blech].
expand value [ , context ]
Perform the expansion as described with get_property.
set_property prop, value
Set the property to the given value.
set_properties prop1 => value1, ...
Add a hash (key/value pairs) of properties to the set of properties.
set_context context
Set the search context. Without argument, clears the current context.
get_context
Get the current search context.
result_in_context
Get the context status of the last search.
Empty means it was found out of context, a string indicates the context in which the result was found, and undef indicates search failure.
dump [ start [ , stream ] ]
Produce a listing of all properties from a given point in the hierarchy and write it to the stream.
stream defaults to *STDOUT.
dumpx [ start [ , stream ] ]
Like dump, but dumps with all values expanded.