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).