.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 >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::Plugin::Shortcircuit 3pm"
.TH Mail::SpamAssassin::Plugin::Shortcircuit 3pm "2021-03-26" "perl v5.28.1" "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::Plugin::Shortcircuit \- short\-circuit evaluation for certain rules
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  loadplugin     Mail::SpamAssassin::Plugin::Shortcircuit
\&
\&  report Content analysis details:   (_SCORE_ points, _REQD_ required, s/c _SCTYPE_)
\&
\&  add_header all Status "_YESNO_, score=_SCORE_ required=_REQD_ tests=_TESTS_ shortcircuit=_SCTYPE_ autolearn=_AUTOLEARN_ version=_VERSION_"
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This plugin implements simple, test-based shortcircuiting.  Shortcircuiting a
test will force all other pending rules to be skipped, if that test is hit.
In addition, a symbolic rule, \f(CW\*(C`SHORTCIRCUIT\*(C'\fR, will fire.
.PP
Recomended usage is to use \f(CW\*(C`priority\*(C'\fR to set rules with strong S/O values (ie.
1.0) to be run first, and make instant spam or ham classification based on
that.
.SH "CONFIGURATION SETTINGS"
.IX Header "CONFIGURATION SETTINGS"
The following configuration settings are used to control shortcircuiting:
.IP "shortcircuit \s-1SYMBOLIC_TEST_NAME\s0 {ham|spam|on|off}" 4
.IX Item "shortcircuit SYMBOLIC_TEST_NAME {ham|spam|on|off}"
Shortcircuiting a test will force all other pending rules to be skipped, if
that test is hit.
.Sp
Recomended usage is to use \f(CW\*(C`priority\*(C'\fR to set rules with strong S/O values (ie.
1.0) to be run first, and make instant spam or ham classification based on
that.
.Sp
To override a test that uses shortcircuiting, you can set the classification
type to \f(CW\*(C`off\*(C'\fR.
.RS 4
.IP "on" 4
.IX Item "on"
Shortcircuits the rest of the tests, but does not make a strict classification
of spam or ham.  Rather, it uses the default score for the rule being
shortcircuited.  This would allow you, for example, to define a rule such as
.Sp
.Vb 5
\&  body TEST /test/
\&  describe TEST test rule that scores barely over spam threshold
\&  score TEST 5.5
\&  priority TEST \-100
\&  shortcircuit TEST on
.Ve
.Sp
The result of a message hitting the above rule would be a final score of 5.5,
as opposed to 100 (default) if it were classified as spam.
.IP "off" 4
.IX Item "off"
Disables shortcircuiting on said rule.
.IP "spam" 4
.IX Item "spam"
Shortcircuit the rule using a set of defaults; override the default score of
this rule with the score from \f(CW\*(C`shortcircuit_spam_score\*(C'\fR, set the
\&\f(CW\*(C`noautolearn\*(C'\fR tflag, and set priority to \f(CW\*(C`\-100\*(C'\fR.  In other words,
equivalent to:
.Sp
.Vb 4
\&  shortcircuit TEST on
\&  priority TEST \-100
\&  score TEST 100
\&  tflags TEST noautolearn
.Ve
.IP "ham" 4
.IX Item "ham"
Shortcircuit the rule using a set of defaults; override the default score of
this rule with the score from \f(CW\*(C`shortcircuit_ham_score\*(C'\fR, set the \f(CW\*(C`noautolearn\*(C'\fR
and \f(CW\*(C`nice\*(C'\fR tflags, and set priority to \f(CW\*(C`\-100\*(C'\fR.   In other words, equivalent
to:
.Sp
.Vb 4
\&  shortcircuit TEST on
\&  priority TEST \-100
\&  score TEST \-100
\&  tflags TEST noautolearn nice
.Ve
.RE
.RS 4
.RE
.IP "shortcircuit_spam_score n.nn (default: 100)" 4
.IX Item "shortcircuit_spam_score n.nn (default: 100)"
When shortcircuit is used on a rule, and the shortcircuit classification type
is set to \f(CW\*(C`spam\*(C'\fR, this value should be applied in place of the default score
for that rule.
.IP "shortcircuit_ham_score n.nn (default: \-100)" 4
.IX Item "shortcircuit_ham_score n.nn (default: -100)"
When shortcircuit is used on a rule, and the shortcircuit classification type
is set to \f(CW\*(C`ham\*(C'\fR, this value should be applied in place of the default score
for that rule.
.SH "TAGS"
.IX Header "TAGS"
The following tags are added to the set available for use in reports, headers
etc.:
.PP
.Vb 3
\&  _SC_              shortcircuit status (classification and rule name)
\&  _SCRULE_          rulename that caused the shortcircuit 
\&  _SCTYPE_          shortcircuit classification ("spam", "ham", "default", "none")
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\f(CW\*(C`http://issues.apache.org/SpamAssassin/show_bug.cgi?id=3109\*(C'\fR