/ 
ZConf-0.3.1
River stage zero No dependents
/ ZConf

NAME

ZConf - A configuration system allowing for either file or LDAP backed storage.

VERSION

Version 0.3.0

SYNOPSIS

This is currently mostly done and is largely being released as I want to get to writing some small desktop apps using it. Still needing implementation is fall through on error, syncing between backends, and listing of configs.

    use ZConf;

	#creates a new instance
    my $zconf = ZConf->new();
    ...

FUNCTIONS

new

my $zconf=ZCnf->(%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.

file

The default is 'xdf_config_home/zconf.zml', which is generally '~/.config/zconf.zml'.

chooseSet

This chooses what set should be used using the associated chooser string for the config in question.

This function 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.

my $set=$zconf->chooseSet("foo/bar")

chooseSetFile

Functions just like chooseSet, but for the file backend. It is intended for internal use only and should generally not be used by programs.

my $set=$zconf->chooseSetFile("foo/bar")

chooseSetLDAP

Functions just like chooseSet, but for the LDAP backend. Is is intended for internal use only and should generally notb be used by programs.

my $set=$zconf->chooseSetLDAP("foo/bar")

config2dn

This function converts the config name into part of a DN string. IT is largely only for internal use and is used by the LDAP backend.

my $partialDN = $zconf->config2dn("foo/bar");

configExists

This function 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.

if(!$zconf->configExists("foo/bar")){
	print "'foo/bar' does not exist\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->configExists("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

configExistsFile

This function functions 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.

if(!$zconf->configExistsFile("foo/bar")){
	print "'foo/bar' does not exist\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->configExistsFile("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

configExistsLDAP

This function functions exactly the same as configExists, but for the LDAP 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.

if(!$zconf->configExistsLDAP("foo/bar")){
	print "'foo/bar' does not exist\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->configExistsLDAP("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

configNameCheck

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(defined($error)){
	warn("zconf configExists:".$error.": ".$errorString);
	$self->{error}=$error;
	$self->{errorString}=$errorString;
	return undef;
};

createConfig

This function is used for creating a new config.

One arguement is needed and that is the config name.

The returned value is a perl boolean.

if(!$zconf->createConfig("foo/bar")){
	print "'foo/bar' could not be created\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->createConfig("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

createConfigFile

This functions 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.

if(!$zconf->createConfigFile("foo/bar")){
	print "'foo/bar' could not be created\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->createConfigFile("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

createConfigLDAP

This functions just like createConfig, but is for the LDAP backend. This is not really meant for external use. The config name passed is not checked to see if it is legit or not.

if(!$zconf->createConfigLDAP("foo/bar")){
	print "'foo/bar' could not be created\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->createConfigLDAP("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

defaultSetExists

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.

errorBlank

This blanks the error storage and is only meant to not meant to be called.

It does the following.

$zconf->{error}=undef;
$zconf->{errorString}="";

getAvailableSets

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}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

getAvailableSetsFile

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->getAvailableSetsFile("foo/bar");
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

getAvailableSetsLDAP

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->getAvailableSetsLDAP("foo/bar");
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

getDefault

This gets the default set currently being used if one is not choosen.

my $defaultSet = $zml->getDefault();

getKeys

This gets gets the keys for a loaded config.

my @keys = $zconf->getKeys("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

getLoadedConfigs

This gets gets the keys for a loaded config.

my @configs = $zconf->getLoadedConfigs("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

getSet

This gets the set for a loaded config.

my $set = $zconf->getSet("foo/bar")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\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}){
    print "There was some error.\n";
}

getSubConfigsFile

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}){
    print "There was some error.\n";
}

getSubConfigsLDAP

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}){
    print "There was some error.\n";
}

read

This reads a config. The only accepted option is the config name.

It takes one arguement, which is a hash. 'config' is the only required key in the hash and it holds the name of the config to be loaded. If set is defined in the hash, that specified set be used instead of the default or automatically choosen one.

if(!$zconf->read({config=>"foo/bar"})){
	print "'foo/bar' does not exist\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->read({config=>"foo/bar"})
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

readFile

readFile functions just like read, but is mainly intended for internal use only. This reads the config from the file backend.

if(!$zconf->readFile({config=>"foo/bar"})){
	print "'foo/bar' does not exist\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->readFile({config=>"foo/bar"})
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

readLDAP

readFile functions just like read, but is mainly intended for internal use only. This reads the config from the LDAP backend.

if(!$zconf->readLDAP({config=>"foo/bar"})){
	print "'foo/bar' does not exist\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->readLDAP({config=>"foo/bar"})
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

readChooser

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}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

readChooserFile

This functions just like readChooser, but functions on the file backend and only really intended for internal use.

my $chooser = $zconf->readChooserFile("foo/bar");
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

readChooserLDAP

This functions just like readChooser, but functions on the LDAP backend and only really intended for internal use.

my $chooser = $zconf->readChooserLDAP("foo/bar");
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

regexVarDel

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}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

regexVarGet

This searches through the variables in a loaded config for any that match the supplied regex and returns them in a hash.

Two arguements are required. The first is the config to search. The second is the regular expression to use.

#returns any variable begining with monkey
my %vars = $zconf->regexVarGet("foo/bar", "^monkey");
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

regexVarSearch

This searches through the variables in a loaded config for any that match the supplied regex and returns a array of matches.

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 @matched = $zconf->regexVarSearch("foo/bar", "^monkey")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

setDefault

This sets the default set to use if one is not specified or choosen.

if(!$zconf->setDefault("something")){
	print "'something' is not a legit set name\n";
};

#sets what the default set is
my $returned = $zconf->setDefault("something")
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

setNameLegit

This checks if a setname is legit.

There is one required arguement, which is the set name.

The returned value is a perl boolean value.

my $set="something";
if(!$zconf->setNameLegit($set)){
	print "'".$set."' is not a legit set name.\n";
};

setVar

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.

if(!$zconf->setVar("foo/bar" , "something", "eat more weazel\n\nor something")){
	print "A error occured when trying to set a variable.\n";
};

#sets what the default set is
my $returned = $zconf->setVar("foo/bar" , "something", "eat more weazel\n\nor something"
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

unloadConfig

Unloads a specified configuration. The only required value is the set name. The return value is a Perl boolean value.

if(!$zconf->unloadConfig($config)){
    print "error: ".$zconf->{error}."\n";
}

varNameCheck

my ($error, $errorString) = $zconf->varNameCheck($config);
if(defined($error)){
	$self->{error}=$error;
	$self->{errorString}=$errorString;
	return undef;
};

writeChooser

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.

#writes the contents of $chooserString to the chooser for "foo/bar"
if(!$zconf->writeChooser("foo/bar", $chooserString)){
	print "it failed\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->writeChooser("foo/bar", $chooserString)
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

writeChooserFile

This function is a internal function and largely meant to only be called writeChooser, which it functions the same as. It works on the file backend.

#writes the contents of $chooserString to the chooser for "foo/bar"
if(!$zconf->writeChooserFile("foo/bar", $chooserString)){
	print "it failed\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->writeChooserFile("foo/bar", $chooserString)
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

writeChooserLDAP

This function is a internal function and largely meant to only be called writeChooser, which it functions the same as. It works on the LDAP backend.

#writes the contents of $chooserString to the chooser for "foo/bar"
if(!$zconf->writeChooserLDAP("foo/bar", $chooserString)){
	print "it failed\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->writeChooserLDAP("foo/bar", $chooserString)
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

writeSetFromHash

This takes a hash and writes it to a config. It takes two arguements, both of which are hashes.

The first hash has one required key, which is 'config', the name of the config it is to be written to. If the 'set' is defined, that set will be used.

The second hash is the hash to be written to the config.

if(!$zconf->writeSetFromHash({config=>"foo/bar"}, %hash)){
	print "'foo/bar' does not exist\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->writeSetFromHash({config=>"foo/bar"}, %hash)
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

writeSetFromHashFile

This function is intended for internal use only and functions exactly like writeSetFromHash, but functions just on the file backend.

if(!$zconf->writeSetFromHashFile({config=>"foo/bar"}, %hash)){
	print "'foo/bar' does not exist\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->writeSetFromHashFile({config=>"foo/bar"}, %hash)
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

writeSetFromHashLDAP

This function is intended for internal use only and functions exactly like writeSetFromHash, but functions just on the LDAP backend.

if(!$zconf->writeSetFromHashLDAP({config=>"foo/bar"}, %hash)){
	print "'foo/bar' does not exist\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->writeSetFromHashLDAP({config=>"foo/bar"}, %hash)
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

writeSetFromLoadedConfig

This function writes a loaded config to a to a set.

One arguement is required, which is a hash. 'config' is the one required key in the hash and it represents the config that should be written out to a set. 'set' is a optional key that represents set the config will be written to. If there is not set defined, the current set will be used.

if(!$zconf->writeSetFromLoadedConfig({config=>"foo/bar"})){
	print "it failed\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->writeSetFromLoadedConfig({config=>"foo/bar"}, %hash)
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

writeSetFromLoadedConfigFile

This is a internal only function. No checking is done on the arguements as that is done in writeSetFromLoadedConfig. This provides the file backend for writeSetFromLoadedConfig.

if(!$zconf->writeSetFromLoadedConfigFile({config=>"foo/bar"})){
	print "it failed\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->writeSetFromLoadedConfigFile({config=>"foo/bar"}, %hash)
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

writeSetFromLoadedConfigLDAP

This is a internal only function. No checking is done on the arguements as that is done in writeSetFromLoadedConfig. This provides the LDAP backend for writeSetFromLoadedConfig.

if(!$zconf->writeSetFromLoadedConfigLDAP({config=>"foo/bar"})){
	print "it failed\n";
};

#does the same thing above, but using the error interface
my $returned = $zconf->writeSetFromLoadedConfigLDAP({config=>"foo/bar"}, %hash)
if($zconf->{error}){
	print 'error: '.$zconf->{error}."\n".$zconf->errorString."\n";
};

CONFIG NAME

Any configuration name is legit as long as it does not match any of the following.

undef
/./
/\/\./
/\.\.\//
/\/\//
/\.\.\//
/\/\.\./
/^\.\//
/\/$/
/^\//
/\n/

SET NAME

Any set name is legit as long as it does not match any of the following.

undef
/\//
/^\./
/^ /
/ $/
/\.\./

VARIABLE NAME

Any variable name is legit as long it does not match any of the following.

/,/
/\/\./
/\/\//
\.\.\//
/\/\.\./
/^\.\//
/\/$/	
/^\//
/\n/
/=/

ERROR CODES

0

LDAP connection error

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

LDAP entry already exists

12

config does not exist

13

Expected LDAP DN not found

14

file/dir does not exist

15

file/dir open failed

16

file/dir creation failed

17

file write failed

18

improper function usage

19

config key starts with a ' '

20

LDAP entry has no sets

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.

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.

INTERNALS

ZConf stores the object information in a hash. The keys are 'conf', 'args', 'zconf', 'user', 'error', and 'errorString'.

conf

This is a hash whose keys represent various configs. Each item in the hash is another hash. Each key of that a value in a config.

args

This is the arguements currently in use by ZConf.

zconf

This is the parsed configuration settings for ZConf as pulled from xdg_config_home()."/zconf.zml".

error

This is contains the error code if there is an error. It is undefined when none is present.

errorString

This contains a description of the error when one is present. When one is not present it is "".

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.

General Keys

backend

This is the backend to use for storage. Current values of 'file' and 'ldap' are supported.

backendChooser

This is a Chooser string that chooses what backend should be used.

defaultChooser

This is a chooser string that chooses what the name of the default to use should be.

fileonly

This is a boolean value. If it is set to 1, only the file backend is used.

LDAP Backend Keys

LDAPprofileChooser

This is a chooser string that chooses what LDAP profile to use. If this is not present, 'default' will be used for the profile.

ldap/<profile>/bind

This is the DN to bind to the server as.

ldap/<profile>/homeDN

This is the home DN of the user in question. The user needs be able to write to it. ZConf will attempt to create 'ou=zconf,ou=.config,$homeDN' for operating out of.

ldap/<profile>/host

This is the server to use for LDAP connections.

ldap/<profile>/password

This is the password to use for when connecting to the server.

ZConf LDAP Schema

# 1.3.6.1.4.1.26481 Zane C. Bowers
#  .2 ldap
#   .7 zconf
#    .0 zconfData
#    .1 zconfChooser
#    .2 zconfSet

attributeType ( 1.3.6.1.4.1.26481.2.7.0
	NAME 'zconfData'
	DESC 'Data attribute for a zconf entry.'
	SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
	EQUALITY caseExactMatch
	)

attributeType ( 1.3.6.1.4.1.26481.2.7.1
	NAME 'zconfChooser'
	DESC 'Chooser attribute for a zconf entry.'
	SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
	EQUALITY caseExactMatch
	)

attributeType ( 1.3.6.1.4.1.26481.2.7.2
	NAME 'zconfSet'
	DESC 'A zconf set name available in a entry.'
	SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
	EQUALITY caseExactMatch
	)

objectclass ( 1.3.6.1.4.1.26481.2.7
	NAME 'zconf'
	DESC 'A zconf entry.'
	MAY ( cn $ zconfData $ zconfChooser $ zconfSet )
	)

AUTHOR

Zane C. Bowers, <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 ZConf

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2008 Zane C. Bowers, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.