Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

94 lines (79 sloc) 3.235 kb
__NAME__ purpose
add a new configuration directive
__END__
__NAME__ synopsis
<arg choice='plain'><replaceable>directive_name</replaceable></arg>
<arg><replaceable>parse_function_name</replaceable>
<arg><replaceable>default_value</replaceable></arg></arg>
__END__
__NAME__ description
This directive allows you to extend the set of regular
&glos-configuration;
directives accepted in each &ccf;. The added
directives are then treated the same as the existing "built-ins".
</para><para>
Three standard arguments can be specified: the
<literal>directive_name</literal>,
<literal>parse_function_name</literal> and
<literal>default_value</literal>.
</para><para>
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/Config.pm</filename>.
The file <filename>lib/Vend/Config.pm</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>.)
</para><para>
The <literal>default_value</literal> is optional.
</para><para>
Directly modifying <filename>Config.pm</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;).
__END__
__NAME__ notes
Note that <literal>boolean</literal>, one of the default parse functions, is
actually
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.
</para><para>
Please see the &glos-configuration; glossary entry for a discussion
on config directives.
__END__
__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;:
<programlisting><![CDATA[
GlobalSub <<EOS
sub declare_extra_config {
package Vend::Config;
sub parse_docroot {
my ($var, $value) = @_;
unless ( -d $value ) { $@ = errmsg("Directory $value: $!") }
if ($@) { config_warn($@) }
return;
}
}
EOS
AddDirective DocRoot docroot "/var/www"
]]></programlisting>
__END__
__NAME__ example: Adding the "Swish" directive with an existing parse routine
<programlisting>
Require module Vend::Swish
Variable swish Vend::Swish
AddDirective Swish hash
</programlisting>
__END__
Jump to Line
Something went wrong with that request. Please try again.