.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::Conf::Parser 3"
.TH Mail::SpamAssassin::Conf::Parser 3 "2015-04-29" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::SpamAssassin::Conf::Parser \- parse SpamAssassin configuration
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  (see Mail::SpamAssassin)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mail::SpamAssassin is a module to identify spam using text analysis and
several internet-based realtime blacklists.
.PP
This class is used internally by SpamAssassin to parse its configuration files.
Please refer to the \f(CW\*(C`Mail::SpamAssassin\*(C'\fR documentation for public interfaces.
.SH "STRUCTURE OF A CONFIG BLOCK"
.IX Header "STRUCTURE OF A CONFIG BLOCK"
This is the structure of a config-setting block.  Each is a hashref which may
contain these keys:
.IP "setting" 4
.IX Item "setting"
the name of the setting it modifies, e.g. \*(L"required_score\*(R". this also doubles
as the default for 'command' (below). \s-1THIS IS REQUIRED.\s0
.IP "command" 4
.IX Item "command"
The command string used in the config file for this setting.  Optional;
\&'setting' will be used for the command if this is omitted.
.IP "aliases" 4
.IX Item "aliases"
An [aryref] of other aliases for the same command.  optional.
.IP "type" 4
.IX Item "type"
The type of this setting:
.Sp
.Vb 12
\& \- $CONF_TYPE_NOARGS: must not have any argument, like "clear_headers"
\& \- $CONF_TYPE_STRING: string
\& \- $CONF_TYPE_NUMERIC: numeric value (float or int)
\& \- $CONF_TYPE_BOOL: boolean (0/no or 1/yes)
\& \- $CONF_TYPE_TEMPLATE: template, like "report"
\& \- $CONF_TYPE_ADDRLIST: list of mail addresses, like "whitelist_from"
\& \- $CONF_TYPE_HASH_KEY_VALUE: hash key/value pair, like "describe" or tflags
\& \- $CONF_TYPE_STRINGLIST list of strings, stored as an array
\& \- $CONF_TYPE_IPADDRLIST list of IP addresses, stored as an array of SA::NetSet
\& \- $CONF_TYPE_DURATION a nonnegative time interval in seconds \- a numeric value
\&                      (float or int), optionally suffixed by a time unit (s, m,
\&                      h, d, w), seconds are implied if unit is missing
.Ve
.Sp
If this is set, and a 'code' block does not already exist, a 'code' block is
assigned based on the type.
.Sp
In addition, the SpamAssassin test suite will validate that the settings
do not 'leak' between users.
.Sp
Note that \f(CW$CONF_TYPE_HASH_KEY_VALUE\fR\-type settings require that the
value be non-empty, otherwise they'll produce a warning message.
.IP "code" 4
.IX Item "code"
A subroutine to deal with the setting.  \s-1ONE OF \s0\fBcode\fR \s-1OR \s0\fBtype\fR \s-1IS REQUIRED.\s0
The arguments passed to the function are \f(CW\*(C`($self, $key, $value, $line)\*(C'\fR,
where \f(CW$key\fR is the setting (*not* the command), \f(CW$value\fR is the value string,
and \f(CW$line\fR is the entire line.
.Sp
There are two special return values that the \fBcode\fR subroutine may return
to signal that there is an error in the configuration:
.Sp
\&\f(CW$Mail::SpamAssassin::Conf::MISSING_REQUIRED_VALUE\fR \*(-- this setting requires
that a value be set, but one was not provided.
.Sp
\&\f(CW$Mail::SpamAssassin::Conf::INVALID_VALUE\fR \*(-- this setting requires a value
from a set of 'valid' values, but the user provided an invalid one.
.Sp
\&\f(CW$Mail::SpamAssassin::Conf::INVALID_HEADER_FIELD_NAME\fR \*(-- this setting
requires a syntactically valid header field name, but the user provided
an invalid one.
.Sp
Any other values \*(-- including \f(CW\*(C`undef\*(C'\fR \*(-- returned from the subroutine are
considered to mean 'success'.
.Sp
It is good practice to set a 'type', if possible, describing how your settings
are stored on the Conf object; this allows the SpamAssassin test suite to
validate that the settings do not 'leak' between users.
.IP "default" 4
.IX Item "default"
The default value for the setting.  may be omitted if the default value is a
non-scalar type, which should be set in the Conf ctor.  note for path types:
using \*(L"_\|_userstate_\|_\*(R" is recommended for defaults, as it allows
Mail::SpamAssassin module users who set that configuration setting, to receive
the correct values.
.IP "is_priv" 4
.IX Item "is_priv"
Set to 1 if this setting requires 'allow_user_rules' when run from spamd.
.IP "is_admin" 4
.IX Item "is_admin"
Set to 1 if this setting can only be set in the system-wide config when run
from spamd.  (All settings can be used by local programs run directly by the
user.)
.IP "is_frequent" 4
.IX Item "is_frequent"
Set to 1 if this value occurs frequently in the config. this means it's looked
up first for speed.