.\" Automatically generated by Pod::Man 2.28 (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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::Conf::Parser 3pm"
.TH Mail::SpamAssassin::Conf::Parser 3pm "2017-05-06" "perl v5.20.2" "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.