view release on metacpan or  search on metacpan

lib/ChordPro/Config/Properties.pm  view on Meta::CPAN

=head2 Arrays

When a property has a number of sub-properties with keys that are
consecutive numbers starting at C<0>, it may be considered as an
array. This is only relevant when using the data() method to retrieve
a Perl data structure from the set of properties.

    list {
       0 = aap
       1 = noot
       2 = mies
    }

When retrieved using data(), this returns the Perl structure

    [ "aap", "noot", "mies" ]

For convenience, arrays can be input in several more concise ways:

    list = [ aap noot mies ]
    list = [ aap
             noot
             mies ]

The opening bracket must be followed by one or more values. This will
currently not work:

    list = [
             aap
             noot
             mies ]

=head2 Includes

Property files can include other property files:

    include "myprops.prp"

All properties that are read from the file are entered in the current
context. E.g.,

    foo {
      include "myprops.prp"
    }

will enter all the properties from the file with an additional C<foo.>
prefix.

=head2 Expansion

Property values can be anything. The value will be I<expanded> before
being assigned to the property unless it is placed between single
quotes C<''>.

Expansion means:

=over

=item *

A tilde C<~> in what looks like a file name will be replaced by the
value of C<${HOME}>.

=item *

If the value contains C<${I<name>}>, I<name> is first looked up in the
current environment. If an environment variable I<name> can be found,
its value is substituted.

If no suitable environment variable exists, I<name> is looked up as a
property and, if it exists and has a non-empty value, this value is
substituted.

Otherwise, the C<${I<name>}> part is removed.

Note that if a property is referred as C<${.I<name>}>, I<name> is
looked up in the current context only.

B<Important:> Property lookup is case insensitive, B<except> for the
names of environment variables B<except> on Microsoft Windows
where environment variable names are looked up case insensitive.

=item *

If the value contains C<${I<name>:I<value>}>, I<name> is looked up as
described above. If, however, no suitable value can be found, I<value>
is substituted.

=back

Expansion is delayed if single quotes are used around the value.

    x = 1
    a = ${x}
    b = "${x}"
    c = '${x}'
    x = 2

Now C<a> and C<b> will be C<'1'>, but C<c> will be C<'2'>.

Substitution is handled by L<String::Interpolate::Named>. See its
documentation for more power.

In addition, you can test for a property being defined (not null) by
appending a C<?> to its name.

    result = ${x?|${x|value|empty}|null}

This will yield C<value> if C<x> is not null and not empty, C<empty>
if not null and empty, and C<null> if not defined or defined as null.

=head1 SEE ALSO

L<File::LoadLines>, L<String::Interpolate::Named>.

=head1 BUGS

Although in production for over 25 years, this module is still
slightly experimental and subject to change.

=head1 AUTHOR