.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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 2024-09-01 "perl v5.40.0" "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 blocklists.
.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. "required_score". this also doubles
as the default for 'command' (below). THIS IS REQUIRED.
.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 "welcomelist_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.  ONE OF \fBcode\fR OR \fBtype\fR IS REQUIRED.
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 "_\|_userstate_\|_" 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.)