diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2008-11-02 00:04:55 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2008-11-02 00:04:55 +0000 |
commit | 24fbd12566346861b0b57a329ff9d6a35250baea (patch) | |
tree | 7d2d6b2d83ca1ba204755d5d503d86ab707b246f /doc/mailfromd.texi | |
parent | bb0b0e2f5002e2c0e3badc85045daa701f21fe80 (diff) | |
download | mailfromd-24fbd12566346861b0b57a329ff9d6a35250baea.tar.gz mailfromd-24fbd12566346861b0b57a329ff9d6a35250baea.tar.bz2 |
New functions: replstr, ml_header, sa_format_score, sa_format_report_header
* mflib/sa.mf: New file.
* mflib/Makefile.am (inc_DATA): Add sa.mf
* mfd/bi_string.m4 (replstr): New function.
* doc/mailfromd.texi: Document new functions.
* NEWS: Update.
git-svn-id: file:///svnroot/mailfromd/trunk@1716 7a8a7f39-df28-0410-adc6-e0d955640f24
Diffstat (limited to 'doc/mailfromd.texi')
-rw-r--r-- | doc/mailfromd.texi | 145 |
1 files changed, 125 insertions, 20 deletions
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi index 058e53ef..40995a82 100644 --- a/doc/mailfromd.texi +++ b/doc/mailfromd.texi @@ -5681,6 +5681,34 @@ localpart "gray@@gnu.org.ua" @result{} "gray" @end smallexample @end deftypefn +@deftypefn {Built-in Function} string ml_header (string @var{text}) + If @var{text} is a multi-line string, the function reformats it, by +inserting a horizontal tabulation character (@acronym{ASCII} 09) +before each newline (@acronym{ASCII} 10). Use this function to format +multi-line strings for use in message headers. For example: + +@smallexample + string text <<EOT + A multi-line + text + EOT + + add "X-String" ml_header(%text) +@end smallexample + +@xref{Actions, Header manipulation actions}, and +@xref{Header modification functions}. +@end deftypefn + +@deftypefn {Built-in Function} string replstr (string @var{s}, number @var{n}) + Replicate a string, i.e. return a string, consisting of @var{s} +repeated @var{n} times: + +@smallexample +replstr("12", 3) @result{} "121212" +@end smallexample +@end deftypefn + @deftypefn {Built-in Function} string revstr (string @var{s}) Returns the string composed of the characters from @var{s} in reversed order: @@ -5776,6 +5804,36 @@ toupper "mail" @result{} "MAIL" @end deftypefn +@deftypefn {Library Function} string sa_format_score (number @var{code}, @ + number @var{prec}) +Format @var{code} as a floating-point number with @var{prec} decimal +digits: + +@smallexample +sa_format_score(5000, 3) @result{} "5.000" +@end smallexample + +@flindex sa.mf +This function is convenient for formatting SpamAssassin scores for use +in message headers and textual reports. It is defined in module +@file{sa.mf}. + +@xref{sa, SpamAssassin}, for examples of its use. +@end deftypefn + +@deftypefn {Library Function} string sa_format_report_header (string @var{text}) +Format a SpamAssassin report text in order to include it in a RFC 822 +header. This function selects the score listing from @var{%text}, and +prefixes each line with @samp{* }. Its result looks like: + +@smallexample +* 0.2 NO_REAL_NAME From: does not include a real name +* 0.1 HTML_MESSAGE BODY: HTML included in message +@end smallexample + +@xref{sa, SpamAssassin}, for examples of its use. +@end deftypefn + @anchor{strip_domain_part} @deftypefn {Library Function} string strip_domain_part (string @var{domain}, @ number @var{n}) @@ -7287,6 +7345,8 @@ socket:///var/run/filter.sock @cindex SpamAssassin @cindex spamd @deftypefn {Built-in Function} boolean sa (string @var{url}, number @var{prec}) +@deftypefnx {Built-in Function} boolean sa (string @var{url}, @ + number @var{prec}, number @var{report}) Pass the message to the SpamAssassin daemon (@code{spamd}) at @var{url}. Return @code{true} if SpamAssassin considers it a spam, @code{false} otherwise. The second arguments, @var{prec}, gives the @@ -7304,22 +7364,78 @@ where @var{sa-var} stands for the SpamAssassin value and @var{var} stands for the corresponding @command{mailfromd} one. @code{int()} means taking the integer part. +Optional third argument, @var{report}, is used to control what kind of +data is returned in the @code{sa_keywords} variable. See below for +its description. + The function returns additional information via the following variables: @table @code @cindex sa_score, global variable @item sa_score -The spam score, converted to integer as described above. +The spam score, converted to integer as described above. To convert +it to a floating-point representation, use @code{sa_format_score} +function (@pxref{String manipulation, sa_format_score}). See also the +example below. @cindex sa_threshold, global variable @item sa_threshold -The threshold, converted to integer. +The threshold, converted to integer form. @cindex sa_keywords, global variable @item sa_keywords -A string of comma-separated SpamAssassin keywords identifying this -message. +If @var{report} is not supplied or is null, this variable contains a +string of comma-separated SpamAssassin keywords identifying this +message, e.g.: + +@smallexample +ADVANCE_FEE_1,AWL,BAYES_99 +@end smallexample + +Otherwise, if @var{report} is not null, the value of this variable is +a @dfn{spam report} message. It is a multi-line textual message, +containing detailed description of spam scores in a tabular form. +It consists of the following parts: + +@enumerate +@item A preamble. +@item Content preview. + +The words @samp{Content preview}, followed by a colon and an excerpt +of the message body. + +@item Content analysis details. + +It has the following form: + +@smallexample +Content analysis details: (@var{score} points, @var{max} required) +@end smallexample + +@noindent +where @var{score} and @var{max} are spam score and threshold in +floating point. + +@item Score table. + +The score table is formatted in three columns: + +@table @asis +@item pts +The score, as a floating point number with one decimal digit. + +@item rule name +SpamAssassin rule name that contributed this score. + +@item description +Textual description of the rule +@end table + +The score table can be extracted from @code{sa_keywords} using +@code{sa_format_report_header} function (@pxref{String manipulation, +sa_format_report_header}), as illustrated in the example below. +@end enumerate @end table The @code{sa} function can signal the following exceptions: @@ -7344,29 +7460,18 @@ done Here is a more advanced example: @smallexample -/* @r{Convert a SpamAssassin @code{code} back to fixed point form - using the given number of digits (@code{prec})} */ -func to_double_str(string code, number prec) returns string -do - if length(%code) > %prec - return substring(%code, 0, length(%code)-%prec-1) '.' - substring(%code, length(%code)-%prec, -1) - else - return $1 - fi -done - prog eom do set prec 3 - if sa("tcp://192.168.10.1:3333", %prec) + if sa("tcp://192.168.10.1:3333", %prec, 1) add "X-Spamd-Status" "SPAM" else add "X-Spamd-Status" "OK" fi - add "X-Spamd-Score" to_double_str(%sa_score, %prec) - add "X-Spamd-Threshold" to_double_str(%sa_threshold, %prec) - add "X-Spamd-Keywords" %sa_keywords + add "X-Spamd-Score" sa_format_score(%sa_score, %prec) + add "X-Spamd-Threshold" sa_format_score(%sa_threshold, %prec) + add "X-Spamd-Keywords" + ml_header(sa_format_report_header(%sa_keywords)) done @end smallexample |