Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CGI::Ex::Conf(3)      User Contributed Perl Documentation     CGI::Ex::Conf(3)

NAME
       CGI::Ex::Conf - Conf Reader/Writer for many different data format types

VERSION
       version 2.50

SYNOPSIS
	   use CGI::Ex::Conf qw(conf_read conf_write);

	   my $hash = conf_read("/tmp/foo.yaml");

	   conf_write("/tmp/foo.yaml", {key1 =>	$val1, key2 => $val2});

	   ### OOP interface

	   my $cob = CGI::Ex::Conf->new;

	   my $full_path_to_file = "/tmp/foo.val"; # supports ini, sto,	val, pl, xml
	   my $hash = $cob->read($file);

	   local $cob->{default_ext} = 'conf'; # default anyway

	   my @paths = qw(/tmp,	/home/pauls);
	   local $cob->{paths} = \@paths;
	   my $hash = $cob->read('My::NameSpace');
	   # will look in /tmp/My/NameSpace.conf and /home/pauls/My/NameSpace.conf

	   my $hash = $cob->read('My::NameSpace', {paths => ['/tmp']});
	   # will look in /tmp/My/NameSpace.conf

	   local $cob->{directive} = 'MERGE';
	   my $hash = $cob->read('FooSpace');
	   # OR	#
	   my $hash = $cob->read('FooSpace', {directive	=> 'MERGE'});
	   # will return merged	hashes from /tmp/FooSpace.conf and /home/pauls/FooSpace.conf
	   # immutable keys are	preserved from originating files

	   local $cob->{directive} = 'FIRST';
	   my $hash = $cob->read('FooSpace');
	   # will return values	from first found file in the path.

	   local $cob->{directive} = 'LAST'; # default behavior
	   my $hash = $cob->read('FooSpace');
	   # will return values	from last found	file in	the path.

	   ### manipulate $hash
	   $cob->write('FooSpace'); # will write it out	the changes

DESCRIPTION
       There are half a	million	Conf readers out there.	 Why not add one more.
       Actually, this module provides a	wrapper	around the many	file formats
       and the config modules that can handle them.  It	does not introduce any
       formats of its own.

       This module also	provides a preload ability which is useful in
       conjunction with	mod_perl.

       Oh - and	it writes too.

METHODS
       "read_ref"
	   Takes a file	and optional argument hashref.	Figures	out the	type
	   of handler to use to	read the file, reads it	and returns the	ref.
	   If you don't	need the extended merge	functionality, or key
	   fallback, or	immutable keys,	or path	lookup ability - then use this
	   method.  Otherwise -	use ->read.

       "read"
	   First argument may be either	a perl data structure, yaml string, a
	   full	filename, or a file "namespace".

	   The second argument can be a	hashref	of override values (referred
	   to as $args below)..

	   If the first	argument is a perl data	structure, it will be copied
	   one level deep and returned (nested structures will contain the
	   same	references).  A	yaml string will be parsed and returned.  A
	   full	filename will be read using the	appropriate handler and
	   returned (a file beginning with a / or ./ or	../ is considered to
	   be a	full filename).	 A file	"namespace" (ie	"footer" or
	   "my::config"	or "what/ever")	will be	turned into a filename by
	   looking for that namespace in the paths found either	in
	   $args->{paths} or in	$self->{paths} or in @DEFAULT_PATHS.
	   @DEFAULT_PATHS is empty by default as is $self->{paths} - read
	   makes no attempt to guess what directories to look in.  If the
	   namespace has no extension the extension listed in
	   $args->{default_ext}	or $self->{default_ext}	or $DEFAULT_EXT	will
	   be used).

	     my	$ref = $cob->read('My::NameSpace', {
	       paths =>	[qw(/tmp /usr/data)],
	       default_ext => 'pl',
	     });
	     # would look first	for /tmp/My/NameSpace.pl
	     # and then	/usr/data/My/NameSpace.pl

	     my	$ref = $cob->read('foo.sto', {
	       paths =>	[qw(/tmp /usr/data)],
	       default_ext => 'pl',
	     });
	     # would look first	for /tmp/foo.sto
	     # and then	/usr/data/foo.sto

	   When	a namespace is used and	there are multiple possible paths,
	   there area a	few options to control which file to look for.	A
	   directive of	'FIRST', 'MERGE', or 'LAST' may	be specified in
	   $args->{directive} or $self->{directive} or the default value in
	   $DIRECTIVE will be used (default is 'LAST').	When 'FIRST' is
	   specified the first path that contains the namespace	is returned.
	   If 'LAST' is	used, the last found path that contains	the namespace
	   is returned.	 If 'MERGE' is used, the data structures are joined
	   together.  If they are arrayrefs, they are joined into one large
	   arrayref.  If they are hashes, they are layered on top of each
	   other with keys found in later paths	overwriting those found	in
	   earlier paths.  This	allows for setting system defaults in a	root
	   file, and then allow	users to have custom overrides.

	   It is possible to make keys in a root file be immutable (non
	   overwritable) by adding a suffix of _immutable or _immu to the key
	   (ie {foo_immutable => 'bar'}).  If a	value is found in the file
	   that	matches	$IMMUTABLE_KEY,	the entire file	is considered
	   immutable.  The immutable defaults may be overriden using
	   $IMMUTABLE_QR and $IMMUTABLE_KEY.

	   Errors during read die.  If the file	does not exist undef is
	   returned.

       "write_ref"
	   Takes a file	and the	reference to be	written.  Figures out the type
	   of handler to use to	write the file and writes it. If you used the
	   ->read_ref use this method.	Otherwise, use ->write.

       "write"
	   Allows for writing back out the information read in by ->read.  If
	   multiple paths where	used - the directive 'FIRST' will write	the
	   changes to the first	file in	the path - otherwise the last path
	   will	be used.  If ->read had	found immutable	keys, then those keys
	   are removed before writing.

	   Errors during write die.

       "preload_files"
	   Arguments are file(s) and/or	directory(s) to	preload.
	   preload_files will loop through the arguments, find the files that
	   exist, read them in using the handler which matches the files
	   extension, and cache	them by	filename in %CACHE.  Directories are
	   spidered for	file extensions	which match those listed in
	   %EXT_READERS.  This is useful for a server environment where	CPU
	   may be more precious	than memory.

       "in_cache"
	   Allow for testing if	a particular filename is registered in the
	   %CACHE - typically from a preload_files call.  This is useful when
	   building wrappers around the	conf_read and conf_write method	calls.

FUNCTIONS
       conf_read
	   Takes a filename.  Returns the read contents	of that	filename.  The
	   handler to use is based upon	the extention on the file.

	       my $hash	= conf_read('/tmp/foo.yaml');

	       my $hash	= conf_read('/tmp/foo',	{file_type => 'yaml'});

	   Takes a filename and	a data structure.  Writes the data to the
	   filename.  The handler to use is based upon the extention on	the
	   file.

	       conf_write('/tmp/foo.yaml', \%hash);

	       conf_write('/tmp/foo', \%hash, {file_type => 'yaml'});

FILETYPES
       CGI::Ex::Conf supports the files	found in %EXT_READERS by default.
       Additional types	may be added to	%EXT_READERS, or a custom handler may
       be passed via $args->{handler} or $self->{handler}.  If the custom
       handler is a code ref, all files	will be	passed to it.  If it is	a
       hashref,	it should contain keys which are extensions it supports, and
       values which read those extensions.

       Some file types have benefits over others.  Storable is very fast, but
       is binary and not human readable.  YAML is readable but very slow.  I
       would suggest using a readable format such as YAML and then using
       preload_files to	load in	what you need at run time.  All	preloaded
       files are faster	than any of the	other types.

       The following is	the list of handlers that ships	with CGI::Ex::Conf
       (they will only work if the supporting module is	installed on your
       system):

       "pl"
	   Should be a file containing a perl structure	which is the last
	   thing returned.

       "sto" and "storable"
	   Should be a file containing a structure stored in Storable format.
	   See Storable.

       "yaml" and "conf" and "val"
	   Should be a file containing a yaml document.	 Multiple documents
	   are returned	as a single arrayref.  Also - any file without an
	   extension and custom	handler	will be	read using YAML.  See YAML.

       "ini"
	   Should be a windows style ini file.	See Config::IniHash

       "xml"
	   Should be an	xml file.  It will be read in by XMLin.	 See
	   XML::Simple.

       "json"
	   Should be a json file.  It will be read using the JSON library.
	   See JSON.

       "html" and "htm"
	   This	is actually a custom type intended for use with
	   CGI::Ex::Validate.  The configuration to be read is actually
	   validation that is stored inline with the html.  The	handler	will
	   look	for any	form elements or input elements	with an	attribute with
	   the same name as in $HTML_KEY.  It will also	look for a javascript
	   variable by the same	name as	in $HTML_KEY.  All configuration items
	   done	this way should	be written in YAML.  For example, if $HTML_KEY
	   contained 'validation' it would find	validation in:

	     <input type=text name=username validation="{required: 1}">
	     # automatically indented and "username:\n"	prepended
	     # AND #
	     <form name=foo validation="
	     general no_confirm: 1
	     ">
	     # AND #
	     <script>
	     document.validation = "\n\
	     username: {required: 1}\n\
	     ";
	     </script>
	     # AND #
	     <script>
	     var validation = "\n\
	     username: {required: 1}\n\
	     ";
	     </script>

	   If the key $HTML_KEY	is not set, the	handler	will always return
	   undef without even opening the file.

TODO
       Make a similar write method that	handles	immutability.

LICENSE
       This module may be distributed under the	same terms as Perl itself.

AUTHOR
       Paul Seamons <perl at seamons dot com>

perl v5.32.0			  2020-07-08		      CGI::Ex::Conf(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | FUNCTIONS | FILETYPES | TODO | LICENSE | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CGI::Ex::Conf&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help