Basic Syntax¶

As of V 2.30, this module supports the case of a key having an array of values.

Sample data (copied from t/test.conf):

        root=something
        [section]
        greetings[]=Hello
        one=two
        Foo=Bar
        greetings[]=World!
        this=Your Mother!
        blank=
        [Section Two]
        something else=blah
         remove = whitespace

Note specifically that the key name greetings has the empty bracket pair [] as a suffix. This tells the code that it is not to overwrite the 1st value with the 2nd value, but rather to push these values onto a stack called 'greetings'.

Note also that you could have used:

        [section]
        greetings[]=Hello
        greetings[]=World!
        one=two
        Foo=Bar
        this=Your Mother!
        blank=

Clearly, the 2 lines using greetings[] do not have to be side-by-side.

If you use e.g. Data::Dumper::Concise to give you a Dumper() function (not method), then 'say Dumper($Config)' the output will look like:

        bless( {
          "Section Two" => {
             remove => "whitespace",
             "something else" => "blah",
           },
           _ => {
             root => "something",
           },
           section => {
             Foo => "Bar",
             blank => "",
             greetings => [
               "Hello",
               "World!",
             ],
             one => "two",
             this => "Your Mother!",
           },
         }, 'Config::Tiny' )

You can see this structure in t/02.main.t starting at line 45. Observe too that the key names are reported in alphabetical order (by the module Data::Dumper::Concise) despite the differing order in the setting of these keys, and that the array syntax result is that greetings has an array for a value.

To access these values, use code like this:

        Dumper($Config);
        Dumper($Config->{section});
        Dumper($Config->{section}->{greetings});
        Dumper($Config->{section}->{greetings}->[0]);
        Dumper($Config->{section}->{greetings}->[1]);
        Dumper(ref $Config);

Warning¶

$Config is a blessed value, which means it is accessed differently than if it was a hash ref. The latter could be accessed as:

        Dumper($$Config{section}{greetings}); # Don't do this for blessed values!

Finally, if a hash ref rather than a blessed value, you could also use, as above:

        Dumper($Config->{section}->{greetings}); # Don't do this for blessed values!

My (Ron Savage) personal preference for hashrefs is the one without the gross '->' chars, but that requires you to double up the initial $ character (which I hope you noticed!).

errstr()¶

Returns a string representing the most recent error, or the empty string.

You can also retrieve the error message from the $Config::Tiny::errstr variable.

new([$config])¶

Here, the [] indicate an optional parameter.

The constructor "new" creates and returns a "Config::Tiny" object.

This will normally be a new, empty configuration, but you may also pass a hashref here which will be turned into an object of this class. This hashref should have a structure suitable for a configuration file, that is, a hash of hashes where the key "_" is treated specially as the root section.

read($filename, [$encoding])¶

Here, the [] indicate an optional parameter.

The "read" constructor reads a config file, $filename, and returns a new "Config::Tiny" object containing the properties in the file.

$encoding may be used to indicate the encoding of the file, e.g. 'utf8' or 'encoding(iso-8859-1)'.

Do not add a prefix to $encoding, such as '<' or '<:'.

Returns the object on success, or "undef" on error.

When "read" fails, "Config::Tiny" sets an error message internally you can recover via "Config::Tiny->errstr". Although in some cases a failed "read" will also set the operating system error variable $!, not all errors do and you should not rely on using the $! variable.

See t/04.utf8.t and t/04.utf8.txt.

read_string($string)¶

The "read_string" method takes as argument the contents of a config file as a string and returns the "Config::Tiny" object for it.

write($filename, [$encoding])¶

Here, the [] indicate an optional parameter.

The "write" method generates the file content for the properties, and writes it to disk to the filename specified.

$encoding may be used to indicate the encoding of the file, e.g. 'utf8' or 'encoding(iso-8859-1)'.

Do not add a prefix to $encoding, such as '>' or '>:'.

Returns true on success or "undef" on error.

See t/04.utf8.t and t/04.utf8.txt.

write_string()¶

Generates the file content for the object and returns it as a string.

What happens if a key is repeated?¶

Case 1: The last value is retained, overwriting any previous values.

See t/06.repeat.key.t for sample code.

Case 2: However, by using the new array syntax, as of V 2.30, you can assign a set of values to a key.

For details, see the "ARRAY SYNTAX" section above for sample code.

See t/test.conf for sample data.

Why can't I put comments at the ends of lines?¶

o The # char is only introduces a comment when it's at the start of a line.

So a line like:

        key=value # A comment
    

Sets key to 'value # A comment', which, presumably, you did not intend.

This conforms to the syntax discussed in "CONFIGURATION FILE SYNTAX".

o Comments matching /\s\;\s.+$//g; are ignored.

This means you can't preserve the suffix using:

        key = Prefix ; Suffix
    

Result: key is now 'Prefix'.

But you can do this:

        key = Prefix;Suffix
    

Result: key is now 'Prefix;Suffix'.

Or this:

        key = Prefix; Suffix
    

Result: key is now 'Prefix; Suffix'.

See t/07.trailing.comment.t.

Why can't I omit the '=' signs?¶

E.g.:

        [Things]
        my =
        list =
        of =
        things =

Instead of:

        [Things]
        my
        list
        of
        things

Because the use of '=' signs is a type of mandatory documentation. It indicates that that section contains 4 items, and not 1 odd item split over 4 lines.

Why do I have to assign the result of a method call to a variable?¶

This question comes from RT#85386.

Yes, the syntax may seem odd, but you don't have to call both new() and read_string().

Try:

        perl -MData::Dumper -MConfig::Tiny -E 'my $c=Config::Tiny->read_string("one=s"); say Dumper $c'

Or:

        my($config) = Config::Tiny -> read_string('alpha=bet');
        my($value)  = $$config{_}{alpha}; # $value is 'bet'.

Or even, a bit ridiculously:

        my($value) = ${Config::Tiny -> read_string('alpha=bet')}{_}{alpha}; # $value is 'bet'.

Can I use a file called '0' (zero)?¶

Yes. See t/05.zero.t (test code) and t/0 (test data).