NAME

Config::Model::AutoRead - Load on demand base class for configuration node

SYNOPSIS

  # top level config file name matches instance name
  $model->create_config_class 
  (
   config_class_name => 'OneAutoReadConfigClass',

   read_config  => [ { syntax => 'cds'},
                     { syntax => 'custom' ,
                       class => 'ProcessRead' ,
                       function => 'read_it'
                     }
                   ],
   write_config => { syntax => 'cds' } , # can be array ref also

   config_dir  => '/etc/my_config_dir',

   element => ...
  ) ;

  # config data will be written in /etc/my_config_dir/foo.cds
  my $instance = $model->instance(instance_name => 'foo') ;

DESCRIPTION

This class provides a way to specify how to read or write configuration data within the model (instead of writing dedicated perl code).

In other words, when a node object is created, all the configuration information are read during creation of the node.

This read/write can be done with:

• Config dump string (cds). I.e. a string that describes the content of a configuration tree. See Config::Model::Dumper.

• Ini files (written with Config::Tiny. See limitations in "Limitations depending on storage".

• Perl data structure (perl). See Config::Model::DumpAsData for details on the data structure.

• XML. Not yet implemented (ask the author if you're interested)

• Any format when the user provides a dedicated class and function to read and load the configuration tree.

When read, the object registers itself to the instance. Then the user can call the write_back method on the instance (See Config::Model::Instance) to write all configuration informations.

Built-in read write format

Currently, this class supports the following built-in formats:

cds

Config dump string. See Config::Model::Dumper.

ini

Ini files written by Config::Tiny.

Limitations depending on storage

Some storage system will limit the structure of the model you can map to the file.

Ini files limitation

Structure of the Config::Model must be very simple. Either:

• A single class with hash of leaves elements.

• 2 levels of classes. The top level has nodes elements. All other classes have only leaf elements.

Configuration class with auto read or auto write

read and write specification

A configuration class will be declared with optional read or write parameters:

  read_config  => [ { syntax => 'cds'} , 
                    { syntax => 'custom', class => 'Bar' ,  function => 'read_it'},
                  ],
  write_config => { syntax => 'cds'},

The various read method will be tried in order specified:

• First the cds file name which depend on the parameters used in model creation and instance creation: <model:config_dir>/<instance_name>.cds The syntax of the cds file is described in Config::Model::Dumper.

• A call to Bar::read_it with these parameters:

   (object => config_tree_root, conf_dir => config_file_location )

When a read operation is successful, the remaining read methods will be skipped.

When necessary (or required by the user), all configuration informations are written back using all the write method passed.

In the example above, only a cds file is written. But, both custom format and cds file are tried, this example is also an example of a graceful migration from a customized format to a cds format.

You can choose also to read and write only customized files :

  read_config  => { syntax => 'custom', class => 'Bar' ,  function => 'read_it'},
  write_config => { syntax => 'custom', class => 'Bar' ,  function => 'write_it'};

Or to read and write only cds files :

  read_config  => { syntax => 'cds'} ,
  write_config => { syntax => 'cds'} ,

To migrate from an old format to a new format:

  read_config  => [ { syntax => 'custom', class => 'OldFormat' ,  function => 'old_read'} ,
                    { syntax => 'custom', class => 'NewFormat' ,  function => 'new_read'} 
                  ],
  write_config => [ { syntax => 'custom', class => 'NewFormat' ,  function => 'write'   } ],

read write directory

You must also specify where to read or write configuration information. These informations can be read or written in the same directory :

  config_dir => '/etc/my_config_dir',

Or configuration informations can be read from one directory and written in another directory:

   read_config_dir  => '/etc/old_config_dir',
   write_config_dir => '/etc/new_config_dir',

AUTHOR

Dominique Dumont, (ddumont at cpan dot org)

SEE ALSO

Config::Model, Config::Model::Instance, Config::Model::Node, Config::Model::Dumper

cpanm Config::Model

perl -MCPAN -e shell
install Config::Model