oracular (3) Unix::ConfigFile.3pm.gz

NAME

       Unix::ConfigFile - Perl interface to various Unix configuration files

SYNOPSIS

         use Unix::ConfigFile;

DESCRIPTION

       The Unix::ConfigFile module provides a base class from which the other Unix::*File modules are derived.
       It provides some basic facilities like file opening, locking, and closing.  You do not need to use this
       module directly unless you are developing a derived module for an unsupported configuration file.
       However, some of the methods documented here are intended for public use by users of Unix::ConfigFile
       submodules, so you may find this documentation useful even if you are not developing your own module.

       The ConfigFile object also provides a sequencing API for modules that wish to preserve the order of the
       configuration file they read and write.  The sequencer maintains a list of arbitrary data that a
       submodule may append, insert, and delete from.  Use of the sequencer is completely optional.

       A module that subclasses from Unix::ConfigFile must, at a minimum, provide two methods, called "read" and
       "write".  Both methods will receive a filehandle as a parameter (besides the regular object parameter).
       The read method is called after the file is opened.  It is expected to read in the configuration file and
       initialize the subclass-specific data structures associated with the object.  The write method is called
       when an object is committed and is expected to write out the new configuration to the supplied
       filehandle.

USER METHODS

   commit( [%OPTIONS] )
       This writes any changes you have made to the object back to disk.  If you do not call commit, none of
       your changes will be reflected in the file you are modifying.  Commit may not be called on files opened
       in read-only mode.  There are some optional parameters that may be provided; these are passed in the form
       of key => value pairs.  The "backup" option allows you to specify a file extension that will be used to
       save a backup of the original file.  The "writeopts" option passes module-specific options through to the
       write method.  It will accept any scalar for its value; typically this will be a list or hash reference.
       Commit returns 1 on success and 0 on failure.

   encpass( PASSWORD )
       This method encrypts the supplied plaintext password using a random salt and returns the encrypted
       password.  Note that this method does not actually make any use of the object that it is invoked on, and
       could be called as a class method.

   new( FILENAME [,%OPTIONS] )
       The new method constructs a new ConfigFile (or subclass) object using the specified FILENAME.  There are
       several optional parameters that may be specified.  Options must be passed as keyed pairs in the form of
       option => value.  Valid options are "locking", "lockfile", "mode", and "readopts".  The locking option
       determines what style of file locking is used; available styles are "dotlock", "flock", and "none".  The
       default locking style is "dotlock".  The "none" locking style causes no locking to be done, and all lock
       and unlock requests will return success.  The lockfile option can be used to specify the lock filename
       used with dotlocking.  The default is "FILENAME.lock", where FILENAME is the name of the file being
       opened.  The mode option allows the file open mode to be specified.  The default mode is "r+"
       (read/write), but "r" and "w" are accepted as well.  Finally, the readopts option allows module-specific
       options to be passed through to the read method.  It will accept any scalar for its value; typically this
       will be a list or hash reference.

DEVELOPER METHODS

   joinwrap( LENGTH, HEAD, INDENT, DELIM, TAIL, @LIST )
       This is a utility function that may be called as an object or class method.  As the name suggests, this
       method is basically a version of the join function that incorporates line wrapping.  The specified list
       will be joined together, with each list element separated by the specified delimiter.  The first line of
       output will be prefixed with the HEAD parameter.  If a line exceeds the length parameter, output is
       wrapped to the next line and the INDENT parameter is used to prefix the line.  In addition, the TAIL
       parameter will be added to the end of every line generated except the final one.  There is one case where
       the resulting string can exceed the specified line length - if a single list element, plus HEAD or
       INDENT, exceeds that length.  One final feature is that if the HEAD or INDENT parameters contain the text
       '%n', it will be replaced with the current line number, beginning at 0.

   sequence( )
       Returns the current sequence list associated with the object.  This is a list of arbitrary data
       maintained by a ConfigFile submodule.  The ConfigFile module does not care what is contained in the list.

   seq_append( @DATA )
       Appends that specified data to the end of the sequence list.

   seq_insert( KEY, @DATA )
       Inserts the data into the sequence list before the data that matches the specified key.

   seq_remove( KEY )
       Removes the data from the sequence list that matches the specified key.

AUTHOR

       Steve Snodgrass, ssnodgra@fore.com

SEE ALSO

       Unix::AliasFile, Unix::AutomountFile, Unix::GroupFile, Unix::PasswdFile