NAME
SVN::Friendly::Config - User friendly access to Subversion configuration data.
SYNOPSIS
use Config;
$oConfig = Svn::Friendly::Config->new();
$oConfig = Svn::Friendly::Config->new($sNative, $oPool);
#------------------------------------------------
# list categories, sections and properties
#------------------------------------------------
$aNames = $oConfig->getCategoryNames();
$bFound = $oConfig->hasSection($sCategory, $sSection);
$aNames = $oConfig->getSectionNames($sCategory);
$oConfig->visitSections($sCategory, $crVisit);
$oConfig->find_group($sCategory, $sItem, $sWildcardSection
, $oPool);
$aNames = $oConfig->getOptionNames($sCategory, $sSection);
$oConfig->visitOptions($sCategory, $sSection, $crVisit);
#------------------------------------------------
# getting configuration properties
#------------------------------------------------
$oConfig->get($sCategory, $sSection, $sOption);
$oConfig->get($sCategory, $sSection, $sOption, $xDefault);
$oConfig->get_bool($sCategory, $sSection, $sOption);
$oConfig->get_bool($sCategory, $sSection, $sOption
, $xBoolishDefault);
$oConfig->get_server_setting($sCategory, sServerGroup, $sOption);
$oConfig->get_server_setting($sCategory, $sServerGroup, $sOption
, $xDefault);
$oConfig->get_server_setting_int($sCategory, $sServerGroup
, $sOption);
$oConfig->get_server_setting_int($sCategory, $sServerGroup
, $sOption, $xDefault);
#------------------------------------------------
# setting configuration properties
#------------------------------------------------
$oConfig->merge($sCategory, $sFile);
$oConfig->merge($sCategory, $sFile, $bMustExist);
$oConfig->read($sCategory, $sFile);
$oConfig->read($sCategory, $sFile, $bMustExist, $oPool);
$oConfig->set($sCategory, $sSection, $sOption, $xValue);
$oConfig->set_bool($sCategory, $sSection, $sOption, $xBoolishValue);
#------------------------------------------------
# Get svn_config_t objects and hashes
#------------------------------------------------
$oCategory = $oConfig->getCategory($sCategory);
$hCategories xrw= $oConfig->getCategoryHash();
DESCRIPTION
This class provides a wrapper around the subversion configuration hash and also emulates certain functions that are either missing from subversion 1.1, as well as later methods that have incomplete SWIG binding definitions (see "CAVEATS").
Relationship to the C-API
As with SVN::Friendly::Client the methods defined for this class try to strike a balance between closely following the C-API and usability. Once again there are two families of methods: those ending in a major_minor version number and those without.
The major_minor version number methods are taken from the list of config methods in svn_conifg.h (see http://svn.collab.net/svn-doxygen/svn__config_8h.html).
Because this object wraps a hash containing svn_config_t
objects rather than a single object, some minor adjustments have been made to the funciton definitions:
All methods get an extra "category" parameter that identifies which
svn_config_t
object we want to operate on. This parameter is nothing more than a key name stored in the configuration hash.
For more information about method naming conventions, please see SVN::Friendly::Client
Terminology
In this documentation svn_config_t
objects are called category objects because they are mapped to category names in the configuration hash. This naming also makes clear the distinction between the configuration as a whole stored in a hash, and an individual category with in that configuration stored in a svn_config_t
object.
Parameter naming conventions
For more information about parameter naming conventions, ordering, rules for defaulting and omitting parameters, etc, please see See SVN::Friendly::Client .
USAGE
The configuration object is stores all the configuration information used by subversion. The configuration information is stored as a set of name-value pairs. Name-value pairs, also known as options, are grouped into sections and sections are grouped into categories.
To access any value, you need to know the categoory, section, and option names. Hence the methods for this class fall into two major groupings: (a) listing out the available categories, sections, and options (b) retrieving and setting values for those options.
The major_minor version number methods are taken from the list of config methods in svn_conifg.h (see http://svn.collab.net/svn-doxygen/svn__config_8h.html).
names.
Creating a configuration object
# $sDir - local file system path to a configuration directory
$oConfig = Svn::Friendly::Config->new();
$oConfig = Svn::Friendly::Config->new($sDir, $oPool);
List configuration sections and properties
$aNames = $oConfig->getCategoryNames();
$bFound = $oConfig->hasSection($sCategory, $sSection);
$aNames = $oConfig->getSectionNames($sCategory);
$oConfig->visitSections($sCategory, $crVisit);
$oConfig->enumerate_sections($crVisit);
$oConfig->enumerate_sections1_1($crVisit);
$oConfig->enumerate_sections1_4($crVisit, $oPool);
$oConfig->enumerate_sections1_5($crVisit, $oPool);
$oConfig->enumerate_sections1_6($crVisit, $oPool);
$oConfig->enumerate_sections1_7($crVisit, $oPool);
$oConfig->find_group($sCategory, $sItem, $sWildcardSection
, $oPool);
# find_group1_1, etc have the same parameters
$aNames = $oConfig->getOptionNames($sCategory, $sSection);
$oConfig->visitOptions($sCategory, $sSection, $crVisit);
$oConfig->enumerate($crVisit, $sSection);
$oConfig->enumerate1_1($crVisit, $sSection);
$oConfig->enumerate1_4($crVisit, $sSection, $oPool);
$oConfig->enumerate1_5($crVisit, $sSection, $oPool);
$oConfig->enumerate1_6($crVisit, $sSection, $oPool);
$oConfig->enumerate1_7($crVisit, $sSection, $oPool);
- enumerate
-
This method visits each option name-value pair within a section and passes it to the routine stored in the
$crVisit
parameter. This routine should be defined to expect the parameters below;sub visitOption { my ($sOption, $sValue) = @_; }
- enumerate_sections
-
This method visits each section name within a configuration object and passes it to the routine stored in the
$crVisit
parameter. This routine should be defined to expect the parameters below;sub visitSection { my ($sSection) = @_; }
- find_group
-
Looks up
$sItem
in a wildcard section named$sWildcardSection
and returns the option name associated with the matching wildcard.A wildcard section is a section where each option is set to a comma delimited list of wildcard expressions. This method searches through all the wildcard expressions until it finds one that matches. When it finds a match it returns the option name associated with that wildcard expression.
This method is named after one of the original uses of this method: finding the configuration section for a server. In that case the wildcard section was named "groups", the option names were the names of sections storing server configuration information. The wildcards mapped server names to the section responsible for configuring them:
[groups] perl = *.perl.org collabnet = svn.collab.net [perl] ~ [collabnet] ~
Getting and setting configuration values
#------------------------------------------------
# get configuration properties
#------------------------------------------------
$oConfig->get($sCategory, $sSection, $sOption);
$oConfig->get($sCategory, $sSection, $sOption, $xDefault);
# get1_1, etc have the same parameters
$oConfig->get_bool($sCategory, $sSection, $sOption);
$oConfig->get_bool($sCategory, $sSection, $sOption
, $xBoolishDefault);
# get_bool1_1, etc have the same parameters
$oConfig->get_server_setting($sCategory, sServerGroup, $sOption);
$oConfig->get_server_setting($sCategory, $sServerGroup, $sOption
, $xDefault);
# get_get_server_setting1_1, etc have the same parameters
$oConfig->get_server_setting_int($sCategory, $sServerGroup
, $sOption);
$oConfig->get_server_setting_int($sCategory, $sServerGroup
, $sOption, $xDefault);
# get_get_server_setting_int1_1, etc have the same parameters
#------------------------------------------------
# set configuration properties
#------------------------------------------------
$oConfig->merge($sCategory, $sFile);
$oConfig->merge($sCategory, $sFile, $bMustExist);
# merge1_1, etc have the same parameters
$oConfig->read($sCategory, $sFile);
$oConfig->read($sCategory, $sFile, $bMustExist, $oPool);
# read1_1, etc have the same parameters
$oConfig->set($sCategory, $sSection, $sOption, $xValue);
# set1_1, etc have the same parameters
$oConfig->set_bool($sCategory, $sSection, $sOption, $xBoolishValue);
# set1_1, etc have the same parameters
Accessing the svn_config_t object
If you want to work with the raw API and need the svn_config_t object you can access that through this method:
# $oCategory is a svn_config_t object
$oCategory = $oConfig->getCategory($sCategory);
$hCategories xrw= $oConfig->getCategoryHash();
- get
-
Retrieves the value of an option.
- get_bool
-
Retrieves the value of an option and converts it to a boolean. The default value, if provided, must be set to any of the following:
"true","false","on","off","yes","no","1","0"
. Case does not matter. If no value is provided$xBoolishDefault
defaults to false (0). - get_sever_setting
-
Retrieves a setting from one of the groups retrieved by
find_group
- get_server_setting_int
- merge
-
Reads in property settings from the file
$sFile
and merges them with existing property settings for category$sCategory
. By merging we mean that existing option values will be overwritten by option values in the file and new ones from the file will be added. - read
-
Reloads the property settings for category
$sCategory
and sets them to those stored in$sFile
. - set
-
Sets an option.
- set_bool
-
Sets an option to a boolean value.
$xBoolishValue
may be any of the following:"true","false","on","off","yes","no","1","0"
. Case does not matter.
VERSION COMPATIBILITY
See SVN::Friendly.
CAVEATS
KNOWN BUGS
In the 1.4.6 release of Alien::SVN the following methods will not work, presumably because of missing elements in their SWIG binding definition:
* enumerate_sections
- the callbacks needed by this method do not appear to have a thunk defined. You can use visitSections
instead, which serves much the same purpose.
* enumerate1_4
and later - the callback thunk needed by the later versions of this method doesn't have a thunk defined.
TO DO/ROADMAP
See SVN::Friendly
VOLUNTEERS
If anyone would like to be involved in testing or expanding the user friendly interface, please contact the maintainer.
Feedback on the documentation, bugs, usability, or additional features desired is welcome. Time and person-power permitting the most commonly requested features will be implemented.
SEE ALSO
See SVN::Friendly
AUTHOR
Elizabeth Grace Frank-Backman
COPYRIGHT
Copyright (c) 2008-2011 Elizabeth Grace Frank-Backman. All rights reserved.
LICENSE
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.