ZConf - A configuration system allowing for either file or LDAP backed storage.
Version 6.1.0
use ZConf; #creates a new instance my $zconf = ZConf->new; my @configs
my $zconf=ZConf->(\%args);
This initiates the ZConf object. If it can't be initiated, $zconf->error will be set. This error should be assumed to be permanent.
When it is run for the first time, it creates a filesystem only config file.
The default is xdf_config_home."/zconf.zml", which is generally '~/.config/zconf.zml'.
This is incompatible with the sys option.
my $zconf=ZConf->new(); if($zconf->error){ warn('error: '.$zconf->{error}."\n".$zconf->errorString); }
This chooses what set should be used using the associated chooser string for the config in question.
This method does fail safely. If a improper configuration is returned by chooser string, it uses the value the default set.
It takes one arguement, which is the configuration it is for.
If the chooser errors, is blank, or is just a newline, the default is returned.
my $set=$zconf->chooseSet("foo/bar"); if($zconf->error){ warn('error: '.$zconf->{error}."\n".$zconf->errorString); }
This method is used for checking if a config exists or not.
It takes one option, which is the configuration to check for.
The returned value is a perl boolean value.
$zconf->configExists("foo/bar") if($zconf->error){ print 'error: '.$zconf->error."\n".$zconf->errorString."\n"; }
This checks if the name of a config is legit or not. See the section CONFIG NAME for more info on config naming.
my ($error, $errorString) = $zconf->configNameCheck($config); if($error){ warn("ZConf configExists:".$error.": ".$errorString); $self->{error}=$error; $self->{errorString}=$errorString; $self->warn; return undef; };
This method is used for creating a new config.
One arguement is needed and that is the config name.
The returned value is a perl boolean.
$zconf->createConfig("foo/bar") if($zconf->error){ print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n"; };
This checks to if the default set for a config exists. It takes one arguement, which is the name of the config. The returned value is a Perl boolean.
my $returned=$zconf->defaultSetExists('someConfig'); if($zconf->error){ warn('error: '.$zconf->{error}."\n".$zconf->errorString); } if($returned){ print "It exists.\n"; }
This removes a config. Any sub configs will need to removes first. If any are present, this method will error.
#removes 'foo/bar' $zconf->delConfig('foo/bar'); if(defined($zconf->error)){ warn('error: '.$zconf->{error}."\n".$zconf->errorString); }
This deletes a specified set.
Two arguements are required. The first one is the name of the config and the and the second is the name of the set.
$zconf->delSetFile("foo/bar", "someset"); if($zconf->error){ warn('error: '.$zconf->{error}."\n".$zconf->errorString); }
This dumps a loaded config to a ZML object.
One arguement is required and it is the name of the loaded config.
my $zml=$foo->dumpToZML($config); if($zconf->error){ warn('error: '.$zconf->{error}."\n".$zconf->errorString); }
This gets if a config should be automatically updated or not.
One arguement is required and it is the config. If this is undefined or a matching one is not found, the global is used.
The return value is a boolean.
#fetches the global my $autoupdate=$zconf->getAutoupdate(); #fetches it for 'some/config' my $autoupdate=$zconf->getAutoupdate('some/config');
This gets the available sets for a config.
The only arguement is the name of the configuration in question.
my @sets = $zconf->getAvailableSets("foo/bar"); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This gets the default set currently being used if one is not choosen.
my $defaultSet = $zml->getDefault();
This gets a list of variables that have comments.
my @keys = $zconf->getComments("foo/bar") if($zconf->error){ print 'error: '.$zconf->error."\n".$zconf->errorString."\n"; }
This fetches the revision for the speified config.
my $revision=$zconf->getConfigRevision('some/config'); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This fetches the mtime for a variable.
Two arguements are required. The first is the config and the second is the variable.
The returned value is UNIX time value for when it was last changed. If it is undef, it means the variable has not been changed since ZConf 2.0.0 came out.
my $time=$zconf->getMtime('some/config', 'some/var'); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); } if(defined($time)){ print "variable modified at".$time." seconds past 1970-01-01.\n"; }else{ print "variable not modifined since ZConf 2.0.0 came out.\n"; }
This gets gets the keys for a loaded config.
my @keys = $zconf->getKeys("foo/bar") if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This gets the revision of the specified config, if it is loaded.
my $rev=$zconf->getLoadedConfigRevision; if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
my @configs = $zconf->getLoadedConfigs("foo/bar") if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This gets a list of variables that have meta variables.
my @keys = $zconf->getComments("foo/bar") if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This will get the current override chooser for a config.
If no chooser is specified for the loaded config
One arguement is required it is the name of the config.
This method is basically a wrapper around regexMetaGet.
my $orchooser=$zconf->getOverrideChooser($config); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This gets the set for a loaded config.
my $set = $zconf->getSet("foo/bar") if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This gets any sub configs for a config. "" can be used to get a list of configs under the root.
One arguement is accepted and that is the config to look under.
#lets assume 'foo/bar' exists, this would return my @subConfigs=$zconf->getSubConfigs("foo"); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This requires three arguments.
The first is the name of the config.
The second is the variable.
The third is the comment name.
If the comment does not exist, undef is returned. It is also possible it errored, but a non-existant variable is not considered a error.
my $value=$zconf->getVar($someConfig, $someVariable, $someComment); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); } if(!defined($value)){ print "'.$someVariable.' and/or '".$someComment."' does not exist\n"; }
The third is the meta name.
my $value=$zconf->getVar($someConfig, $someVariable, $someMeta); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); } if(!defined($value)){ print "'.$someVariable.' and/or '".$someMeta."' does not exist\n"; }
This reqyures two arguments.
If the variable does not exist, undef is returned. It is also possible it errored, but a non-existant variable is not considered a error.
my $value=$zconf->getVar($someConfig, $someVariable); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); } if(!defined($value)){ print "'.$someVariable.' does not exist\n"; }
This initializes a backend.
One arguement is required and it is the backend name.
my $backend=$zconf->initBackend('file'); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }else{ if($backend->error){ warn('backend error: '.$backend->error.":".$backend->errorString); } }
This returns if the loaded config is locked or not.
Only one arguement is taken and that is the name of the config.
my $returned=$zconf->isLoadedConfigLocked('some/config'); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This checks if a config or not.
One argument is taken and that is if a config is loaded or not.
$zconf->isConfigLoaded($config); if( $zconf->error ){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This checks if a config is locked or not.
One arguement is required and it is the name of the config.
The returned value is a boolean value.
my $locked=$zconf->isConfigLocked('some/config'); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); } if($locked){ print "The config is locked\n"; }
This generates a Net::LDAP object based on the LDAP backend.
my $ldap=$zconf->LDAPconnect(); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This runs the overrides for a config.
This overrides various variables in the config by running the chooser stored in '#!zconf=override/chooser'. If it fails, the profile 'default' is used.
Once a profile name has been picked, everything under '#!zconf=override/profiles/<profile>/' has /^override\/profiles\/<profile>\// removed and it is set as a regular variable.
One arguement is taken and it is a hash.
If a value of undef is returned, but no error is set, no '#!zconf=override/chooser' is not defined.
This method does not invoke the method updateIfNeeded.
This is the config to operate on.
If this is not specified, the chooser stored in the meta is '#!zconf=override/chooser'.
This reads a config. The only accepted option is the config name.
It takes one arguement, which is a hash.
The config to load.
This specifies if override should be ran not.
If this is not specified, it defaults to 1, true.
The set for that config to load.
$zconf->read({config=>"foo/bar"}) if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This reads the chooser for a config. If no chooser is defined "" is returned.
The name of the config is the only required arguement.
my $chooser = $zconf->readChooser("foo/bar") if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This searches through the comments for variables in a loaded config for any that match the supplied regex and removes them.
A hash of hash containing copies of the deleted variables are returned.
This is the config search.
The variable to search for matching comment names.
The regex use for matching comment names.
my %deleted=$zconf->regexCommentDel({ config=>"foo/bar", varRegex=>"^some/var$", commentRegex=>"^monkey\/"; }); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This searches through the comments for variables in a loaded config for any that match the supplied regex and returns them.
my %deleted=$zconf->regexCommentGet({ config=>"foo/bar", varRegex=>"^some/var$", commentRegex=>"^monkey\/"; }); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This searches through the meta variables in a loaded config for any that match the supplied regex and removes them.
The regex use for matching meta variables.
my %deleted=$zconf->regexMetaDel({ config=>"foo/bar", varRegex=>"^some/var$", metaRegex=>"^monkey\/"; }); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
my %deleted=$zconf->regexMetaGet({ config=>"foo/bar", varRegex=>"^some/var$", metaRegex=>"^monkey\/"; }); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This searches through the variables in a loaded config for any that match the supplied regex and removes them.
Two arguements are required. The first is the config to search. The second is the regular expression to use.
#removes any variable starting with the monkey my @deleted = $zconf->regexVarDel("foo/bar", "^monkey"); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This searches through the variables in a loaded config for any that match the supplied regex and returns them in a hash.
#returns any variable begining with monkey my %vars = $zconf->regexVarGet("foo/bar", "^monkey"); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This searches through the variables in a loaded config for any that match the supplied regex and returns a array of matches.
#removes any variable starting with the monkey my @matched = $zconf->regexVarSearch("foo/bar", "^monkey") if($zconf->error)){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This rereads the specified config file. This requires it to be already loaded.
$zconf->reread('some/config'); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This sets if a value for autoupdate.
It takes two optional arguements. The first is a name for a config and second is a boolean value.
If a config name is not specified, it sets the global value for it.
#set the global auto update value to false $zconf->setAutoupdate(undef, '0'); #sets it to true for 'some/config' $zconf->setAutoupdate('some/config', '1');
This sets a comment variable in a loaded config.
Four arguements are required. The first is the name of the config. The second is the name of the variable. The third is the comment variable. The fourth is the value.
$zconf->setComment("foo/bar" , "somethingVar", "someComment", "eat more weazel\n\nor something" if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This sets the default set to use if one is not specified or choosen.
my $returned = $zconf->setDefault("something") if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This checks if the specified set exists.
Two arguements are required. The first arguement is the name of the config. The second arguement is the name of the set. If no set is specified, the default set is used. This is done by calling 'defaultSetExists'.
my $return=$zconf->setExists("foo/bar", "fubar"); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }else{ if($return){ print "It exists.\n"; } }
This unlocks or logs a config.
Two arguements are taken. The first is a the config name, required, and the second is if it should be locked or unlocked
#lock 'some/config' $zconf->setLockConfig('some/config', 1); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); } #unlock 'some/config' $zconf->setLockConfig('some/config', 0); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); } #unlock 'some/config' $zconf->setLockConfig('some/config'); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This sets a meta variable in a loaded config.
Four arguements are required. The first is the name of the config. The second is the name of the variable. The third is the meta variable. The fourth is the value.
$zconf->setMeta("foo/bar" , "somethingVar", "someComment", "eat more weazel\n\nor something" if($zconf->{error}){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This checks if a setname is legit.
There is one required arguement, which is the set name.
my $set="something"; if(!$zconf->setNameLegit($set)){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This will set the override chooser for a config.
Two arguements are required. The first is the config and th e second is the chooser string.
This method is basically a wrapper around setMeta.
$zconf->setOverrideChooser($config, $chooser); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This sets a variable in a loaded config.
Three arguements are required. The first is the name of the config. The second is the name of the variable. The third is the value.
$zconf->setVar("foo/bar" , "something", "eat more weazel\n\nor something" if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
Unloads a specified configuration. The only required value is the set name. The return value is a Perl boolean value.
zconf->unloadConfig($config); if( $zconf->error ) warn('error: '.$zconf->error.":".$zconf->errorString); }
This checks if the loaded config on disk has a different revision ID than the saved one.
The return value is a boolean value. A value of true indicates the config has been changed on the backend.
my $updatable=$zconf->updatable('some/config'); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
If a loaded config is updatable, reread it.
The returned value is a boolean value indicating if it was updated or not. A value of true indicates it was.
This tells it to check getAutoupdate. If it returns false, it will return.
If $zconf->{error} is set, clear it. This is primarily meant for being used internally.
This config to check.
This is required.
my $updated=$zconf->updateIfNeeded({config=>'some/config'}); if($zconf->{error}){ warn('error: '.$zconf->error.":".$zconf->errorString); } if($updated){ print "Updated!\n"; }
This checks if a there if the specified variable name is a legit one or not.
my ($error, $errorString) = $zconf->varNameCheck($config); if(defined($error)){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This writes a string into the chooser for a config.
There are two required arguements. The first is the config name. The second is chooser string.
No error checking is done currently on the chooser string.
Setting this to '' or "\n" will disable the chooser fuction and the default will be used when chooseSet is called.
my $returned = $zconf->writeChooser("foo/bar", $chooserString) if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This takes a hash and writes it to a config. It takes two arguements, both of which are hashes.
The first hash contains
The second hash is the hash to be written to the config.
The config to write it to.
This is the set name to use.
If not defined, the one will be choosen.
This is the revision string to use.
This is primarily meant for internal usage and is suggested that you don't touch this unless you really know what you are doing.
$zconf->writeSetFromHash({config=>"foo/bar"}, \%hash); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This method writes a loaded config to a to a set.
One arguement is required.
$zconf->writeSetFromLoadedConfig({config=>"foo/bar"}); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
This is the ZML object to use.
$zconf->writeSetFromZML({config=>"foo/bar", zml=>$zml}); if($zconf->error){ warn('error: '.$zconf->error.":".$zconf->errorString); }
Any configuration name is legit as long as it does not match any of the following.
undef /./ /\/\./ /\.\.\// /\/\// /\.\.\// /\/\.\./ /^\.\// /\/$/ /^\// /\n/
Any set name is legit as long as it does not match any of the following.
undef /\// /^\./ /^ / / $/ /\.\./
Any variable name is legit as long it does not match any of the following. This also covers comments and meta variables.
/,/ /\/\./ /\/\// \.\.\// /\/\.\./ /^\.\// /\/$/ /^\// /\n/ /=/
This module uses Error::Helper for error handling. Below are the error codes returned by the error method.
config name contains ,
config name contains /.
config name contains //
config name contains ../
config name contains /..
config name contains ^./
config name ends in /
config name starts with /
could not sync to file
config name contains a \n
Backend errored.
config does not exist
Backend is not ZConf::backends::ldap.
The backend could not be found.
No backend specified.
ZML object not passed.
No variable name specified.
config key starts with a ' '
set not found for config
skilling variable as it is not a legit name
set is not defined
Config is undefined.
Config not loaded.
Set name is not a legit name.
ZML->parse error.
Could not unlink the unlink the set.
The sets exist for the specified config.
Did not find a matching set.
Unable to choose a set.
Unable to remove the config as it has sub configs.
Sys name matched /\//.
Sys name matched /\./.
No chooser string specified.
No comment specified.
No meta specified.
Config is locked.
LDAP entry update failed.
Failed to initialize the backend. It returned undef.
This can be done by checking $zconf->{error} to see if it is defined. If it is defined, The number it contains is the corresponding error code. A description of the error can also be found in $zconf->{errorString}, which is set to "" when there is no error.
The default is 'xdf_config_home/zconf.zml', which is generally '~/.config/zconf.zml'. See perldoc ZML for more information on the file format. The keys are listed below.
For information on the keys for the backends, please see perldoc for the backend in question.
The two included are 'file' and 'ldap'. See perldoc for 'ZConf::backends::file' and 'ZConf::backends::ldap' for their key values.
This is the backend to use for storage. Current values of 'file' and 'ldap' are supported.
This is a Chooser string that chooses what backend should be used.
This is a chooser string that chooses what the name of the default to use should be.
This is a boolean value. If it is set to 1, only the file backend is used.
This will override 'backend'.
If this is set, if any of the methods below error when trying the any backend other than 'file' , it will fall through to the file backend.
configExists getAvailableSets getSubConfigs read readChooser
There are several scripts installed with this module. Please see the perldocs for the utilities listed below.
zcchooser-edit zcchooser-get zcchooser-run zcchooser-set zccreate zcget zcls zcrm zcset zcvdel zcvls
Coming shortly.
This will be documented more shortly.
Zane C. Bowers-Hadley, <vvelox at vvelox.net>
<vvelox at vvelox.net>
Please report any bugs or feature requests to bug-zconf at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ZConf. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-zconf at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc ZConf
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=ZConf
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/ZConf
CPAN Ratings
http://cpanratings.perl.org/d/ZConf
Search CPAN
http://search.cpan.org/dist/ZConf
Subversion Repository
http://eesdp.org/svnweb/index.cgi/pubsvn/browse/Perl/ZConf
Copyright 2011 Zane C. Bowers-Hadley, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install ZConf, copy and paste the appropriate command in to your terminal.
cpanm
cpanm ZConf
CPAN shell
perl -MCPAN -e shell install ZConf
For more information on module installation, please visit the detailed CPAN module installation guide.