view release on metacpan or  search on metacpan

lib/Config/Model/Backend/Any.pm  view on Meta::CPAN

    backend    => 'Foo' , # can also be 'foo'
    config_dir => '/etc/cfg_dir'
    file       => 'foo.conf', # optional
 }

(The backend class name is constructed with C<ucfirst($backend_name)>)

C<rw_config> can also have custom parameters that are passed
verbatim to C<Config::Model::Backend::Foo> methods:

 rw_config  => {
    backend    => 'Foo' , # can also be 'foo'
    config_dir => '/etc/cfg_dir'
    file       => 'foo.conf', # optional
    my_param   => 'my_value',
 }

C<Config::Model::Backend::Foo> class must inherit (extend)
L<Config::Model::Backend::Any> and is expected to provide the
following methods:

=over

=item read

C<read> is called with the following parameters:

 %custom_parameters,       # e.g. my_param   => 'my_value' in the example above
 object     => $obj,         # Config::Model::Node object
 root       => $root_dir,  # fake root directory, used for tests
 backend    => $backend,   # backend name
 config_dir => $read_dir,  # path below root
 file       => 'foo.conf', # file name
 file_path  => $full_name, # Path::Tiny object
 check      => [yes|no|skip]

The L<IO::File> object is undef if the file cannot be read.

This method must return 1 if the read was successful, 0 otherwise.

Following the C<my_param> example above, C<%custom_parameters> contains
C< ( 'my_param' , 'my_value' ) >, so C<read()> is called with
C<root>, C<config_dir>, C<file_path> B<and>
C<<  my_param   => 'my_value' >>.

=item write

C<write> is called with the following parameters:

 %$custom_parameters,         # e.g. my_param   => 'my_value' in the example above
 object      => $obj,         # Config::Model::Node object
 root        => $root_dir,    # fake root directory, used for tests
 auto_create => $auto_create, # boolean specified in backend declaration
 auto_delete => $auto_delete, # boolean specified in backend declaration
 backend     => $backend,     # backend name
 config_dir  => $write_dir,   # override from instance
 file        => 'foo.conf',   # file name
 file_path   => $full_name, # full file name (root+path+file)
 write       => 1,            # always
 check       => [ yes|no|skip] ,
 backup      => [ undef || '' || suffix ] # backup strategy required by user

The L<IO::File> object is undef if the file cannot be written to.

This method must return 1 if the write was successful, 0 otherwise

=back

=head2 How to test your new backend

Using L<Config::Model::Tester>, you can test your model with your
backend following the instructions given in L<Config::Model::Tester>.

You can also test your backend with a minimal model (and
L<Config::Model::Tester>). In this case, you need to specify
a small model to test in a C<*-test-conf.pl> file.
See the
L<IniFile backend test|https://github.com/dod38fr/config-model/blob/master/t/model_tests.d/backend-ini-test-conf.pl>
for an example and its
L<examples files|https://github.com/dod38fr/config-model/tree/master/t/model_tests.d/backend-ini-examples>.

=head1 CONSTRUCTOR

=head2 new

The constructor should be used only by L<Config::Model::Node>.

Parameter:

=over

=item node

Calling node object. Node ref is weakened,

=item name

Backend name

=item auto_create

Boolean. Set to true to create the configuration file if this one is
missing (default 0)

=item auto_delete

Boolean. Set to true to remove the configuration file if this one no
longer contain configuration information. (default 0)

=back

=head1 Methods to override

=head2 annotation

Whether the backend supports reading and writing annotation (a.k.a
comments). Default is 0. Override this method to return 1 if your
backend supports annotations.

=head2 read