File Coverage

blib/lib/Unix/Conf.pm

Criterion	Covered	Total	%
statement	15	26	57.6
branch			n/a
condition			n/a
subroutine	5	9	55.5
pod	1	1	100.0
total	21	36	58.3

# Provides utility modules for use by file configuration manipulation classes
#
# Copyright Karthik Krishnamurthy

=head1 NAME

Unix::Conf - Front end for class methods in various utility modules
under the Unix::Conf namespace.

=head1 DESCRIPTION

Methods in Unix::Conf are intended as a gateway into the various
utility modules like Unix::Conf::ConfIO, Unix::Conf::Err. Unix::Conf
is the preferred way to access class constructors in the above mentioned
modules. Methods starting with a '_' are intended for use from other
modules under the Unix::Conf namespace. Those without the '_' prefix
are for general users of the Unix::Conf suite of modules.

=head1 METHODS

=cut

package Unix::Conf;

use 5.6.0;
use strict;
use warnings;
use Unix::Conf::Err;
use Unix::Conf::ConfIO;

$Unix::Conf::VERSION = "0.2";

=over 4

=item debuglevel ()

 Arguments
 DEBUGLEVEL,
Set the class debuglevel variable in Unix::Conf::Err. This enables
debugging messages to be printed for all class objects. The actual
level at which debug messages are printed is the maximum of class
debuglevel variable and the object specific debuglevel variable.
Refer to Unix::Conf::Err for the behaviour of the three debuglevels.

   Example
   Unix::Conf->debuglevel (2);

=cut

sub debuglevel
{
	shift ();
	return (Unix::Conf::Err->debuglevel (@_));
}

=item _open_conf ()

 Arguments
 NAME        => 'PATHNAME',
 MODE        => FILE_OPEN_MODE,     # default is O_RDWR | O_CREAT
 PERMS       => FILE_CREATION_PERMS,# default is 0600
 LOCK_STYLE  => 'flock'/'dotlock',  # default is 'flock'
 SECURE_OPEN => 0/1,                # default is 0 (disabled)
 PERSIST=> 0/1,                     # default is 0 (disabled)
Open a configuration file and return a Unix::Conf::ConfIO object.
A LOCK_STYLE of 'dotlock' is used to access /etc/passwd,
/etc/shadow, /etc/group, /etc/gshadow. Refer to Unix::Conf::ConfIO
for the various methods that this object offers. Returns a new
ConfIO object in case of success, or an Err object in case of
failure. Refer to documentation for

   Example
   my $conf = Unix::Conf->_open_conf (
      NAME        => '/etc/passwd',
      SECURE_OPEN => 1,
      LOCK_STYLE  => 'dotlock',
   );

=cut

# For use by other modules only. use goto &funcname to warp to that function
# replacing the frame for these functions. The actual functions/methods meddle
# with the stack and hence are sensitive to the calling sequence. We could
# alter those methods to omit one frame, i.e. that of Unix::Conf->_*. However
# this way, even if users call Unix::Conf::Err, or Unix::Conf::ConfIO directly,
# it will still work
sub _open_conf
{
	shift ();
	unshift (@_, 'Unix::Conf::ConfIO');
	goto &Unix::Conf::ConfIO::open;
}

=item _release_all ()

Release all objects which have been opened persistently by the
calling class.

   Example
   my $conf = Unix::Conf->_open_conf (
      NAME       => 'some_conf',
      PERSISTENT => 1,
      LOCK       => 'flock',
   );
   # Now this object will be held in the Unix:Conf::ConfIO
   # object cache even though $conf passes out of scope.
   # This is for ancillary files which need to be held open
   # so that they remain locked. It eases the user from
   # having to prevent the user of these objects from going
   # out of scope. Call this from the destructor to release
   # all such objects.

   sub DESTROY
   {
      # do stuff
      Unix::Conf->_release_all ();
   }

   # Now all persistently held Unix::Conf::ConfIO objects
   # will be released this triggering their destructors
   # which will effectively sync the files and release
   # the locks.

=cut

sub _release_all
{
	shift ();
	unshift (@_, 'Unix::Conf::ConfIO');
	goto &Unix::Conf::ConfIO::release_all;
}

=item _err ()

 Arguments
 PREFIX,
 ERRMSG,
Create a new Unix::Conf::Err object. This object remembers the stack
at the creation. The returned object can thrown or returned to
indicate an error condition as it evaluates to false in a boolean
context. Refer to Unix::Conf::Err for the various methods that this
object offers. If error message is missing, a stringified version of
$! is stored as the error message.

   Example
   return (Unix::Conf::->_err ('chdir')) unless (chdir ('/etc'));

   return (
      Unix::Conf::->_err (
         'object_method', 'argument not an object of class BLAH'
      )
   ) unless (ref ($obj) eq 'BLAH');

=cut

sub _err
{
	shift ();
	unshift (@_, 'Unix::Conf::Err');
	goto &Unix::Conf::Err::new;
}

1;
__END__