view release on metacpan or  search on metacpan

docs/Overview.tex  view on Meta::CPAN

@chapter A broad overview of CfgTie

CfgTie is a set of PERL modules, each working with the configuration tables of
some subsystem.    For our purposes, configuration will basically be defined
loosely as:
@itemize @bullet
@item Settings in various files, or databases
@item Probably establish some bounds for your system
@item Describe an arrangement of modules and subsystems
@item May describe how things currently are.
@end itemize
 
@c API Standards
@c Attributes
@c Implementation

@heading Standards in the API
@c Traps
@c Common Object methods
@c

Most of the configuration elements have been developed to work as both Perl
ties (almost always hashes or associative arrays), and as Perl objects.  In
the more complex cases, the associative arrays often refer to other associatve
arrays.  Otherwise the stored values are list references.

To make these work as a normal variable you need only:

@itemize @bullet
@item reference the desired module:
@code{require cfgthingy;}
@code{my %Table;}

@item Then, tie it a variable that you want to use:
@code{tie %Table, 'cfgthingy', param1, param2, ...}

@end itemize

@subheading Traps
Traps on changes in the variables are not currently implemented in this
module.   The Perl module @code{Tie::Watch} seems to provide the proper
functionality for this.

@subheading Common object methods
There as some standard methods typically (but not always) available to
associative arrays:

@code{HTML();} or @code{$Table->HTML('MyHTMLClass');}  This return a
string formatted in HTML.  If an HTML class is specified, it will be embedded
in the HTML.  This is useful for style sheets.

@code{stat();} This works like a normal @code{stat}, returning information
about the last time the table (e.g. file) was accessed, modified, etc.

@heading Attributes
The flags used in all of the variable control procedures are composed of
three sections, based upon what they control

@table @asis
@item Scope
This controls the scope of the variable setting.  The scope, from the
narrowest to the widest scope: @emph{Session}, @emph{Application},
@emph{User}, @emph{Group}, @emph{Global}.  That is, a variable set in the
@emph{user} scope, say, will only affect applications run by that user.
Currently all of the configuration modules are effectively global.

@item Inheritance
This controls whether or not a child process would inherit the variable.

@item Precedence
This controls whether an operation should affect an already existing variable.
@end table

@subheading Scope attributes
The current scopes are mutually exclusive, and defined as follows, from the
narrowest to the widest scope:

@table @dfn
@item session
This sets the variable for this session only.

@item application
This sets the variable for executions of this application only.

@item user
This sets the variable for use by this user (and any applications that may
run by said user) only.  If a user is not specified or otherwise implied, the
effective user id is used to determine the user name.

@item group
This sets the variable for use by this group (and any applications that may
run by an users in said group) only.  The effective group id is used to
determine the user name.

@item global
This sets the variable for use in general by any user or any applications.

@end table

@heading Implementation

@subheading CfgTie uses external utilities
Wherever possible, CfgTie employs utility programs to interact with the
low-level configuration data.  This was choosen for several reasons:

@itemize @bullet
@item The issues of locking, timing, state, security and communication with the
services can be very specific.  It is better to use a utility that correctly
addresses this, than reinvent an incorrect one.

@item Many of the utilities can be used with @code{chroot} and other powerful
tools limit their scope for security reasons.