view release on metacpan or  search on metacpan

lib/Config/MyConfig2.pm  view on Meta::CPAN

(type = multi)

  $value = $myconfig->GetGlobalValue('my_directive','some_identifier','foo')
  $value_array_ref = $myconfig->GetGlobalValue('foo')

=head2 SetGlobalValue

Sets the value of a global keyword.

Expects a pre-defined global keyword and a value

Returns undef in case of success or an string with a error message. It uses the
syntax-checker to verifiy if the global value meets the requirements of the
checkng regex.

  $errmsg = $myconfig->SetGlobalValue('some_keyword','some_value')
  
If the keyword is of type 'multi', the passed value will be added to a list of values. 
  
=head2 SetDirectiveValue

Sets the value of a keyword within a directive.

Expects a directive-name, directive identifier, keyword and a value.

Returns undef in case of success or an string with a error message. It uses the
syntax-checker to verifiy if the global value meets the requirements of the
checkng regex.

  $errmsg = $myconfig->SetGlobalValue('some_directive','some_identifier','some_keyword','some_value')

If the directive identifier doesn't exist, it will be created. If the keyword is of type 'multi', the
passed value will be added to a list of values.

=head2 DeleteDirectiveIdentifier

 Deletes an identifier from a directive.
 
 Expects a directive name and directive identifier
 
 Returns the removed values or undef is no values for this directive/identifiehave been deleted. 

=head2 WriteConfig

Writes the (modified) configuration file back to disk.

Expects a name-string, that is shown in the configuration file header comments and a filename where
the configuration should be saved to.

  $myconfig->WriteConfig('Foo Bars Configuration File','/tmp/foo.cfg'); 

=head2 error

Internal method, that is used to throw an error. The default behavior is to
croack().

=head1 EXAMPLE

=over

=item * Configuration file for a backup script: backup.cfg
 
 --- snip ---
 #
 # Config file
 #
 
 #
 # ---- Global Section ----
 #
 
 # Path to the rsync programm
 rsync           /usr/bin/rsync
 # Path to sendmail
 sendmail        /usr/sbin/sendmail
 # Path to the tar utility
 tar             /bin/tar
 # Path to ssh command
 # If not specified, rsh will be used 
 ssh             /usr/bin/ssh
 # Debuglevel, range (0..2)
 debuglevel      1
 
 #
 # ---- Backup Directives ----
 #
  
 <backup server-system>
        hostname        localhost
        backupschedule  Mon, Wed, Fri
        archiveschedule Sun
        archivemaxdays  60
        add  /
        excl /home, /proc, /sys, /dev, /mnt, /media
 </backup>
 
 <backup server-home>
        hostname        localhost
        backupschedule  Mon, Wed, Fri
        archiveschedule Sun
        archivemaxdays  30
        add  /home
 </backup>
 
 --- snap ---

=item * Setup procedure in perl context

 #!/usr/bin/perl
 
 use Config::MyConfig2;
 use strict;
 use Data::Dumper;
 
 my $myconfig = Config::MyConfig2->new(
 	conffile => "backup.cfg"
 );
 
 my $conftemplate;
 $conftemplate->{global}->{rsync} = { required => 'true', type => 'single', match => '.+' };
 $conftemplate->{global}->{sendmail} = { required => 'true', type => 'single', match => '.+' };
 $conftemplate->{global}->{tar} = { required => 'true', type => 'single', match => '.+' };
 $conftemplate->{global}->{ssh} = { required => 'true', type => 'single', match => '.+' };
 $conftemplate->{global}->{rsync} = { required => 'true', type => 'single', match => '.+' };
 $conftemplate->{global}->{debuglevel} = { required => 'true', type => 'single', match => '^\d$' };
 
 $conftemplate->{backup}->{hostname} = { required => 'true', type => 'single', match => '^[a-zA-Z0-9\.]+$' };
 $conftemplate->{backup}->{backupschedule} = { required => 'true', type => 'list', match => '^[Mon]|[Tue]|[Wed]|[Thu]|[Fri]|[Sat]|[Sun]$' };
 $conftemplate->{backup}->{archiveschedule} = { required => 'true', type => 'list', match => '^[Mon]|[Tue]|[Wed]|[Thu]|[Fri]|[Sat]|[Sun]$' };
 $conftemplate->{backup}->{archivemaxdays} = { required => 'true', type => 'list', match => '^\d+$' };
 $conftemplate->{backup}->{add} = { required => 'true', type => 'list', match => '.+' };
 $conftemplate->{backup}->{excl} = { required => 'false', type => 'list', match => '.+' };
 
 $myconfig->SetupDirectives($conftemplate);
 
 my $config = $myconfig->ReadConfig();
 
 print Dumper (\$config);

=item * Results in the following hash structure

 $VAR1 = \{
            'global' => {
                          'tar' => '/bin/tar',
                          'sendmail' => '/usr/sbin/sendmail',
                          'rsync' => '/usr/bin/rsync',
                          'ssh' => '/usr/bin/ssh',
                          'debuglevel' => '1'
                        },
            'backup' => {
                          'server-home' => {
                                             'archivemaxdays' => [
                                                                   '30'
                                                                 ],
                                             'add' => [
                                                        '/home'
                                                      ],
                                             'archiveschedule' => [
                                                                    'Sun'
                                                                  ],
                                             'hostname' => 'localhost',
                                             'backupschedule' => [
                                                                   'Mon',
                                                                   'Wed',
                                                                   'Fri'
                                                                 ]
                                           },
                          'server-system' => {
                                               'excl' => [
                                                           '/home',
                                                           '/proc',
                                                           '/sys',
                                                           '/dev',
                                                           '/mnt',
                                                           '/media'
                                                         ],
                                               'archivemaxdays' => [
                                                                     '60'
                                                                   ],
                                               'add' => [
                                                          '/'
                                                        ],
                                               'archiveschedule' => [
                                                                      'Sun'
                                                                    ],
                                               'hostname' => 'localhost',
                                               'backupschedule' => [
                                                                     'Mon',
                                                                     'Wed',
                                                                     'Fri'
                                                                   ]
                                             }
                        }
          };

=back

A more advanced example can be found in the included example program myconfig-demo.pl.

=head1 NOTES

Config::MyConfig2.pm supports my DebugHelper.pm class, which provides excellent
debugging and error handling methods.

 $mycfg = Config::MyConfig2->new(
 	conffile = "foo.cfg",
 	dh = $reference_to_debughelper_class
 	);
 	
If you don't like, that MyConfig croaks if an error (i.e. syntax error in a configuration file) occurs,
you may use MyConfig with eval:

  eval { $myconfig->ReadConfig() }
  if ($@) ... do something

=head1 AUTHOR

Markus Guertler, C<< <markus at guertler.org> >>

=head1 BUGS

Please report any bugs or feature requests to C<bug-myconfig2 at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config::MyConfig2>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.




=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Config::MyConfig2


You can also look for information at:

=over 4

=item * RT: CPAN's request tracker (report bugs here)

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Config::MyConfig2>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Config::MyConfig2>