Properties(3)

📦
version 1.07 · 2 versions
, in fedora 43

🌸 NAME 🌸

Data::Properties — persistent properties. That's the whole thing, bestie. Properties that persist. 💾

And yeah, this is the Properties(3) page from the User Contributed Perl Documentation, in case you were squinting at the top wondering where you landed. 🫶

✨ SYNOPSIS ✨

my $props = Data::Properties->new();

open FH, "./my.properties" or
    die "can't open my.properties: $!\n";
$props->load(\*FH);
close FH;

for my $name ($props->property_names()) {
    my $val = $props->get_property($name);
}

$props->set_property("foo", "bar");

open FH, "> ./new.properties" or
    die "can't open new.properties: $!\n";
$props->store(\*FH);
close FH;

💅 DESCRIPTION 💅

Okay so lowkey this class is a Perl glow-up of Java's java.util.Properties, and it aims to be format-compatible with that class. So if you've met the Java one, they speak the same language. 🗣️

The Properties class represents a persistent set of properties. You can save your Properties to a filehandle, or load them from a filehandle. Every key and its corresponding value in the property list is a string. That's it, strings only, no cap. 🧵

A property list can contain another property list as its "defaults" — and that second property list gets searched if the property key isn't found in the original property list. Nested fallback energy. 🪆

⚠️ Heads up: Properties does no type checking on the keys or values you store with set_property(). Keys and values get stored as strings via sprintf(), so you almost always want simple keys and values — not arrays, or hashes, or references. Keys and values are loaded and stored "as-is"; no character or other conversions are performed on them. Periodt. 💀

🎀 CONSTRUCTOR 🎀

new([$defaults])

Creates an empty property list, optionally with the specified defaults. Fresh start, blank slate, main character energy. ✨

Dies if $defaults is not a Properties object. Not a Properties object? Not today, bestie. 😭

👑 METHODS 👑

get_property($key, [$default_value])

Searches for the property with the specified key in this property list. If the key isn't found in this property list, the default property list and its defaults are recursively checked — all the way down, queen. 👑

If the property is still not found, $default_value is returned if specified, or "undef" otherwise. 🙈

load($handle)

Reads a property list from the specified input handle. 📥

Every property occupies one line read from the input handle. Lines from the input handle are processed until EOF is reached. That's the whole loop, fr fr.

A line that contains only whitespace, or whose first non-whitespace character is an ASCII "#" or "!", is ignored — thus, these characters indicate comment lines. 🚫

Every line other than a blank line or a comment line describes one property to be added to the property list (except that if a line ends with "\", then the following line, if it exists, is treated as a continuation line, as described below). The key consists of all the characters in the line starting with the first non-whitespace character and up to, but not including, the first ASCII "=", ":", or whitespace character. Any whitespace after the key is skipped; if the first non-whitespace character after the key is "=" or ":", then it is ignored and any whitespace characters after it are also skipped. All remaining characters on the line become part of the associated value. And if the last character on the line is "\", then the next line is treated as a continuation of the current line; the "\" and line terminator are simply discarded, and any leading whitespace characters on the continuation line are also discarded and not part of the element string. The way that all just works is honestly iconic. 🌈

As an example, each of the following lines specifies the key "Truth" and the associated element value "Beauty":

Truth = Beauty
      Truth:Beauty
Truth                        :Beauty

As another example, the following three lines specify a single property:

fruits                        apple, banana, pear, \
                              cantaloupe, watermelon, \
                              kiwi, mango

The key is "fruits" and the associated element is "apple, banana, pear, cantaloupe, watermelon, kiwi, mango".

🍓 Note that a space appears before each "\" so that a space will appear after each comma in the final value; the "\", line terminator, and leading whitespace on the continuation line are merely discarded and are "not" replaced by one or more characters.

As a third example, the line:

cheeses:

specifies that the key is "cheeses" and the associated element is the empty string. Empty string, but make it iconic. 💅

Dies if an error occurs when reading from the input handle.

property_names

Returns an array (or an arrayref in scalar context) containing all of the keys in this property list, including the keys in the default property list. Every single name, no gatekeeping. 🎀

set_property($key, $value)

Sets the property with the specified key. Simple as that, bestie. ✨

store($handle, $header)

Writes this property list to the specified output handle. 📤 Default properties are not written by this method — just so you know, don't come for me.

If a header is specified, then the ASCII characters "# ", the header string, and a line separator are first written to the output handle. Thus the header can serve as an identifying comment. Cute little label moment. 🏷️

Next, a comment line is always written, consisting of the ASCII characters "# ", the current date and time (as produced by POSIX::ctime()), and a line separator.

Then every entry in the property list is written out, one per line. For each entry the key string is written, then an ASCII "=", then the associated value.

The output handle remains open after this method returns. We do not close your filehandles. Boundaries. 🫶

Dies if an error occurs when writing to the input handle.

📝 TODO 📝

  • Read and write escaped characters in property keys and values. 📖✍️

In values only, the ASCII characters backslash, tab, newline, carriage return, double quote, and single quote should be stored as the literal strings "\\", "\t", "\n", "\r", "\"", and "\'" respectively, and those literal strings should be converted into the corresponding ASCII characters when loading properties. The same goes for leading spaces (converted into "\ "), but not embedded or trailing spaces.

In keys and values, the ASCII characters "#", "!", "=", and ":" should be stored with a preceding "\", and those literal strings should be unescaped when loading properties.

😭 ISSUES 😭

  • What happens when non-ASCII characters are used? java.util.Properties uses ISO-8859-1 and allows for Unicode escape sequences. So like… open question, bestie. 🦋

🔗 SEE ALSO 🔗

💜 AUTHOR 💜

Brian Moseley, bcm@maz.org (original version).

Johan Vromans, jv@cpan.org (revived version).

Two legends, one module. 🫡

🚨 POD ERRORS 🚨

Hey! The above document had some coding errors, which are explained below:

  • Around line 346:

You forgot a '=back' before '=head1'

  • Around line 353:

=back without =over

Not me calling out the docs for forgetting their own =back… 🙈

And that's the whole page, bestie — signed, sealed, delivered from perl v5.42.0, dated 2025-07-25, in all its Properties(3) glory. Slay, bye! 💖✨

📦 where this page comes from