NAME
ZConf::backends::file - A configuration system allowing for either file or LDAP backed storage.
VERSION
Version 2.1.0
SYNOPSIS
use ZConf;
#creates a new instance
my $zconf = ZConf->new();
...METHODS
new
my $zconf=ZConf->(\%args);This initiates the ZConf object. If it can't be initiated, a value of undef is returned. The hash can contain various initization options.
When it is run for the first time, it creates a filesystem only config file.
args hash
self
This is the copy of the ZConf object intiating it.
zconf
This is the variables found in the ~/.config/zconf.zml.
my $zconfbe=ZConf::backends::file->new(\%args);
if($zconfbe->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}configExists
This method methods exactly the same as configExists, but for the file backend.
No config name checking is done to verify if it is a legit name or not as that is done in configExists. The same is true for calling errorblank.
$zconfbe->configExistsFile("foo/bar");
if($zconf->error){
warn('error: '.$zconf->{error}.":".$zconf->errorString);
}createConfig
This methods just like createConfig, but is for the file backend. This is not really meant for external use. The config name passed is not checked to see if it is legit or not.
$zconf->createConfigFile("foo/bar");
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}delConfig
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);
}delSet
This deletes a specified set, for the filesystem backend.
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.":".$zconf->errorString);
}getAvailableSets
This is exactly the same as getAvailableSets, but for the file back end. For the most part it is not intended to be called directly.
my @sets = $zconf->getAvailableSets("foo/bar");
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}getConfigRevision
This fetches the revision for the speified config using the file backend.
A return of undef means that the config has no sets created for it yet or it has not been read yet by 2.0.0 or newer.
my $revision=$zconf->getConfigRevision('some/config');
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}
if(!defined($revision)){
print "This config has had no sets added since being created or is from a old version of ZConf.\n";
}getSubConfigs
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);
}isConfigLocked
This checks if a config is locked or not for the file backend.
One arguement is required and it is the name of the config.
The returned value is a boolean value.
my $locked=$zconf->isConfigLockedFile('some/config');
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}
if($locked){
print "The config is locked\n";
}read
readFile methods just like read, but is mainly intended for internal use only. This reads the config from the file backend.
hash args
config
The config to load.
override
This specifies if override should be ran not.
If this is not specified, it defaults to 1, true.
set
The set for that config to load.
$zconf->readFile({config=>"foo/bar"})
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}readChooser
This methods just like readChooser, but methods on the file backend and only really intended for internal use.
my $chooser = $zconf->readChooserFile("foo/bar");
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}setExists
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";
}
}setLockConfig
This unlocks or logs a config for the file backend.
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->setLockConfigFile('some/config', 1);
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}
#unlock 'some/config'
$zconf->setLockConfigFile('some/config', 0);
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}
#unlock 'some/config'
$zconf->setLockConfigFile('some/config');
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}writeChooser
This method is a internal method and largely meant to only be called writeChooser, which it methods the same as. It works on the file backend.
$zconf->writeChooserFile("foo/bar", $chooserString)
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}writeSetFromHash
This takes a hash and writes it to a config for the file backend. 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.
args hash
config
The config to write it to.
This is required.
set
This is the set name to use.
If not defined, the one will be choosen.
revision
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->writeSetFromHashFile({config=>"foo/bar"}, \%hash);
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}writeSetFromLoadedConfig
This method writes a loaded config to a to a set, for the file backend.
One arguement is required.
args hash
config
The config to write it to.
This is required.
set
This is the set name to use.
If not defined, the one will be choosen.
revision
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->writeSetFromLoadedConfigFile({config=>"foo/bar"});
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}writeSetFromZML
This writes a config set from a ZML object.
One arguement is required.
args hash
config
The config to write it to.
This is required.
set
This is the set name to use.
If not defined, the one will be choosen.
revision
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->writeSetFromZML({config=>"foo/bar", zml=>$zml});
if($zconf->error){
warn('error: '.$zconf->error.":".$zconf->errorString);
}ERROR HANDLING/CODES
This module uses Error::Helper for error handling. Below are the error codes returned by the error method.
1
config name contains ,
2
config name contains /.
3
config name contains //
4
config name contains ../
5
config name contains /..
6
config name contains ^./
7
config name ends in /
8
config name starts with /
9
could not sync to file
10
config name contains a \n
11
ZML dump failed.
12
config does not exist
14
file/dir does not exist
15
file/dir open failed
16
file/dir creation failed
17
file write failed
18
No variable name specified.
19
config key starts with a ' '
20
ZML object not specified.
21
set not found for config
22
LDAPmakepathSimple failed
23
skilling variable as it is not a legit name
24
set is not defined
25
Config is undefined.
26
Config not loaded.
27
Set name is not a legit name.
28
ZML->parse error.
29
Could not unlink the unlink the set.
30
The sets exist for the specified config.
31
Did not find a matching set.
32
Unable to choose a set.
33
Unable to remove the config as it has sub configs.
34
LDAP connection error
35
Can't use system mode and file together.
36
Could not create '/var/db/zconf'. This is a permanent error.
37
Could not create '/var/db/zconf/<sys name>'. This is a permanent error.
38
Sys name matched /\//.
39
Sys name matched /\./.
40
No chooser string specified.
41
No comment specified.
42
No meta specified.
43
Failed to open the revision file for the set.
44
Failed to open or unlink lock file.
45
Config is locked.
46
The base does not exist or could not be created.
47
No ZConf object passed.
48
No zconf.zml var hash passed.
ERROR CHECKING
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.
zconf.zml
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.
keys
backend
This should be set to 'file' to use this backend.
fileonly
This is a boolean value. If it is set to 1, only the file backend is used.
This will override 'backend'.
Basically the same as using the backend to 'file'.
file/base
This is the base directory to use for storing the configs in.
AUTHOR
Zane C. Bowers-Hadley, <vvelox at vvelox.net>
BUGS
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.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc ZConfYou can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
Subversion Repository
ACKNOWLEDGEMENTS
COPYRIGHT & LICENSE
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.