Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
94 lines (79 sloc) 3.16 KB
__NAME__ purpose
add a new configuration directive
__NAME__ synopsis
<arg choice='plain'><replaceable>directive_name</replaceable></arg>
__NAME__ description
This directive allows you to extend the set of regular
directives accepted in each &ccf;. The added
directives are then treated the same as the existing "built-ins".
Three standard arguments can be specified: the
<literal>parse_function_name</literal> and
If the parse function is not defined (either by omitting it or
literally specifying <literal>undef</literal>), then no parser
will be called on the value at all,
and the value of the directive will be exactly what users specify in their
config files (which will usually be &PERL; scalar values). If the parser
argument <emphasis>is</emphasis> supplied, then the requested parser function
must already be defined because it can't be referenced
<emphasis>in advance</emphasis>. It can be defined either as a
&conf-Sub; or &conf-GlobalSub; block, or can refer to an existing parser
function from <filename>lib/Vend/</filename>.
The file <filename>lib/Vend/</filename> contains all the default
parser functions, which are recognized by the mandatory prefix
<literal>parse_</literal>. (You do not, however, include
<literal>parse_</literal> in the <literal>parse_function_name</literal>.)
The <literal>default_value</literal> is optional.
Directly modifying <filename></filename> (or any other
files from the &IC; installation) is discouraged for portability
reasons. Therefore, to add a custom parsing function, you should
modify &gcf; as seen in <xref linkend="AddDirective_examples"/>
(note again that the parser definition
must logically come before &conf-AddDirective;).
__NAME__ notes
Note that <literal>boolean</literal>, one of the default parse functions, is
a boolean list, and not a true boolean value. The list achieves the effect
of being boolean by logically returning &glos-true; or &glos-false;,
depending on whether the searched item is present in the list or not.
True boolean values are called "<literal>yesno</literal>"s in &IC; parlance.
Please see the &glos-configuration; glossary entry for a discussion
on config directives.
__NAME__ example: Adding a new catalog configuration directive with a custom parse routine
Let's add the <literal>DocRoot</literal> directive. Put the following
in your &gcf;:
GlobalSub <<EOS
sub declare_extra_config {
package Vend::Config;
sub parse_docroot {
my ($var, $value) = @_;
unless ( -d $value ) { $@ = errmsg("Directory $value: $!") }
if ($@) { config_warn($@) }
AddDirective DocRoot docroot "/var/www"
__NAME__ example: Adding the "Swish" directive with an existing parse routine
Require module Vend::Swish
Variable swish Vend::Swish
AddDirective Swish hash