You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@spamassassin.apache.org by km...@apache.org on 2014/02/11 18:26:52 UTC
svn commit: r1567225 [1/15] - in /spamassassin/site/full/3.4.x: ./ doc/
Author: kmcgrail
Date: Tue Feb 11 17:26:49 2014
New Revision: 1567225
URL: http://svn.apache.org/r1567225
Log:
Adding 3.4.x docs
Added:
spamassassin/site/full/3.4.x/
spamassassin/site/full/3.4.x/doc/
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AICache.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AICache.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_ArchiveIterator.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_ArchiveIterator.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AsyncLoop.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AsyncLoop.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AutoWhitelist.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AutoWhitelist.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Bayes.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Bayes.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_BDB.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_MySQL.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_PgSQL.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_PgSQL.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_Redis.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_Redis.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_SQL.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_BayesStore_SQL.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Client.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Client.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Conf.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Conf.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Conf_LDAP.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Conf_LDAP.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Conf_Parser.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Conf_Parser.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Conf_SQL.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Conf_SQL.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_DnsResolver.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_DnsResolver.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Logger.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Logger.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Logger_File.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Logger_File.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Logger_Stderr.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Logger_Stderr.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Logger_Syslog.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Logger_Syslog.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Message.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Message.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Message_Metadata.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Message_Metadata.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Message_Node.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Message_Node.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_PerMsgLearner.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_PerMsgLearner.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_PerMsgStatus.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_PerMsgStatus.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_PersistentAddrList.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_PersistentAddrList.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_PluginHandler.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_PluginHandler.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_ASN.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_ASN.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_AWL.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_AWL.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_AccessDB.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_AccessDB.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_AntiVirus.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_AntiVirus.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_AskDNS.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_AskDNS.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_AutoLearnThreshold.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_AutoLearnThreshold.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Bayes.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Bayes.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_BodyRuleBaseExtractor.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_BodyRuleBaseExtractor.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Check.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Check.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_DCC.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_DCC.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_DKIM.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_DKIM.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_DNSEval.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_DNSEval.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Hashcash.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Hashcash.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_MIMEHeader.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_MIMEHeader.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_NetCache.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_NetCache.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_OneLineBodyRuleType.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_OneLineBodyRuleType.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_PhishTag.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_PhishTag.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Pyzor.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Pyzor.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Razor2.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Razor2.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_RelayCountry.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_RelayCountry.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_ReplaceTags.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_ReplaceTags.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Reuse.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Reuse.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Rule2XSBody.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Rule2XSBody.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_SPF.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_SPF.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Shortcircuit.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Shortcircuit.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_SpamCop.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_SpamCop.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Test.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_Test.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_TextCat.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_TextCat.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_URIDNSBL.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_URIDNSBL.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_URIDetail.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_URIDetail.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_VBounce.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_VBounce.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_WhiteListSubject.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Plugin_WhiteListSubject.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_SQLBasedAddrList.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_SQLBasedAddrList.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_SubProcBackChannel.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_SubProcBackChannel.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Timeout.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Timeout.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Util.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Util.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Util_DependencyInfo.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Util_DependencyInfo.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Util_Progress.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Util_Progress.txt
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Util_RegistrarBoundaries.html
spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Util_RegistrarBoundaries.txt
spamassassin/site/full/3.4.x/doc/sa-awl.html
spamassassin/site/full/3.4.x/doc/sa-awl.txt
spamassassin/site/full/3.4.x/doc/sa-compile.html
spamassassin/site/full/3.4.x/doc/sa-compile.txt
spamassassin/site/full/3.4.x/doc/sa-learn.html
spamassassin/site/full/3.4.x/doc/sa-learn.txt
spamassassin/site/full/3.4.x/doc/sa-update.html
spamassassin/site/full/3.4.x/doc/sa-update.txt
spamassassin/site/full/3.4.x/doc/spamassassin-run.html
spamassassin/site/full/3.4.x/doc/spamassassin-run.txt
spamassassin/site/full/3.4.x/doc/spamassassin.html
spamassassin/site/full/3.4.x/doc/spamassassin.txt
spamassassin/site/full/3.4.x/doc/spamc.html
spamassassin/site/full/3.4.x/doc/spamc.txt
spamassassin/site/full/3.4.x/doc/spamd.html
spamassassin/site/full/3.4.x/doc/spamd.txt
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,893 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin - Spam detector and markup engine</title>
+<link rev="made" href="mailto:root@twm2005-dev.thoughtworthy.com" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <li><a href="#prerequisites">PREREQUISITES</a></li>
+ <li><a href="#more_documentation">MORE DOCUMENTATION</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+ <li><a href="#bugs">BUGS</a></li>
+ <li><a href="#authors">AUTHORS</a></li>
+ <li><a href="#copyright">COPYRIGHT</a></li>
+ <li><a href="#availability">AVAILABILITY</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin - Spam detector and markup engine</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ my $spamtest = Mail::SpamAssassin->new();
+ my $mail = $spamtest->parse($message);
+ my $status = $spamtest->check($mail);</pre>
+<pre>
+ if ($status->is_spam()) {
+ $message = $status->rewrite_mail();
+ }
+ else {
+ ...
+ }
+ ...</pre>
+<pre>
+ $status->finish();
+ $mail->finish();
+ $spamtest->finish();</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>Mail::SpamAssassin is a module to identify spam using several methods
+including text analysis, internet-based realtime blacklists, statistical
+analysis, and internet-based hashing algorithms.</p>
+<p>Using its rule base, it uses a wide range of heuristic tests on mail
+headers and body text to identify ``spam'', also known as unsolicited bulk
+email. Once identified as spam, the mail can then be tagged as spam for
+later filtering using the user's own mail user agent application or at
+the mail transfer agent.</p>
+<p>If you wish to use a command-line filter tool, try the <code>spamassassin</code>
+or the <code>spamd</code>/<code>spamc</code> tools provided.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<dl>
+<dt><strong><a name="item_new">$t = Mail::SpamAssassin->new( { opt => val, ... } )</a></strong><br />
+</dt>
+<dd>
+Constructs a new <code>Mail::SpamAssassin</code> object. You may pass a hash
+reference to the constructor which may contain the following attribute-
+value pairs.
+</dd>
+<dl>
+<dt><strong><a name="item_debug">debug</a></strong><br />
+</dt>
+<dd>
+This is the debug options used to determine logging level. It exists to
+allow sections of debug messages (called ``facilities'') to be enabled or
+disabled. If this is a string, it is treated as a comma-delimited list
+of the debug facilities. If it's a hash reference, then the keys are
+treated as the list of debug facilities and if it's a array reference,
+then the elements are treated as the list of debug facilities.
+</dd>
+<dd>
+<p>There are also two special cases: (1) if the special case of ``info'' is
+passed as a debug facility, then all informational messages are enabled;
+(2) if the special case of ``all'' is passed as a debug facility, then all
+debugging facilities are enabled.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_rules_filename">rules_filename</a></strong><br />
+</dt>
+<dd>
+The filename/directory to load spam-identifying rules from. (optional)
+</dd>
+<p></p>
+<dt><strong><a name="item_site_rules_filename">site_rules_filename</a></strong><br />
+</dt>
+<dd>
+The filename/directory to load site-specific spam-identifying rules from.
+(optional)
+</dd>
+<p></p>
+<dt><strong><a name="item_userprefs_filename">userprefs_filename</a></strong><br />
+</dt>
+<dd>
+The filename to load preferences from. (optional)
+</dd>
+<p></p>
+<dt><strong><a name="item_userstate_dir">userstate_dir</a></strong><br />
+</dt>
+<dd>
+The directory user state is stored in. (optional)
+</dd>
+<p></p>
+<dt><strong><a name="item_config_tree_recurse">config_tree_recurse</a></strong><br />
+</dt>
+<dd>
+Set to <code>1</code> to recurse through directories when reading configuration
+files, instead of just reading a single level. (optional, default 0)
+</dd>
+<p></p>
+<dt><strong><a name="item_config_text">config_text</a></strong><br />
+</dt>
+<dd>
+The text of all rules and preferences. If you prefer not to load the rules
+from files, read them in yourself and set this instead. As a result, this will
+override the settings for <a href="#item_rules_filename"><code>rules_filename</code></a>, <a href="#item_site_rules_filename"><code>site_rules_filename</code></a>,
+and <a href="#item_userprefs_filename"><code>userprefs_filename</code></a>.
+</dd>
+<p></p>
+<dt><strong><a name="item_pre_config_text">pre_config_text</a></strong><br />
+</dt>
+<dd>
+Similar to <a href="#item_config_text"><code>config_text</code></a>, this text is placed before config_text to allow an
+override of config files.
+</dd>
+<p></p>
+<dt><strong><a name="item_post_config_text">post_config_text</a></strong><br />
+</dt>
+<dd>
+Similar to <a href="#item_config_text"><code>config_text</code></a>, this text is placed after config_text to allow an
+override of config files.
+</dd>
+<p></p>
+<dt><strong><a name="item_force_ipv4">force_ipv4</a></strong><br />
+</dt>
+<dd>
+If set to 1, DNS or other network tests will prefer IPv4 and not attempt
+to use IPv6. Use if the existing tests for IPv6 availability produce
+incorrect results or crashes.
+</dd>
+<p></p>
+<dt><strong><a name="item_force_ipv6">force_ipv6</a></strong><br />
+</dt>
+<dd>
+For symmetry with force_ipv4: if set to 1, DNS or other network tests
+will prefer IPv6 and not attempt to use IPv4. Some plugins may disregard
+this setting and use whatever protocol family they are comfortable with.
+</dd>
+<p></p>
+<dt><strong><a name="item_require_rules">require_rules</a></strong><br />
+</dt>
+<dd>
+If set to 1, <code>init()</code> will die if no valid rules could be loaded. This is the
+default behaviour when called by <code>spamassassin</code> or <code>spamd</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_languages_filename">languages_filename</a></strong><br />
+</dt>
+<dd>
+If you want to be able to use the language-guessing rule
+<code>UNWANTED_LANGUAGE_BODY</code>, and are using <a href="#item_config_text"><code>config_text</code></a> instead of
+<a href="#item_rules_filename"><code>rules_filename</code></a>, <a href="#item_site_rules_filename"><code>site_rules_filename</code></a>, and <a href="#item_userprefs_filename"><code>userprefs_filename</code></a>, you will
+need to set this. It should be the path to the <strong>languages</strong> file normally
+found in the SpamAssassin <strong>rules</strong> directory.
+</dd>
+<p></p>
+<dt><strong><a name="item_local_tests_only">local_tests_only</a></strong><br />
+</dt>
+<dd>
+If set to 1, no tests that require internet access will be performed. (default:
+0)
+</dd>
+<p></p>
+<dt><strong><a name="item_need_tags">need_tags</a></strong><br />
+</dt>
+<dd>
+The option provides a way to avoid more expensive processing when it is known
+in advance that some information will not be needed by a caller.
+</dd>
+<dd>
+<p>A value of the option can either be a string (a comma-delimited list of tag
+names), or a reference to a list of individual tag names. A caller may provide
+the list in advance, specifying his intention to later collect the information
+through $pms-><code>get_tag()</code> calls. If a name of a tag starts with a 'NO' (case
+insensitive), it shows that a caller will not be interested in such tag,
+although there is no guarantee it would save any resources, nor that a tag
+value will be empty. Currently no built-in tags start with 'NO'. A later
+entry overrides previous one, e.g. ASN,NOASN,ASN,TIMING,NOASN is equivalent
+to TIMING,NOASN.</p>
+</dd>
+<dd>
+<p>For backward compatibility, all tags available as of version 3.2.4 will
+be available by default (unless disabled by NOtag), even if not requested
+through need_tags option. Future versions may provide new tags conditionally
+available.</p>
+</dd>
+<dd>
+<p>Currently the only tag that needs to be explicitly requested is 'TIMING'.
+Not requesting it can save a millisecond or two - it mostly serves to
+illustrate the usage of need_tags.</p>
+</dd>
+<dd>
+<p>Example:
+ need_tags => 'TIMING,noLANGUAGES,RELAYCOUNTRY,ASN,noASNCIDR',
+or:
+ need_tags => [qw(TIMING noLANGUAGES RELAYCOUNTRY ASN noASNCIDR)],</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_ignore_site_cf_files">ignore_site_cf_files</a></strong><br />
+</dt>
+<dd>
+If set to 1, any rule files found in the <a href="#item_site_rules_filename"><code>site_rules_filename</code></a> directory will
+be ignored. *.pre files (used for loading plugins) found in the
+<a href="#item_site_rules_filename"><code>site_rules_filename</code></a> directory will still be used. (default: 0)
+</dd>
+<p></p>
+<dt><strong><a name="item_dont_copy_prefs">dont_copy_prefs</a></strong><br />
+</dt>
+<dd>
+If set to 1, the user preferences file will not be created if it doesn't
+already exist. (default: 0)
+</dd>
+<p></p>
+<dt><strong><a name="item_save_pattern_hits">save_pattern_hits</a></strong><br />
+</dt>
+<dd>
+If set to 1, the patterns hit can be retrieved from the
+<code>Mail::SpamAssassin::PerMsgStatus</code> object. Used for debugging.
+</dd>
+<p></p>
+<dt><strong><a name="item_home_dir_for_helpers">home_dir_for_helpers</a></strong><br />
+</dt>
+<dd>
+If set, the <strong>HOME</strong> environment variable will be set to this value
+when using test applications that require their configuration data,
+such as Razor, Pyzor and DCC.
+</dd>
+<p></p>
+<dt><strong><a name="item_username">username</a></strong><br />
+</dt>
+<dd>
+If set, the <a href="#item_username"><code>username</code></a> attribute will use this as the current user's name.
+Otherwise, the default is taken from the runtime environment (ie. this process'
+effective UID under UNIX).
+</dd>
+<p></p>
+<dt><strong><a name="item_skip_prng_reseeding">skip_prng_reseeding</a></strong><br />
+</dt>
+<dd>
+If skip_prng_reseeding is set to true, the SpamAssassin library will <strong>not</strong>
+call <code>srand()</code> to reseed a pseudo-random number generator (PRNG). The <code>srand()</code>
+Perl function should be called during initialization of each child process,
+soon after forking.
+</dd>
+<dd>
+<p>Prior to version 3.4.0, calling <code>srand()</code> was handled by the SpamAssassin
+library.</p>
+</dd>
+<dd>
+<p>This setting requires the caller to decide when to call srand().
+This choice may be desired to preserve the entropy of a PRNG. The default
+value of skip_prng_reseeding is false to maintain backward compatibility.</p>
+</dd>
+<dd>
+<p>This option should only be set by a caller if it calls <code>srand()</code> upon spawning
+child processes. Unless you are certain you need it, leave this setting as
+false.</p>
+</dd>
+<dd>
+<p>NOTE: The skip_prng_reseeding feature is implemented in spamd as of 3.4.0
+which allows spamd to call <code>srand()</code> right after forking a child process.</p>
+</dd>
+<p></p></dl>
+<p>If none of <a href="#item_rules_filename"><code>rules_filename</code></a>, <a href="#item_site_rules_filename"><code>site_rules_filename</code></a>, <a href="#item_userprefs_filename"><code>userprefs_filename</code></a>, or
+<a href="#item_config_text"><code>config_text</code></a> is set, the <code>Mail::SpamAssassin</code> module will search for the
+configuration files in the usual installed locations using the below variable
+definitions which can be passed in.</p>
+<dl>
+<dt><strong><a name="item_prefix">PREFIX</a></strong><br />
+</dt>
+<dd>
+Used as the root for certain directory paths such as:
+</dd>
+<dd>
+<pre>
+ '__prefix__/etc/mail/spamassassin'
+ '__prefix__/etc/spamassassin'</pre>
+</dd>
+<dd>
+<p>Defaults to ``@@PREFIX@@''.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_def_rules_dir">DEF_RULES_DIR</a></strong><br />
+</dt>
+<dd>
+Location where the default rules are installed. Defaults to
+``@@DEF_RULES_DIR@@''.
+</dd>
+<p></p>
+<dt><strong><a name="item_local_rules_dir">LOCAL_RULES_DIR</a></strong><br />
+</dt>
+<dd>
+Location where the local site rules are installed. Defaults to
+``@@LOCAL_RULES_DIR@@''.
+</dd>
+<p></p>
+<dt><strong><a name="item_local_state_dir">LOCAL_STATE_DIR</a></strong><br />
+</dt>
+<dd>
+Location of the local state directory, mainly used for installing updates via
+<code>sa-update</code> and compiling rulesets to native code. Defaults to
+``@@LOCAL_STATE_DIR@@''.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_parse">parse($message, $parse_now [, $suppl_attrib])</a></strong><br />
+</dt>
+<dd>
+Parse will return a Mail::SpamAssassin::Message object with just the
+headers parsed. When calling this function, there are two optional
+parameters that can be passed in: $message is either undef (which
+will use STDIN), a scalar - a string containing an entire message,
+a reference to such string, an array reference of the message with
+one line per array element, or either a file glob or an IO::File object
+which holds the entire contents of the message; and $parse_now, which
+specifies whether or not to create a MIME tree at parse time or later
+as necessary.
+</dd>
+<dd>
+<p>The <em>$parse_now</em> option, by default, is set to false (0). This
+allows SpamAssassin to not have to generate the tree of internal
+data nodes if the information is not going to be used. This is
+handy, for instance, when running <code>spamassassin -d</code>, which only
+needs the pristine header and body which is always parsed and stored
+by this function.</p>
+</dd>
+<dd>
+<p>The optional last argument <em>$suppl_attrib</em> provides a way for a caller
+to pass additional information about a message to SpamAssassin. It is
+either undef, or a ref to a hash where each key/value pair provides some
+supplementary attribute of the message, typically information that cannot
+be deduced from the message itself, or is hard to do so reliably, or would
+represent unnecessary work for SpamAssassin to obtain it. The argument will
+be stored to a Mail::SpamAssassin::Message object as 'suppl_attrib', thus
+made available to the rest of the code as well as to plugins. The exact list
+of attributes will evolve through time, any unknown attribute should be
+ignored. Possible examples are: SMTP envelope information, a flag indicating
+that a message as supplied by a caller was truncated due to size limit, an
+already verified list of DKIM signature objects, or perhaps a list of rule
+hits predetermined by a caller, which makes another possible way for a
+caller to provide meta information (instead of having to insert made-up
+header fields in order to pass information), or maybe just plain rule hits.</p>
+</dd>
+<dd>
+<p>For more information, please see the <code>Mail::SpamAssassin::Message</code>
+and <code>Mail::SpamAssassin::Message::Node</code> POD.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_check">$status = $f->check ($mail)</a></strong><br />
+</dt>
+<dd>
+Check a mail, encapsulated in a <code>Mail::SpamAssassin::Message</code> object,
+to determine if it is spam or not.
+</dd>
+<dd>
+<p>Returns a <code>Mail::SpamAssassin::PerMsgStatus</code> object which can be
+used to test or manipulate the mail message.</p>
+</dd>
+<dd>
+<p>Note that the <code>Mail::SpamAssassin</code> object can be re-used for further messages
+without affecting this check; in OO terminology, the <code>Mail::SpamAssassin</code>
+object is a ``factory''. However, if you do this, be sure to call the
+<a href="#item_finish"><code>finish()</code></a> method on the status objects when you're done with them.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_check_message_text">$status = $f->check_message_text ($mailtext)</a></strong><br />
+</dt>
+<dd>
+Check a mail, encapsulated in a plain string <code>$mailtext</code>, to determine if it
+is spam or not.
+</dd>
+<dd>
+<p>Otherwise identical to <a href="#item_check"><code>check()</code></a> above.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_learn">$status = $f->learn ($mail, $id, $isspam, $forget)</a></strong><br />
+</dt>
+<dd>
+Learn from a mail, encapsulated in a <code>Mail::SpamAssassin::Message</code> object.
+</dd>
+<dd>
+<p>If <code>$isspam</code> is set, the mail is assumed to be spam, otherwise it will
+be learnt as non-spam.</p>
+</dd>
+<dd>
+<p>If <code>$forget</code> is set, the attributes of the mail will be removed from
+both the non-spam and spam learning databases.</p>
+</dd>
+<dd>
+<p><code>$id</code> is an optional message-identification string, used internally
+to tag the message. If it is <code>undef</code>, the Message-Id of the message
+will be used. It should be unique to that message.</p>
+</dd>
+<dd>
+<p>Returns a <code>Mail::SpamAssassin::PerMsgLearner</code> object which can be used to
+manipulate the learning process for each mail.</p>
+</dd>
+<dd>
+<p>Note that the <code>Mail::SpamAssassin</code> object can be re-used for further messages
+without affecting this check; in OO terminology, the <code>Mail::SpamAssassin</code>
+object is a ``factory''. However, if you do this, be sure to call the
+<a href="#item_finish"><code>finish()</code></a> method on the learner objects when you're done with them.</p>
+</dd>
+<dd>
+<p><a href="#item_learn"><code>learn()</code></a> and <a href="#item_check"><code>check()</code></a> can be run using the same factory. <a href="#item_init_learner"><code>init_learner()</code></a>
+must be called before using this method.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_init_learner">$f->init_learner ( [ { opt => val, ... } ] )</a></strong><br />
+</dt>
+<dd>
+Initialise learning. You may pass the following attribute-value pairs to this
+method.
+</dd>
+<dl>
+<dt><strong><a name="item_caller_will_untie">caller_will_untie</a></strong><br />
+</dt>
+<dd>
+Whether or not the code calling this method will take care of untie'ing
+from the Bayes databases (by calling <a href="#item_finish_learner"><code>finish_learner()</code></a>) (optional, default 0).
+</dd>
+<p></p>
+<dt><strong><a name="item_force_expire">force_expire</a></strong><br />
+</dt>
+<dd>
+Should an expiration run be forced to occur immediately? (optional, default 0).
+</dd>
+<p></p>
+<dt><strong><a name="item_learn_to_journal">learn_to_journal</a></strong><br />
+</dt>
+<dd>
+Should learning data be written to the journal, instead of directly to the
+databases? (optional, default 0).
+</dd>
+<p></p>
+<dt><strong><a name="item_wait_for_lock">wait_for_lock</a></strong><br />
+</dt>
+<dd>
+Whether or not to wait a long time for locks to complete (optional, default 0).
+</dd>
+<p></p>
+<dt><strong><a name="item_opportunistic_expire_check_only">opportunistic_expire_check_only</a></strong><br />
+</dt>
+<dd>
+During the opportunistic journal sync and expire check, don't actually do the
+expire but report back whether or not it should occur (optional, default 0).
+</dd>
+<p></p>
+<dt><strong><a name="item_no_relearn">no_relearn</a></strong><br />
+</dt>
+<dd>
+If doing a learn operation, and the message has already been learned as
+the opposite type, don't re-learn the message.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_rebuild_learner_caches">$f->rebuild_learner_caches ({ opt => val })</a></strong><br />
+</dt>
+<dd>
+Rebuild any cache databases; should be called after the learning process.
+Options include: <code>verbose</code>, which will output diagnostics to <code>stdout</code>
+if set to 1.
+</dd>
+<p></p>
+<dt><strong><a name="item_finish_learner">$f->finish_learner ()</a></strong><br />
+</dt>
+<dd>
+Finish learning.
+</dd>
+<p></p>
+<dt><strong><a name="item_dump_bayes_db">$f-><code>dump_bayes_db()</code></a></strong><br />
+</dt>
+<dd>
+Dump the contents of the Bayes DB
+</dd>
+<p></p>
+<dt><strong><a name="item_signal_user_changed">$f->signal_user_changed ( [ { opt => val, ... } ] )</a></strong><br />
+</dt>
+<dd>
+Signals that the current user has changed (possibly using <code>setuid</code>), meaning
+that SpamAssassin should close any per-user databases it has open, and re-open
+using ones appropriate for the new user.
+</dd>
+<dd>
+<p>Note that this should be called <em>after</em> reading any per-user configuration, as
+that data may override some paths opened in this method. You may pass the
+following attribute-value pairs:</p>
+</dd>
+<dl>
+<dt><strong>username</strong><br />
+</dt>
+<dd>
+The username of the user. This will be used for the <a href="#item_username"><code>username</code></a> attribute.
+</dd>
+<p></p>
+<dt><strong><a name="item_user_dir">user_dir</a></strong><br />
+</dt>
+<dd>
+A directory to use as a 'home directory' for the current user's data,
+overriding the system default. This directory must be readable and writable by
+the process. Note that the resulting <a href="#item_userstate_dir"><code>userstate_dir</code></a> will be the
+<code>.spamassassin</code> subdirectory of this dir.
+</dd>
+<p></p>
+<dt><strong>userstate_dir</strong><br />
+</dt>
+<dd>
+A directory to use as a directory for the current user's data, overriding the
+system default. This directory must be readable and writable by the process.
+The default is <code>user_dir/.spamassassin</code>.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_report_as_spam">$f->report_as_spam ($mail, $options)</a></strong><br />
+</dt>
+<dd>
+Report a mail, encapsulated in a <code>Mail::SpamAssassin::Message</code> object, as
+human-verified spam. This will submit the mail message to live,
+collaborative, spam-blocker databases, allowing other users to block this
+message.
+</dd>
+<dd>
+<p>It will also submit the mail to SpamAssassin's Bayesian learner.</p>
+</dd>
+<dd>
+<p>Options is an optional reference to a hash of options. Currently these
+can be:</p>
+</dd>
+<dl>
+<dt><strong><a name="item_dont_report_to_dcc">dont_report_to_dcc</a></strong><br />
+</dt>
+<dd>
+Inhibits reporting of the spam to DCC.
+</dd>
+<p></p>
+<dt><strong><a name="item_dont_report_to_pyzor">dont_report_to_pyzor</a></strong><br />
+</dt>
+<dd>
+Inhibits reporting of the spam to Pyzor.
+</dd>
+<p></p>
+<dt><strong><a name="item_dont_report_to_razor">dont_report_to_razor</a></strong><br />
+</dt>
+<dd>
+Inhibits reporting of the spam to Razor.
+</dd>
+<p></p>
+<dt><strong><a name="item_dont_report_to_spamcop">dont_report_to_spamcop</a></strong><br />
+</dt>
+<dd>
+Inhibits reporting of the spam to SpamCop.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_revoke_as_spam">$f->revoke_as_spam ($mail, $options)</a></strong><br />
+</dt>
+<dd>
+Revoke a mail, encapsulated in a <code>Mail::SpamAssassin::Message</code> object, as
+human-verified ham (non-spam). This will revoke the mail message from live,
+collaborative, spam-blocker databases, allowing other users to block this
+message.
+</dd>
+<dd>
+<p>It will also submit the mail to SpamAssassin's Bayesian learner as nonspam.</p>
+</dd>
+<dd>
+<p>Options is an optional reference to a hash of options. Currently these
+can be:</p>
+</dd>
+<dl>
+<dt><strong>dont_report_to_razor</strong><br />
+</dt>
+<dd>
+Inhibits revoking of the spam to Razor.
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_add_address_to_whitelist">$f->add_address_to_whitelist ($addr, $cli_p)</a></strong><br />
+</dt>
+<dd>
+Given a string containing an email address, add it to the automatic
+whitelist database.
+</dd>
+<dd>
+<p>If $cli_p is set then underlying plugin may give visual feedback on additions/failures.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_add_all_addresses_to_whitelist">$f->add_all_addresses_to_whitelist ($mail, $cli_p)</a></strong><br />
+</dt>
+<dd>
+Given a mail message, find as many addresses in the usual headers (To, Cc, From
+etc.), and the message body, and add them to the automatic whitelist database.
+</dd>
+<dd>
+<p>If $cli_p is set then underlying plugin may give visual feedback on additions/failures.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_remove_address_from_whitelist">$f->remove_address_from_whitelist ($addr, $cli_p)</a></strong><br />
+</dt>
+<dd>
+Given a string containing an email address, remove it from the automatic
+whitelist database.
+</dd>
+<dd>
+<p>If $cli_p is set then underlying plugin may give visual feedback on additions/failures.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_remove_all_addresses_from_whitelist">$f->remove_all_addresses_from_whitelist ($mail, $cli_p)</a></strong><br />
+</dt>
+<dd>
+Given a mail message, find as many addresses in the usual headers (To, Cc, From
+etc.), and the message body, and remove them from the automatic whitelist
+database.
+</dd>
+<dd>
+<p>If $cli_p is set then underlying plugin may give visual feedback on additions/failures.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_add_address_to_blacklist">$f->add_address_to_blacklist ($addr, $cli_p)</a></strong><br />
+</dt>
+<dd>
+Given a string containing an email address, add it to the automatic
+whitelist database with a high score, effectively blacklisting them.
+</dd>
+<dd>
+<p>If $cli_p is set then underlying plugin may give visual feedback on additions/failures.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_add_all_addresses_to_blacklist">$f->add_all_addresses_to_blacklist ($mail, $cli_p)</a></strong><br />
+</dt>
+<dd>
+Given a mail message, find addresses in the From headers and add them to the
+automatic whitelist database with a high score, effectively blacklisting them.
+</dd>
+<dd>
+<p>Note that To and Cc addresses are not used.</p>
+</dd>
+<dd>
+<p>If $cli_p is set then underlying plugin may give visual feedback on additions/failures.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_remove_spamassassin_markup">$text = $f->remove_spamassassin_markup ($mail)</a></strong><br />
+</dt>
+<dd>
+Returns the text of the message, with any SpamAssassin-added text (such
+as the report, or X-Spam-Status headers) stripped.
+</dd>
+<dd>
+<p>Note that the <strong>$mail</strong> object is not modified.</p>
+</dd>
+<dd>
+<p>Warning: if the input message in <strong>$mail</strong> contains a mixture of CR-LF
+(Windows-style) and LF (UNIX-style) line endings, it will be ``canonicalized''
+to use one or the other consistently throughout.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_read_scoreonly_config">$f->read_scoreonly_config ($filename)</a></strong><br />
+</dt>
+<dd>
+Read a configuration file and parse user preferences from it.
+</dd>
+<dd>
+<p>User preferences are as defined in the <code>Mail::SpamAssassin::Conf</code> manual page.
+In other words, they include scoring options, scores, whitelists and
+blacklists, and so on, but do not include rule definitions, privileged
+settings, etc. unless <code>allow_user_rules</code> is enabled; and they never include
+the administrator settings.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_load_scoreonly_sql">$f->load_scoreonly_sql ($username)</a></strong><br />
+</dt>
+<dd>
+Read configuration paramaters from SQL database and parse scores from it. This
+will only take effect if the perl <code>DBI</code> module is installed, and the
+configuration parameters <code>user_scores_dsn</code>, <code>user_scores_sql_username</code>, and
+<code>user_scores_sql_password</code> are set correctly.
+</dd>
+<dd>
+<p>The username in <code>$username</code> will also be used for the <a href="#item_username"><code>username</code></a> attribute of
+the Mail::SpamAssassin object.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_load_scoreonly_ldap">$f->load_scoreonly_ldap ($username)</a></strong><br />
+</dt>
+<dd>
+Read configuration paramaters from an LDAP server and parse scores from it.
+This will only take effect if the perl <code>Net::LDAP</code> and <code>URI</code> modules are
+installed, and the configuration parameters <code>user_scores_dsn</code>,
+<code>user_scores_ldap_username</code>, and <code>user_scores_ldap_password</code> are set
+correctly.
+</dd>
+<dd>
+<p>The username in <code>$username</code> will also be used for the <a href="#item_username"><code>username</code></a> attribute of
+the Mail::SpamAssassin object.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_set_persistent_address_list_factory">$f->set_persistent_address_list_factory ($factoryobj)</a></strong><br />
+</dt>
+<dd>
+Set the persistent address list factory, used to create objects for the
+automatic whitelist algorithm's persistent-storage back-end. See
+<code>Mail::SpamAssassin::PersistentAddrList</code> for the API these factory objects
+must implement, and the API the objects they produce must implement.
+</dd>
+<p></p>
+<dt><strong><a name="item_compile_now">$f->compile_now ($use_user_prefs, $keep_userstate)</a></strong><br />
+</dt>
+<dd>
+Compile all patterns, load all configuration files, and load all
+possibly-required Perl modules.
+</dd>
+<dd>
+<p>Normally, Mail::SpamAssassin uses lazy evaluation where possible, but if you
+plan to <code>fork()</code> or start a new perl interpreter thread to process a message,
+this is suboptimal, as each process/thread will have to perform these actions.</p>
+</dd>
+<dd>
+<p>Call this function in the master thread or process to perform the actions
+straightaway, so that the sub-processes will not have to.</p>
+</dd>
+<dd>
+<p>If <code>$use_user_prefs</code> is 0, this will initialise the SpamAssassin
+configuration without reading the per-user configuration file and it will
+assume that you will call <a href="#item_read_scoreonly_config"><code>read_scoreonly_config</code></a> at a later point.</p>
+</dd>
+<dd>
+<p>If <code>$keep_userstate</code> is true, <a href="#item_compile_now"><code>compile_now()</code></a> will revert any configuration
+options which have a default with <em>__userstate__</em> in it post-init(),
+and then re-change the option before returning. This lets you change
+<em>$ENV{'HOME'}</em> to a temp directory, have <a href="#item_compile_now"><code>compile_now()</code></a> and create any
+files there as necessary without disturbing the actual files as changed
+by a configuration option. By default, this is disabled.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_debug_diagnostics">$f->debug_diagnostics ()</a></strong><br />
+</dt>
+<dd>
+Output some diagnostic information, useful for debugging SpamAssassin
+problems.
+</dd>
+<p></p>
+<dt><strong><a name="item_lint_rules">$failed = $f->lint_rules ()</a></strong><br />
+</dt>
+<dd>
+Syntax-check the current set of rules. Returns the number of
+syntax errors discovered, or 0 if the configuration is valid.
+</dd>
+<p></p>
+<dt><strong><a name="item_finish">$f-><code>finish()</code></a></strong><br />
+</dt>
+<dd>
+Destroy this object, so that it will be garbage-collected once it
+goes out of scope. The object will no longer be usable after this
+method is called.
+</dd>
+<p></p>
+<dt><strong><a name="item_find_rule_support_file">$fullpath = $f->find_rule_support_file ($filename)</a></strong><br />
+</dt>
+<dd>
+Find a rule-support file, such as <code>languages</code> or <code>triplets.txt</code>,
+in the system-wide rules directory, and return its full path if
+it exists, or undef if it doesn't exist.
+</dd>
+<dd>
+<p>(This API was added in SpamAssassin 3.1.1.)</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_create_default_prefs">$f->create_default_prefs ($filename, $username [ , $userdir ] )</a></strong><br />
+</dt>
+<dd>
+Copy default preferences file into home directory for later use and
+modification, if it does not already exist and <a href="#item_dont_copy_prefs"><code>dont_copy_prefs</code></a> is
+not set.
+</dd>
+<p></p>
+<dt><strong><a name="item_copy_config">$f->copy_config ( [ $source ], [ $dest ] )</a></strong><br />
+</dt>
+<dd>
+Used for daemons to keep a persistent Mail::SpamAssassin object's
+configuration correct if switching between users. Pass an associative
+array reference as either $source or $dest, and set the other to 'undef'
+so that the object will use its current configuration. i.e.:
+</dd>
+<dd>
+<pre>
+ # create object w/ configuration
+ my $spamtest = Mail::SpamAssassin->new( ... );</pre>
+</dd>
+<dd>
+<pre>
+ # backup configuration to %conf_backup
+ my %conf_backup;
+ $spamtest->copy_config(undef, \%conf_backup) ||
+ die "config: error returned from copy_config!\n";</pre>
+</dd>
+<dd>
+<pre>
+ ... do stuff, perhaps modify the config, etc ...</pre>
+</dd>
+<dd>
+<pre>
+ # reset the configuration back to the original
+ $spamtest->copy_config(\%conf_backup, undef) ||
+ die "config: error returned from copy_config!\n";</pre>
+</dd>
+<dd>
+<p>Note that the contents of the associative arrays should be considered
+opaque by calling code.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_loaded_plugins_list">@plugins = $f->get_loaded_plugins_list ( )</a></strong><br />
+</dt>
+<dd>
+Return the list of plugins currently loaded by this SpamAssassin object's
+configuration; each entry in the list is an object of type
+<code>Mail::SpamAssassin::Plugin</code>.
+</dd>
+<dd>
+<p>(This API was added in SpamAssassin 3.2.0.)</p>
+</dd>
+<p></p></dl>
+<p>
+</p>
+<hr />
+<h1><a name="prerequisites">PREREQUISITES</a></h1>
+<p><code>HTML::Parser</code>
+<code>Sys::Syslog</code></p>
+<p>
+</p>
+<hr />
+<h1><a name="more_documentation">MORE DOCUMENTATION</a></h1>
+<p>See also <<a href="http://spamassassin.apache.org/">http://spamassassin.apache.org/</a>> and
+<<a href="http://wiki.apache.org/spamassassin/">http://wiki.apache.org/spamassassin/</a>> for more information.</p>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p>Mail::SpamAssassin::Conf(3)
+Mail::SpamAssassin::PerMsgStatus(3)
+<code>spamassassin(1)</code>
+sa-update(1)</p>
+<p>
+</p>
+<hr />
+<h1><a name="bugs">BUGS</a></h1>
+<p>See <<a href="http://issues.apache.org/SpamAssassin/">http://issues.apache.org/SpamAssassin/</a>></p>
+<p>
+</p>
+<hr />
+<h1><a name="authors">AUTHORS</a></h1>
+<p>The <code>SpamAssassin(tm)</code> Project <<a href="http://spamassassin.apache.org/">http://spamassassin.apache.org/</a>></p>
+<p>
+</p>
+<hr />
+<h1><a name="copyright">COPYRIGHT</a></h1>
+<p>SpamAssassin is distributed under the Apache License, Version 2.0, as
+described in the file <code>LICENSE</code> included with the distribution.</p>
+<p>
+</p>
+<hr />
+<h1><a name="availability">AVAILABILITY</a></h1>
+<p>The latest version of this library is likely to be available from CPAN
+as well as:</p>
+<pre>
+ E<lt><a href="http://spamassassin.apache.org/E<gt>">http://spamassassin.apache.org/E<gt></a>;</pre>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,609 @@
+NAME
+ Mail::SpamAssassin - Spam detector and markup engine
+
+SYNOPSIS
+ my $spamtest = Mail::SpamAssassin->new();
+ my $mail = $spamtest->parse($message);
+ my $status = $spamtest->check($mail);
+
+ if ($status->is_spam()) {
+ $message = $status->rewrite_mail();
+ }
+ else {
+ ...
+ }
+ ...
+
+ $status->finish();
+ $mail->finish();
+ $spamtest->finish();
+
+DESCRIPTION
+ Mail::SpamAssassin is a module to identify spam using several methods
+ including text analysis, internet-based realtime blacklists, statistical
+ analysis, and internet-based hashing algorithms.
+
+ Using its rule base, it uses a wide range of heuristic tests on mail
+ headers and body text to identify "spam", also known as unsolicited bulk
+ email. Once identified as spam, the mail can then be tagged as spam for
+ later filtering using the user's own mail user agent application or at
+ the mail transfer agent.
+
+ If you wish to use a command-line filter tool, try the "spamassassin" or
+ the "spamd"/"spamc" tools provided.
+
+METHODS
+ $t = Mail::SpamAssassin->new( { opt => val, ... } )
+ Constructs a new "Mail::SpamAssassin" object. You may pass a hash
+ reference to the constructor which may contain the following
+ attribute- value pairs.
+
+ debug
+ This is the debug options used to determine logging level. It
+ exists to allow sections of debug messages (called "facilities")
+ to be enabled or disabled. If this is a string, it is treated as
+ a comma-delimited list of the debug facilities. If it's a hash
+ reference, then the keys are treated as the list of debug
+ facilities and if it's a array reference, then the elements are
+ treated as the list of debug facilities.
+
+ There are also two special cases: (1) if the special case of
+ "info" is passed as a debug facility, then all informational
+ messages are enabled; (2) if the special case of "all" is passed
+ as a debug facility, then all debugging facilities are enabled.
+
+ rules_filename
+ The filename/directory to load spam-identifying rules from.
+ (optional)
+
+ site_rules_filename
+ The filename/directory to load site-specific spam-identifying
+ rules from. (optional)
+
+ userprefs_filename
+ The filename to load preferences from. (optional)
+
+ userstate_dir
+ The directory user state is stored in. (optional)
+
+ config_tree_recurse
+ Set to 1 to recurse through directories when reading
+ configuration files, instead of just reading a single level.
+ (optional, default 0)
+
+ config_text
+ The text of all rules and preferences. If you prefer not to load
+ the rules from files, read them in yourself and set this
+ instead. As a result, this will override the settings for
+ "rules_filename", "site_rules_filename", and
+ "userprefs_filename".
+
+ pre_config_text
+ Similar to "config_text", this text is placed before config_text
+ to allow an override of config files.
+
+ post_config_text
+ Similar to "config_text", this text is placed after config_text
+ to allow an override of config files.
+
+ force_ipv4
+ If set to 1, DNS or other network tests will prefer IPv4 and not
+ attempt to use IPv6. Use if the existing tests for IPv6
+ availability produce incorrect results or crashes.
+
+ force_ipv6
+ For symmetry with force_ipv4: if set to 1, DNS or other network
+ tests will prefer IPv6 and not attempt to use IPv4. Some plugins
+ may disregard this setting and use whatever protocol family they
+ are comfortable with.
+
+ require_rules
+ If set to 1, init() will die if no valid rules could be loaded.
+ This is the default behaviour when called by "spamassassin" or
+ "spamd".
+
+ languages_filename
+ If you want to be able to use the language-guessing rule
+ "UNWANTED_LANGUAGE_BODY", and are using "config_text" instead of
+ "rules_filename", "site_rules_filename", and
+ "userprefs_filename", you will need to set this. It should be
+ the path to the languages file normally found in the
+ SpamAssassin rules directory.
+
+ local_tests_only
+ If set to 1, no tests that require internet access will be
+ performed. (default: 0)
+
+ need_tags
+ The option provides a way to avoid more expensive processing
+ when it is known in advance that some information will not be
+ needed by a caller.
+
+ A value of the option can either be a string (a comma-delimited
+ list of tag names), or a reference to a list of individual tag
+ names. A caller may provide the list in advance, specifying his
+ intention to later collect the information through
+ $pms->get_tag() calls. If a name of a tag starts with a 'NO'
+ (case insensitive), it shows that a caller will not be
+ interested in such tag, although there is no guarantee it would
+ save any resources, nor that a tag value will be empty.
+ Currently no built-in tags start with 'NO'. A later entry
+ overrides previous one, e.g. ASN,NOASN,ASN,TIMING,NOASN is
+ equivalent to TIMING,NOASN.
+
+ For backward compatibility, all tags available as of version
+ 3.2.4 will be available by default (unless disabled by NOtag),
+ even if not requested through need_tags option. Future versions
+ may provide new tags conditionally available.
+
+ Currently the only tag that needs to be explicitly requested is
+ 'TIMING'. Not requesting it can save a millisecond or two - it
+ mostly serves to illustrate the usage of need_tags.
+
+ Example: need_tags =>
+ 'TIMING,noLANGUAGES,RELAYCOUNTRY,ASN,noASNCIDR', or: need_tags
+ => [qw(TIMING noLANGUAGES RELAYCOUNTRY ASN noASNCIDR)],
+
+ ignore_site_cf_files
+ If set to 1, any rule files found in the "site_rules_filename"
+ directory will be ignored. *.pre files (used for loading
+ plugins) found in the "site_rules_filename" directory will still
+ be used. (default: 0)
+
+ dont_copy_prefs
+ If set to 1, the user preferences file will not be created if it
+ doesn't already exist. (default: 0)
+
+ save_pattern_hits
+ If set to 1, the patterns hit can be retrieved from the
+ "Mail::SpamAssassin::PerMsgStatus" object. Used for debugging.
+
+ home_dir_for_helpers
+ If set, the HOME environment variable will be set to this value
+ when using test applications that require their configuration
+ data, such as Razor, Pyzor and DCC.
+
+ username
+ If set, the "username" attribute will use this as the current
+ user's name. Otherwise, the default is taken from the runtime
+ environment (ie. this process' effective UID under UNIX).
+
+ skip_prng_reseeding
+ If skip_prng_reseeding is set to true, the SpamAssassin library
+ will not call srand() to reseed a pseudo-random number generator
+ (PRNG). The srand() Perl function should be called during
+ initialization of each child process, soon after forking.
+
+ Prior to version 3.4.0, calling srand() was handled by the
+ SpamAssassin library.
+
+ This setting requires the caller to decide when to call srand().
+ This choice may be desired to preserve the entropy of a PRNG.
+ The default value of skip_prng_reseeding is false to maintain
+ backward compatibility.
+
+ This option should only be set by a caller if it calls srand()
+ upon spawning child processes. Unless you are certain you need
+ it, leave this setting as false.
+
+ NOTE: The skip_prng_reseeding feature is implemented in spamd as
+ of 3.4.0 which allows spamd to call srand() right after forking
+ a child process.
+
+ If none of "rules_filename", "site_rules_filename",
+ "userprefs_filename", or "config_text" is set, the
+ "Mail::SpamAssassin" module will search for the configuration files
+ in the usual installed locations using the below variable
+ definitions which can be passed in.
+
+ PREFIX
+ Used as the root for certain directory paths such as:
+
+ '__prefix__/etc/mail/spamassassin'
+ '__prefix__/etc/spamassassin'
+
+ Defaults to "@@PREFIX@@".
+
+ DEF_RULES_DIR
+ Location where the default rules are installed. Defaults to
+ "@@DEF_RULES_DIR@@".
+
+ LOCAL_RULES_DIR
+ Location where the local site rules are installed. Defaults to
+ "@@LOCAL_RULES_DIR@@".
+
+ LOCAL_STATE_DIR
+ Location of the local state directory, mainly used for
+ installing updates via "sa-update" and compiling rulesets to
+ native code. Defaults to "@@LOCAL_STATE_DIR@@".
+
+ parse($message, $parse_now [, $suppl_attrib])
+ Parse will return a Mail::SpamAssassin::Message object with just the
+ headers parsed. When calling this function, there are two optional
+ parameters that can be passed in: $message is either undef (which
+ will use STDIN), a scalar - a string containing an entire message, a
+ reference to such string, an array reference of the message with one
+ line per array element, or either a file glob or an IO::File object
+ which holds the entire contents of the message; and $parse_now,
+ which specifies whether or not to create a MIME tree at parse time
+ or later as necessary.
+
+ The *$parse_now* option, by default, is set to false (0). This
+ allows SpamAssassin to not have to generate the tree of internal
+ data nodes if the information is not going to be used. This is
+ handy, for instance, when running "spamassassin -d", which only
+ needs the pristine header and body which is always parsed and stored
+ by this function.
+
+ The optional last argument *$suppl_attrib* provides a way for a
+ caller to pass additional information about a message to
+ SpamAssassin. It is either undef, or a ref to a hash where each
+ key/value pair provides some supplementary attribute of the message,
+ typically information that cannot be deduced from the message
+ itself, or is hard to do so reliably, or would represent unnecessary
+ work for SpamAssassin to obtain it. The argument will be stored to a
+ Mail::SpamAssassin::Message object as 'suppl_attrib', thus made
+ available to the rest of the code as well as to plugins. The exact
+ list of attributes will evolve through time, any unknown attribute
+ should be ignored. Possible examples are: SMTP envelope information,
+ a flag indicating that a message as supplied by a caller was
+ truncated due to size limit, an already verified list of DKIM
+ signature objects, or perhaps a list of rule hits predetermined by a
+ caller, which makes another possible way for a caller to provide
+ meta information (instead of having to insert made-up header fields
+ in order to pass information), or maybe just plain rule hits.
+
+ For more information, please see the "Mail::SpamAssassin::Message"
+ and "Mail::SpamAssassin::Message::Node" POD.
+
+ $status = $f->check ($mail)
+ Check a mail, encapsulated in a "Mail::SpamAssassin::Message"
+ object, to determine if it is spam or not.
+
+ Returns a "Mail::SpamAssassin::PerMsgStatus" object which can be
+ used to test or manipulate the mail message.
+
+ Note that the "Mail::SpamAssassin" object can be re-used for further
+ messages without affecting this check; in OO terminology, the
+ "Mail::SpamAssassin" object is a "factory". However, if you do this,
+ be sure to call the "finish()" method on the status objects when
+ you're done with them.
+
+ $status = $f->check_message_text ($mailtext)
+ Check a mail, encapsulated in a plain string $mailtext, to determine
+ if it is spam or not.
+
+ Otherwise identical to "check()" above.
+
+ $status = $f->learn ($mail, $id, $isspam, $forget)
+ Learn from a mail, encapsulated in a "Mail::SpamAssassin::Message"
+ object.
+
+ If $isspam is set, the mail is assumed to be spam, otherwise it will
+ be learnt as non-spam.
+
+ If $forget is set, the attributes of the mail will be removed from
+ both the non-spam and spam learning databases.
+
+ $id is an optional message-identification string, used internally to
+ tag the message. If it is "undef", the Message-Id of the message
+ will be used. It should be unique to that message.
+
+ Returns a "Mail::SpamAssassin::PerMsgLearner" object which can be
+ used to manipulate the learning process for each mail.
+
+ Note that the "Mail::SpamAssassin" object can be re-used for further
+ messages without affecting this check; in OO terminology, the
+ "Mail::SpamAssassin" object is a "factory". However, if you do this,
+ be sure to call the "finish()" method on the learner objects when
+ you're done with them.
+
+ "learn()" and "check()" can be run using the same factory.
+ "init_learner()" must be called before using this method.
+
+ $f->init_learner ( [ { opt => val, ... } ] )
+ Initialise learning. You may pass the following attribute-value
+ pairs to this method.
+
+ caller_will_untie
+ Whether or not the code calling this method will take care of
+ untie'ing from the Bayes databases (by calling
+ "finish_learner()") (optional, default 0).
+
+ force_expire
+ Should an expiration run be forced to occur immediately?
+ (optional, default 0).
+
+ learn_to_journal
+ Should learning data be written to the journal, instead of
+ directly to the databases? (optional, default 0).
+
+ wait_for_lock
+ Whether or not to wait a long time for locks to complete
+ (optional, default 0).
+
+ opportunistic_expire_check_only
+ During the opportunistic journal sync and expire check, don't
+ actually do the expire but report back whether or not it should
+ occur (optional, default 0).
+
+ no_relearn
+ If doing a learn operation, and the message has already been
+ learned as the opposite type, don't re-learn the message.
+
+ $f->rebuild_learner_caches ({ opt => val })
+ Rebuild any cache databases; should be called after the learning
+ process. Options include: "verbose", which will output diagnostics
+ to "stdout" if set to 1.
+
+ $f->finish_learner ()
+ Finish learning.
+
+ $f->dump_bayes_db()
+ Dump the contents of the Bayes DB
+
+ $f->signal_user_changed ( [ { opt => val, ... } ] )
+ Signals that the current user has changed (possibly using "setuid"),
+ meaning that SpamAssassin should close any per-user databases it has
+ open, and re-open using ones appropriate for the new user.
+
+ Note that this should be called *after* reading any per-user
+ configuration, as that data may override some paths opened in this
+ method. You may pass the following attribute-value pairs:
+
+ username
+ The username of the user. This will be used for the "username"
+ attribute.
+
+ user_dir
+ A directory to use as a 'home directory' for the current user's
+ data, overriding the system default. This directory must be
+ readable and writable by the process. Note that the resulting
+ "userstate_dir" will be the ".spamassassin" subdirectory of this
+ dir.
+
+ userstate_dir
+ A directory to use as a directory for the current user's data,
+ overriding the system default. This directory must be readable
+ and writable by the process. The default is
+ "user_dir/.spamassassin".
+
+ $f->report_as_spam ($mail, $options)
+ Report a mail, encapsulated in a "Mail::SpamAssassin::Message"
+ object, as human-verified spam. This will submit the mail message to
+ live, collaborative, spam-blocker databases, allowing other users to
+ block this message.
+
+ It will also submit the mail to SpamAssassin's Bayesian learner.
+
+ Options is an optional reference to a hash of options. Currently
+ these can be:
+
+ dont_report_to_dcc
+ Inhibits reporting of the spam to DCC.
+
+ dont_report_to_pyzor
+ Inhibits reporting of the spam to Pyzor.
+
+ dont_report_to_razor
+ Inhibits reporting of the spam to Razor.
+
+ dont_report_to_spamcop
+ Inhibits reporting of the spam to SpamCop.
+
+ $f->revoke_as_spam ($mail, $options)
+ Revoke a mail, encapsulated in a "Mail::SpamAssassin::Message"
+ object, as human-verified ham (non-spam). This will revoke the mail
+ message from live, collaborative, spam-blocker databases, allowing
+ other users to block this message.
+
+ It will also submit the mail to SpamAssassin's Bayesian learner as
+ nonspam.
+
+ Options is an optional reference to a hash of options. Currently
+ these can be:
+
+ dont_report_to_razor
+ Inhibits revoking of the spam to Razor.
+
+ $f->add_address_to_whitelist ($addr, $cli_p)
+ Given a string containing an email address, add it to the automatic
+ whitelist database.
+
+ If $cli_p is set then underlying plugin may give visual feedback on
+ additions/failures.
+
+ $f->add_all_addresses_to_whitelist ($mail, $cli_p)
+ Given a mail message, find as many addresses in the usual headers
+ (To, Cc, From etc.), and the message body, and add them to the
+ automatic whitelist database.
+
+ If $cli_p is set then underlying plugin may give visual feedback on
+ additions/failures.
+
+ $f->remove_address_from_whitelist ($addr, $cli_p)
+ Given a string containing an email address, remove it from the
+ automatic whitelist database.
+
+ If $cli_p is set then underlying plugin may give visual feedback on
+ additions/failures.
+
+ $f->remove_all_addresses_from_whitelist ($mail, $cli_p)
+ Given a mail message, find as many addresses in the usual headers
+ (To, Cc, From etc.), and the message body, and remove them from the
+ automatic whitelist database.
+
+ If $cli_p is set then underlying plugin may give visual feedback on
+ additions/failures.
+
+ $f->add_address_to_blacklist ($addr, $cli_p)
+ Given a string containing an email address, add it to the automatic
+ whitelist database with a high score, effectively blacklisting them.
+
+ If $cli_p is set then underlying plugin may give visual feedback on
+ additions/failures.
+
+ $f->add_all_addresses_to_blacklist ($mail, $cli_p)
+ Given a mail message, find addresses in the From headers and add
+ them to the automatic whitelist database with a high score,
+ effectively blacklisting them.
+
+ Note that To and Cc addresses are not used.
+
+ If $cli_p is set then underlying plugin may give visual feedback on
+ additions/failures.
+
+ $text = $f->remove_spamassassin_markup ($mail)
+ Returns the text of the message, with any SpamAssassin-added text
+ (such as the report, or X-Spam-Status headers) stripped.
+
+ Note that the $mail object is not modified.
+
+ Warning: if the input message in $mail contains a mixture of CR-LF
+ (Windows-style) and LF (UNIX-style) line endings, it will be
+ "canonicalized" to use one or the other consistently throughout.
+
+ $f->read_scoreonly_config ($filename)
+ Read a configuration file and parse user preferences from it.
+
+ User preferences are as defined in the "Mail::SpamAssassin::Conf"
+ manual page. In other words, they include scoring options, scores,
+ whitelists and blacklists, and so on, but do not include rule
+ definitions, privileged settings, etc. unless "allow_user_rules" is
+ enabled; and they never include the administrator settings.
+
+ $f->load_scoreonly_sql ($username)
+ Read configuration paramaters from SQL database and parse scores
+ from it. This will only take effect if the perl "DBI" module is
+ installed, and the configuration parameters "user_scores_dsn",
+ "user_scores_sql_username", and "user_scores_sql_password" are set
+ correctly.
+
+ The username in $username will also be used for the "username"
+ attribute of the Mail::SpamAssassin object.
+
+ $f->load_scoreonly_ldap ($username)
+ Read configuration paramaters from an LDAP server and parse scores
+ from it. This will only take effect if the perl "Net::LDAP" and
+ "URI" modules are installed, and the configuration parameters
+ "user_scores_dsn", "user_scores_ldap_username", and
+ "user_scores_ldap_password" are set correctly.
+
+ The username in $username will also be used for the "username"
+ attribute of the Mail::SpamAssassin object.
+
+ $f->set_persistent_address_list_factory ($factoryobj)
+ Set the persistent address list factory, used to create objects for
+ the automatic whitelist algorithm's persistent-storage back-end. See
+ "Mail::SpamAssassin::PersistentAddrList" for the API these factory
+ objects must implement, and the API the objects they produce must
+ implement.
+
+ $f->compile_now ($use_user_prefs, $keep_userstate)
+ Compile all patterns, load all configuration files, and load all
+ possibly-required Perl modules.
+
+ Normally, Mail::SpamAssassin uses lazy evaluation where possible,
+ but if you plan to fork() or start a new perl interpreter thread to
+ process a message, this is suboptimal, as each process/thread will
+ have to perform these actions.
+
+ Call this function in the master thread or process to perform the
+ actions straightaway, so that the sub-processes will not have to.
+
+ If $use_user_prefs is 0, this will initialise the SpamAssassin
+ configuration without reading the per-user configuration file and it
+ will assume that you will call "read_scoreonly_config" at a later
+ point.
+
+ If $keep_userstate is true, compile_now() will revert any
+ configuration options which have a default with *__userstate__* in
+ it post-init(), and then re-change the option before returning. This
+ lets you change *$ENV{'HOME'}* to a temp directory, have
+ compile_now() and create any files there as necessary without
+ disturbing the actual files as changed by a configuration option. By
+ default, this is disabled.
+
+ $f->debug_diagnostics ()
+ Output some diagnostic information, useful for debugging
+ SpamAssassin problems.
+
+ $failed = $f->lint_rules ()
+ Syntax-check the current set of rules. Returns the number of syntax
+ errors discovered, or 0 if the configuration is valid.
+
+ $f->finish()
+ Destroy this object, so that it will be garbage-collected once it
+ goes out of scope. The object will no longer be usable after this
+ method is called.
+
+ $fullpath = $f->find_rule_support_file ($filename)
+ Find a rule-support file, such as "languages" or "triplets.txt", in
+ the system-wide rules directory, and return its full path if it
+ exists, or undef if it doesn't exist.
+
+ (This API was added in SpamAssassin 3.1.1.)
+
+ $f->create_default_prefs ($filename, $username [ , $userdir ] )
+ Copy default preferences file into home directory for later use and
+ modification, if it does not already exist and "dont_copy_prefs" is
+ not set.
+
+ $f->copy_config ( [ $source ], [ $dest ] )
+ Used for daemons to keep a persistent Mail::SpamAssassin object's
+ configuration correct if switching between users. Pass an
+ associative array reference as either $source or $dest, and set the
+ other to 'undef' so that the object will use its current
+ configuration. i.e.:
+
+ # create object w/ configuration
+ my $spamtest = Mail::SpamAssassin->new( ... );
+
+ # backup configuration to %conf_backup
+ my %conf_backup;
+ $spamtest->copy_config(undef, \%conf_backup) ||
+ die "config: error returned from copy_config!\n";
+
+ ... do stuff, perhaps modify the config, etc ...
+
+ # reset the configuration back to the original
+ $spamtest->copy_config(\%conf_backup, undef) ||
+ die "config: error returned from copy_config!\n";
+
+ Note that the contents of the associative arrays should be
+ considered opaque by calling code.
+
+ @plugins = $f->get_loaded_plugins_list ( )
+ Return the list of plugins currently loaded by this SpamAssassin
+ object's configuration; each entry in the list is an object of type
+ "Mail::SpamAssassin::Plugin".
+
+ (This API was added in SpamAssassin 3.2.0.)
+
+PREREQUISITES
+ "HTML::Parser" "Sys::Syslog"
+
+MORE DOCUMENTATION
+ See also <http://spamassassin.apache.org/> and
+ <http://wiki.apache.org/spamassassin/> for more information.
+
+SEE ALSO
+ Mail::SpamAssassin::Conf(3) Mail::SpamAssassin::PerMsgStatus(3)
+ spamassassin(1) sa-update(1)
+
+BUGS
+ See <http://issues.apache.org/SpamAssassin/>
+
+AUTHORS
+ The SpamAssassin(tm) Project <http://spamassassin.apache.org/>
+
+COPYRIGHT
+ SpamAssassin is distributed under the Apache License, Version 2.0, as
+ described in the file "LICENSE" included with the distribution.
+
+AVAILABILITY
+ The latest version of this library is likely to be available from CPAN
+ as well as:
+
+ E<lt>http://spamassassin.apache.org/E<gt>
+
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AICache.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AICache.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AICache.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AICache.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,53 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::AICache - provide access to cached information for
+ArchiveIterator</title>
+<link rev="made" href="mailto:root@twm2005-dev.thoughtworthy.com" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#public_methods">PUBLIC METHODS</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::AICache - provide access to cached information for
+ArchiveIterator</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This module allows ArchiveIterator to use cached atime information instead of
+having to read every message separately.</p>
+<p>
+</p>
+<hr />
+<h1><a name="public_methods">PUBLIC METHODS</a></h1>
+<dl>
+<dt><strong><a name="item_new"><code>new()</code></a></strong><br />
+</dt>
+<dd>
+Generates a new cache object.
+</dd>
+<p></p></dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AICache.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AICache.txt?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AICache.txt (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_AICache.txt Tue Feb 11 17:26:49 2014
@@ -0,0 +1,13 @@
+NAME
+ Mail::SpamAssassin::AICache - provide access to cached information for
+ ArchiveIterator
+
+SYNOPSIS
+DESCRIPTION
+ This module allows ArchiveIterator to use cached atime information
+ instead of having to read every message separately.
+
+PUBLIC METHODS
+ new()
+ Generates a new cache object.
+
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_ArchiveIterator.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_ArchiveIterator.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_ArchiveIterator.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_ArchiveIterator.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,281 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::ArchiveIterator - find and process messages one at a time</title>
+<link rev="made" href="mailto:root@twm2005-dev.thoughtworthy.com" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::ArchiveIterator - find and process messages one at a time</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ my $iter = new Mail::SpamAssassin::ArchiveIterator(
+ {
+ 'opt_max_size' => 256 * 1024, # 0 implies no limit
+ 'opt_cache' => 1,
+ }
+ );</pre>
+<pre>
+ $iter->set_functions( \&wanted, sub { } );</pre>
+<pre>
+ eval { $iter->run(@ARGV); };</pre>
+<pre>
+ sub wanted {
+ my($class, $filename, $recv_date, $msg_array) = @_;</pre>
+<pre>
+ ...
+ }</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>The Mail::SpamAssassin::ArchiveIterator module will go through a set
+of mbox files, mbx files, and directories (with a single message per
+file) and generate a list of messages. It will then call the <a href="#item_wanted_sub"><code>wanted_sub</code></a>
+and <a href="#item_result_sub"><code>result_sub</code></a> functions appropriately per message.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<dl>
+<dt><strong><a name="item_archiveiterator">$item = new Mail::SpamAssassin::ArchiveIterator( [ { opt => val, ... } ] )</a></strong><br />
+</dt>
+<dd>
+Constructs a new <code>Mail::SpamAssassin::ArchiveIterator</code> object. You may
+pass the following attribute-value pairs to the constructor. The pairs are
+optional unless otherwise noted.
+</dd>
+<dl>
+<dt><strong><a name="item_opt_max_size">opt_max_size</a></strong><br />
+</dt>
+<dd>
+A value of option <em>opt_max_size</em> determines a limit (number of bytes)
+beyond which a message is considered large and is skipped by ArchiveIterator.
+</dd>
+<dd>
+<p>A value 0 implies no size limit, all messages are examined. An undefined
+value implies a default limit of 256 KiB.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_opt_all">opt_all</a></strong><br />
+</dt>
+<dd>
+Setting this option to true implicitly sets <em>opt_max_size</em> to 0, i.e.
+no limit of a message size, all messages are processes by ArchiveIterator.
+For compatibility with SpamAssassin versions older than 3.4.0 which
+lacked option <em>opt_max_size</em>.
+</dd>
+<p></p>
+<dt><strong><a name="item_opt_scanprob">opt_scanprob</a></strong><br />
+</dt>
+<dd>
+Randomly select messages to scan, with a probability of N, where N ranges
+from 0.0 (no messages scanned) to 1.0 (all messages scanned). Default
+is 1.0.
+</dd>
+<dd>
+<p>This setting can be specified separately for each target.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_opt_before">opt_before</a></strong><br />
+</dt>
+<dd>
+Only use messages which are received after the given time_t value.
+Negative values are an offset from the current time, e.g. -86400 =
+last 24 hours; or as parsed by Time::ParseDate (e.g. '-6 months')
+</dd>
+<dd>
+<p>This setting can be specified separately for each target.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_opt_after">opt_after</a></strong><br />
+</dt>
+<dd>
+Same as opt_before, except the messages are only used if after the given
+time_t value.
+</dd>
+<dd>
+<p>This setting can be specified separately for each target.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_opt_want_date">opt_want_date</a></strong><br />
+</dt>
+<dd>
+Set to 1 (default) if you want the received date to be filled in
+in the <a href="#item_wanted_sub"><code>wanted_sub</code></a> callback below. Set this to 0 to avoid this;
+it's a good idea to set this to 0 if you can, as it imposes a performance
+hit.
+</dd>
+<p></p>
+<dt><strong><a name="item_opt_skip_empty_messages">opt_skip_empty_messages</a></strong><br />
+</dt>
+<dd>
+Set to 1 if you want to skip corrupt, 0-byte messages. The default is 0.
+</dd>
+<p></p>
+<dt><strong><a name="item_opt_cache">opt_cache</a></strong><br />
+</dt>
+<dd>
+Set to 0 (default) if you don't want to use cached information to help speed
+up ArchiveIterator. Set to 1 to enable. This setting requires <a href="#item_opt_cachedir"><code>opt_cachedir</code></a>
+also be set.
+</dd>
+<p></p>
+<dt><strong><a name="item_opt_cachedir">opt_cachedir</a></strong><br />
+</dt>
+<dd>
+Set to the path of a directory where you wish to store cached information for
+<a href="#item_opt_cache"><code>opt_cache</code></a>, if you don't want to mix them with the input files (as is the
+default). The directory must be both readable and writable.
+</dd>
+<p></p>
+<dt><strong><a name="item_wanted_sub">wanted_sub</a></strong><br />
+</dt>
+<dd>
+Reference to a subroutine which will process message data. Usually
+set via set_functions(). The routine will be passed 5 values: class
+(scalar), filename (scalar), received date (scalar), message content
+(array reference, one message line per element), and the message format
+key ('f' for file, 'm' for mbox, 'b' for mbx).
+</dd>
+<dd>
+<p>Note that if <a href="#item_opt_want_date"><code>opt_want_date</code></a> is set to 0, the received date scalar will be
+undefined.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_result_sub">result_sub</a></strong><br />
+</dt>
+<dd>
+Reference to a subroutine which will process the results of the wanted_sub
+for each message processed. Usually set via set_functions().
+The routine will be passed 3 values: class (scalar), result (scalar, returned
+from wanted_sub), and received date (scalar).
+</dd>
+<dd>
+<p>Note that if <a href="#item_opt_want_date"><code>opt_want_date</code></a> is set to 0, the received date scalar will be
+undefined.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_scan_progress_sub">scan_progress_sub</a></strong><br />
+</dt>
+<dd>
+Reference to a subroutine which will be called intermittently during
+the 'scan' phase of the mass-check. No guarantees are made as to
+how frequently this may happen, mind you.
+</dd>
+<p></p>
+<dt><strong><a name="item_opt_from_regex">opt_from_regex</a></strong><br />
+</dt>
+<dd>
+This setting allows for flexibility in specifying the mbox format From seperator.
+</dd>
+<dd>
+<p>It defaults to the regular expression:</p>
+</dd>
+<dd>
+<p>/^From \S+ ?(\S\S\S \S\S\S .\d .\d:\d\d:\d\d \d{4}|.\d-\d\d-\d{4}_\d\d:\d\d:\d\d_)/</p>
+</dd>
+<dd>
+<p>Some SpamAssassin programs such as sa-learn will use the configuration option
+'mbox_format_from_regex' to override the default regular expression.</p>
+</dd>
+<p></p></dl>
+<dt><strong><a name="item_set_functions">set_functions( \&wanted_sub, \&result_sub )</a></strong><br />
+</dt>
+<dd>
+Sets the subroutines used for message processing (wanted_sub), and result
+reporting. For more information, see <em>new()</em> above.
+</dd>
+<p></p>
+<dt><strong><a name="item_run">run ( @target_paths )</a></strong><br />
+</dt>
+<dd>
+Generates the list of messages to process, then runs each message through the
+configured wanted subroutine. Files which have a name ending in <code>.gz</code> or
+<code>.bz2</code> will be properly uncompressed via call to <code>gzip -dc</code> and <code>bzip2 -dc</code>
+respectively.
+</dd>
+<dd>
+<p>The target_paths array is expected to be either one element per path in the
+following format: <code>class:format:raw_location</code>, or a hash reference containing
+key-value option pairs and a 'target' key with a value in that format.</p>
+</dd>
+<dd>
+<p>The key-value option pairs that can be used are: opt_scanprob, opt_after,
+opt_before. See the constructor method's documentation for more information
+on their effects.</p>
+</dd>
+<dd>
+<p><a href="#item_run"><code>run()</code></a> returns 0 if there was an error (can't open a file, etc,) and 1 if there
+were no errors.</p>
+</dd>
+<dl>
+<dt><strong><a name="item_class">class</a></strong><br />
+</dt>
+<dd>
+Either 'h' for ham or 's' for spam. If the class is longer than 1 character,
+it will be truncated. If blank, 'h' is default.
+</dd>
+<p></p>
+<dt><strong><a name="item_format">format</a></strong><br />
+</dt>
+<dd>
+Specifies the format of the raw_location. <code>dir</code> is a directory whose
+files are individual messages, <code>file</code> a file with a single message,
+<code>mbox</code> an mbox formatted file, or <code>mbx</code> for an mbx formatted directory.
+</dd>
+<dd>
+<p><code>detect</code> can also be used. This assumes <code>mbox</code> for any file whose path
+contains the pattern <code>/\.mbox/i</code>, <code>file</code> anything that is not a
+directory, or <code>directory</code> otherwise.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_raw_location">raw_location</a></strong><br />
+</dt>
+<dd>
+Path to file or directory. File globbing is allowed using the
+standard csh-style globbing (see <code>perldoc -f glob</code>). <code>~</code> at the
+front of the value will be replaced by the <code>HOME</code> environment
+variable. Escaped whitespace is protected as well.
+</dd>
+<dd>
+<p><strong>NOTE:</strong> <code>~user</code> is not allowed.</p>
+</dd>
+<dd>
+<p><strong>NOTE 2:</strong> <code>-</code> is not allowed as a raw location. To have
+ArchiveIterator deal with STDIN, generate a temp file.</p>
+</dd>
+<p></p></dl>
+</dl>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p><code>Mail::SpamAssassin</code>
+<code>spamassassin</code>
+<code>mass-check</code></p>
+
+</body>
+
+</html>