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.

AUTHOR

Elizabeth Grace Frank-Backman

COPYRIGHT

LICENSE

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

To install SVN::Friendly::Dates, copy and paste the appropriate command in to your terminal.

cpanm

cpanm SVN::Friendly::Dates

CPAN shell

perl -MCPAN -e shell
install SVN::Friendly::Dates

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)