NAME

Config::Ant - load Ant-style property files

SYNOPSIS

  # In your configuration file
  root.directory = /usr/local

  lib = ${root.directory}/lib
  bin = ${root.directory}/lib
  perl = ${bin}/perl
  
  # In your program
  use Config::Ant;
  
  # Create a config
  my $config = Config::Ant->new();

  # Read the config
  $config->read('file1.conf');
  
  # You can also read a second file, with properties substituted from the first
  $config->read('file2.conf');
  
  my $rootdir = $config->{_}->{'root.directory'};
  my $perl = $config->{_}->{perl};
  
  # Writing ignores substitutions
  $config->write('files.conf');
  

DESCRIPTION

Apache Ant uses property files with substitutions in them, which are very helpful for maintaining a complex set of related properties. This component is a subclass of Config::Tiny which includes the Ant-style substitution systems.

Ant properties are set by their first definition and are then immutable, so a second definition will not affect anything, ever. This is handy, as you can override settings by putting local values first, and the loading files of defaults.

Note that the usage interface is not identical to Config::Tiny. This is because Config::Tiny assumes that each file is self-contained, and constructs a new object for it. This does not make sense for Ant-style files, which are often loaded from several files, allowing for local customization.

Also not that the file format is not identical to Ant, in that like Config::Tiny, Config::Ant allows "windows style" sections to be used. This can be handy, but it's an optional extra that will only annoy you if you use property names containing [ or ], which would be a very bad move.

METHODS

Config::Ant->new()

Returns a new property file processing instance, which can then be used as a container for properties read and written through the other methods.

read($file)

Reads a file (or file handle) into the property system. This reads the text and passes the string to read_string(). This method can be called many times for a single instance, and this is common when you want to handle several property files. The first property sets always wins, and there is no method defined to allow properties to be removed.

read_string($text)

Reads and processes the properties a line at a time. Comment lines and blanks are skipped, sections are set, and property lines passed to read_line()

read_line($section, $property, $value)

This sets the property, and can be overridden if required. The property will only be set if a value doesn't exist. The default method also handles the substitution of existing values into the value.

write($file)

Opens the file for writing, if necessary (i.e., not a file handle) and then writes out all the current properties, using write_string() to obtain the stringified property file text.

write_string()

Returns the stringified text for all the properties currently registered.

AUTHOR

Stuart Watt <stuart@morungos.com>

COPYRIGHT

Copyright 2010 by the authors.

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

SEE ALSO

Partly based on Config::Tiny.