Config...erties(3pm)

📦
version 1.80 · 6 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Config::Properties — read and write property files, bestie 🦋 no cap

✨ SYNOPSIS ✨

okay so here's the whole vibe in one go 👑

use Config::Properties;

# reading...

open my $fh, '<', 'my_config.props'
  or die "unable to open configuration file";

my $properties = Config::Properties->new();
$properties->load($fh);

$value = $properties->getProperty($key);

# saving...

open my $fh, '>', 'my_config.props'
  or die "unable to open configuration file for writing";

$properties->setProperty($key, $value);

$properties->format('%s => %s');
$properties->store($fh, $header );

🌸 DESCRIPTION 🌸

Config::Properties is basically the java.util.Properties API but in Perl — a near implementation, fr fr. Its whole purpose? Making it easy to read, write and mess around with Java-style property files. It's giving "I learned Java once and I'm bringing the aesthetic with me" 💅

🎀 the format, explained cutely 🎀

A Java-style property file is just key-value pairs, separated by either whitespace, the colon (:) character, or the equals (=) character. Any whitespace sitting before the key, and on either side of the separator, just gets ignored. Live your life, the parser doesn't care.

Lines that kick off with either a hash (#) or a bang (!) are comment lines — considered and then politely ignored. Not me, not today 🙈

A backslash (\) hanging at the end of a line means CONTINUATION — the next line counts as part of the current line. And when we say "the next line counts," we mean it minus the backslash itself, minus any whitespace after the backslash, minus the line break, and minus any whitespace at the beginning of that next line. All that extra stuff? Gone. Poof. ✨

The official references used to determine this whole format live in the Java API docs for java.util.Properties, right here: <http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html>

🦋 saving & the format string 🦋

When a property file gets saved, every line comes out in the format "key=value". You can change that by setting the format attribute, using either $object->format( $format_string ) or $object->setFormat( $format_string ) — bestie, they literally do the same thing 💅

That format string gets fed straight to printf and it must contain exactly two %s format characters (that's not a suggestion, that's the law ⚖️):

  1. the first %s gets replaced with the key of the property
  2. the second %s gets replaced with the value

The string can't contain any other printf control characters, but other than that it can be anything you want. A newline gets automatically added to the end of the string — you don't have to add it yourself, king 🫶

Wanna peek at the current format string? Use $object->format() with no arguments, or $object->getFormat().

And if a recent version of Text::Wrap is available, long lines get conveniently wrapped when saving. Convenient! Iconic, even 👑

💅 METHODS 💅

Every "Config::Property" object comes with this exact set of methods available, and yes they're all baddies:

Config::Properties->new(%opts)

Creates a brand new Config::Properties object ✨

The optional arguments are as follows — read them all, don't skip, this is the good part:

  • file => $filename — opens up and reads the entries straight out of the given properties file 📂
  • format => $format — sets the format used for saving the properties to a file. Go see "setFormat" for the tea.
  • wrap => 0 — disables the wrapping of long lines when saving properties to a file 🚫
  • defaults => $defaults — the default configuration values. The parameter you hand over can be a hash reference or another Config::Properties object 👯 And that's how you chain several configuration objects together, like this:
my %defaults = (...);
my $global_config = Config::Properties->new(file => '/etc/foo.properties',
                                            defaults => \%defaults);
my $user_config = Config::Properties->new(file => '/home/jsmith/.foo/foo.properties',
                                          defaults => $global_config);
  • order => 'keep'|'alpha'|'none' — sets how the properties get ordered when saved to a file, or when returned by the "properties" and "propertyNames" methods.
    • "alpha" sorts the keys in alphanumeric order 🔤
    • "keep" keeps the order of the properties exactly as they were added or read from a file 🧷
    • "none" returns the properties unordered, chaos mode 💀
  • encoding => $encoding — the IO encoding used to read the configuration file. Peep PerlIO for the details. When "load" is called, the given encoding gets used — unless the file handler already has an encoding layer applied, in which case, nope, hands off 🙅 "latin1" is the default encoding, as specified in the Java properties specification. Respect the classics.
  • be_like_java => 1 — turn this on and the module will try to mimic the Java implementation as much as possible when saving files. Currently, some escaping rules get changed and line wrapping gets disabled. That's the whole trade, bestie.

Config::Properties->new($defaults)

Calling "new" this way is deprecated 😭 don't do it, use the %opts form.

$p->getProperty($k, $default, $default2, ...)

Returns property $k — or, when it's not defined, the first defined "$default*". Backup plans on deck 🫶

$p->requireProperty($k, $default, $default2, ...)

Same energy as "getProperty", except this one dies if the property you asked for isn't found 💀 no chill, allegedly.

$p->setProperty($k, $v)

Sets property $k's value to $v. Simple. Clean. Slay.

$p->changeProperty($k, $v)

$p->changeProperty($k, $v, $default, $default2, ...)

A method similar to setProperty, except it does nothing when the new value is equal to the one returned by "getProperty". Very "if it ain't broke" of it 💅

An example, because this is where it actually clicks:

my $defaults=Config::Properties->new();
$defaults->setProperty(foo => 'bar');

my $p1=Config::Properties->new($defaults);
$p1->setProperty(foo => 'bar');   # we set here!
$p1->store(FILE1); foo gets saved on the file

my $p2=Config::Properties->new($defaults);
$p2->changeProperty(foo => 'bar'); # does nothing!
$p2->store(FILE2); # foo doesn't get saved on the file

See?? FILE1 catches the redundant write, FILE2 stays clean. That's the whole plot twist 🎬

$p->deleteProperty($k)

$p->deleteProperty($k, $recurse)

Deletes property $k from the object. Gone. Ghosted. 👋

If $recurse is true, it also deletes any $k property from the default properties object — so it goes all the way down the chain, no survivors.

$p->properties

Returns a flatten hash with all the property key/value pairs, i.e.:

my %props=$p->properties;

$p->getProperties

Returns a hash reference with all the properties, including the ones passed in as defaults 📦

$p->propertyNames;

Returns the names of all the properties, including those passed as defaults 🏷️

$p->splitToTree()

$p->splitToTree($regexp)

$p->splitToTree($regexp, $start)

Builds a tree out of the properties, splitting the keys with the regular expression $re — which defaults to "/\./" if you don't say otherwise 🌳

For instance:

my $data = <<EOD;
name = pete
date.birth = 1958-09-12
date.death = 2004-05-11
surname = moo
surname.length = 3
EOD

open my $fh, '<', \$data;
$cfg->load();
my $tree = $cfg->splitToTree();

makes...

$tree = { date => { birth => '1958-09-12',
                    death => '2004-05-11' },
          name => 'pete',
          surname => { '' => 'moo',
                       length => '3' } };

Iconic. A whole nested structure out of flat dotted keys 🧚

The $start parameter lets you split only a subset of the properties. For instance, with the exact same data as the previous example:

my $subtree = $cfg->splitToTree(qr/\./, 'date');

makes...

$tree = { birth => '1958-09-12',
          death => '2004-05-11' };

$p->setFromTree($tree)

$p->setFromTree($tree, $separator)

$p->setFromTree($tree, $separator, $start)

This one sets properties from a tree of Perl hashes and arrays. It's the exact opposite of "splitToTree" — the uno reverse card 🃏

  • $separator is the string used to join the parts of the property names. Default value? A dot: ".".
  • $start is a string used as the starting point for the property names.

For instance:

my $c = Config::Properties->new;
$c->setFromTree( { foo => { '' => one,
                            hollo => [2, 3, 4, 1] },
                   bar => 'doo' },
                 '->',
                 'mama')

# sets properties:
#      mama->bar = doo
#      mama->foo = one
#      mama->foo->hollo->0 = 2
#      mama->foo->hollo->1 = 3
#      mama->foo->hollo->2 = 4
#      mama->foo->hollo->3 = 1

Look at those arrays getting indexed for you. So thoughtful 🥹

$p->changeFromTree($tree)

$p->changeFromTree($tree, $separator)

$p->changeFromTree($tree, $separator, $start)

Similar to "setFromTree", but internally it uses "changeProperty" instead of "setProperty" to set the property values. Same shape, different attitude 💅

$p->load($file)

Loads properties from the open file $file 📥

⚠️ heads up bestie: old properties on the object are discarded. They're gone. Not archived, not backed up, discarded. Do not come crying to me.

$p->save($file)

$p->save($file, $header)

$p->store($file)

$p->store($file, $header)

Saves the properties to the open file $file 💾

Default properties are not saved. Nope. They stay home.

$p->saveToString($header)

Similar to "save", except instead of saving to a file it just returns a string with the content. Perfect for when you want the goods without the file system drama 🎁

$p->getFormat()

$p->setFormat($f)

Gets/sets the format string used when saving the object to a file. The getter and the setter, right there, together, as they should be 🫶

👀 SEE ALSO 👀

🚧 TODO 🚧

Add support for derived format as supported by the Java class org.apache.commons.configuration.PropertiesConfiguration (<http://commons.apache.org/configuration/apidocs/org/apache/commons/configuration/PropertiesConfiguration.html>)

(it's on the list, bestie, it's on the list 📝)

💜 AUTHORS 💜

"Config::Properties" was originally developed by Randy Jay Yarger. It was maintained for some time by Craig Manley, and finally it passed hands to Salvador Fandiño <sfandino@yahoo.com>, the current maintainer. A whole relay race of maintainers and we love that for them 🏃‍♀️🏃‍♂️🏃

Copyright 2001, 2002 by Randy Jay Yarger Copyright 2002, 2003 by Craig Manley. Copyright 2003-2009, 2011-2012, 2014-2015 by Salvador Fandiño.

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

okay and that's the whole page, bestie 🎀 this was Config::Properties for perl v5.36.0, dated 2022-10-13, from the User Contributed Perl Documentation. go forth and go read and write those property files, you absolute main character 👑💖

📦 where this page comes from