You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@spamassassin.apache.org by jm...@apache.org on 2007/07/25 14:52:48 UTC
svn commit: r559437 [1/13] - in /spamassassin/site/full/3.2.x: ./ doc/
Author: jm
Date: Wed Jul 25 05:52:42 2007
New Revision: 559437
URL: http://svn.apache.org/viewvc?view=rev&rev=559437
Log:
updating new doc tree on website
Added:
spamassassin/site/full/3.2.x/
spamassassin/site/full/3.2.x/doc/
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AICache.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AICache.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_ArchiveIterator.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_ArchiveIterator.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AsyncLoop.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AsyncLoop.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AutoWhitelist.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AutoWhitelist.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Bayes.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Bayes.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_BayesStore.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_BayesStore.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_BayesStore_MySQL.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_BayesStore_PgSQL.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_BayesStore_PgSQL.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_BayesStore_SQL.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_BayesStore_SQL.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Client.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Client.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Conf.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Conf.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Conf_LDAP.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Conf_LDAP.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Conf_Parser.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Conf_Parser.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Conf_SQL.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Conf_SQL.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_DnsResolver.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_DnsResolver.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Logger.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Logger.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Logger_File.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Logger_File.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Logger_Stderr.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Logger_Stderr.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Logger_Syslog.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Logger_Syslog.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Message.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Message.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Message_Metadata.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Message_Metadata.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Message_Node.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Message_Node.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PerMsgLearner.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PerMsgLearner.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PerMsgStatus.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PerMsgStatus.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PersistentAddrList.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PersistentAddrList.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PluginHandler.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_PluginHandler.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_ASN.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_ASN.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AWL.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AWL.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AccessDB.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AccessDB.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AntiVirus.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AntiVirus.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AutoLearnThreshold.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_AutoLearnThreshold.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_BodyRuleBaseExtractor.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_BodyRuleBaseExtractor.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Check.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Check.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DCC.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DCC.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DKIM.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DKIM.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DomainKeys.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_DomainKeys.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Hashcash.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Hashcash.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_MIMEHeader.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_MIMEHeader.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_NetCache.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_NetCache.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_OneLineBodyRuleType.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_OneLineBodyRuleType.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Pyzor.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Pyzor.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Razor2.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Razor2.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_RelayCountry.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_RelayCountry.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_ReplaceTags.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_ReplaceTags.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Rule2XSBody.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Rule2XSBody.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_SPF.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_SPF.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Shortcircuit.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Shortcircuit.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_SpamCop.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_SpamCop.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Test.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_Test.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_TextCat.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_TextCat.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_URIDNSBL.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_URIDNSBL.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_URIDetail.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_URIDetail.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_VBounce.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_VBounce.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_WhiteListSubject.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Plugin_WhiteListSubject.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_SQLBasedAddrList.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_SQLBasedAddrList.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_SubProcBackChannel.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_SubProcBackChannel.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Timeout.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Timeout.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Util.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Util.txt
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Util_Progress.html
spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_Util_Progress.txt
spamassassin/site/full/3.2.x/doc/sa-compile.html
spamassassin/site/full/3.2.x/doc/sa-compile.txt
spamassassin/site/full/3.2.x/doc/sa-learn.html
spamassassin/site/full/3.2.x/doc/sa-learn.txt
spamassassin/site/full/3.2.x/doc/sa-update.html
spamassassin/site/full/3.2.x/doc/sa-update.txt
spamassassin/site/full/3.2.x/doc/spamassassin-run.html
spamassassin/site/full/3.2.x/doc/spamassassin-run.txt
spamassassin/site/full/3.2.x/doc/spamassassin.html
spamassassin/site/full/3.2.x/doc/spamassassin.txt
spamassassin/site/full/3.2.x/doc/spamc.html
spamassassin/site/full/3.2.x/doc/spamc.txt
spamassassin/site/full/3.2.x/doc/spamd.html
spamassassin/site/full/3.2.x/doc/spamd.txt
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin.html?view=auto&rev=559437
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin.html Wed Jul 25 05:52:42 2007
@@ -0,0 +1,769 @@
+<!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:jm@apache.org" />
+</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();</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 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_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 tests will not attempt to use IPv6. Use if the existing tests
+for IPv6 availablity produce incorrect results or crashes.
+</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_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></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)</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 of the entire message, an array reference of the
+message with 1 line per array element, or a file glob which holds the
+entire contents of the message; and $parse_now, which specifies whether
+or not to create the 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>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)</a></strong><br />
+</dt>
+<dd>
+Given a string containing an email address, add it to the automatic
+whitelist database.
+</dd>
+<p></p>
+<dt><strong><a name="item_add_all_addresses_to_whitelist">$f->add_all_addresses_to_whitelist ($mail)</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>
+<p></p>
+<dt><strong><a name="item_remove_address_from_whitelist">$f->remove_address_from_whitelist ($addr)</a></strong><br />
+</dt>
+<dd>
+Given a string containing an email address, remove it from the automatic
+whitelist database.
+</dd>
+<p></p>
+<dt><strong><a name="item_remove_all_addresses_from_whitelist">$f->remove_all_addresses_from_whitelist ($mail)</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>
+<p></p>
+<dt><strong><a name="item_add_address_to_blacklist">$f->add_address_to_blacklist ($addr)</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>
+<p></p>
+<dt><strong><a name="item_add_all_addresses_to_blacklist">$f->add_all_addresses_to_blacklist ($mail)</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>
+<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.2.x/doc/Mail_SpamAssassin.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin.txt?view=auto&rev=559437
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin.txt Wed Jul 25 05:52:42 2007
@@ -0,0 +1,504 @@
+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();
+
+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 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".
+
+ 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 tests will not attempt to use IPv6. Use if the
+ existing tests for IPv6 availablity produce incorrect results or
+ crashes.
+
+ 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)
+
+ 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).
+
+ 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)
+ 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 of the entire message, an array reference
+ of the message with 1 line per array element, or a file glob which
+ holds the entire contents of the message; and $parse_now, which
+ specifies whether or not to create the 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.
+
+ 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)
+ Given a string containing an email address, add it to the automatic
+ whitelist database.
+
+ $f->add_all_addresses_to_whitelist ($mail)
+ 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.
+
+ $f->remove_address_from_whitelist ($addr)
+ Given a string containing an email address, remove it from the
+ automatic whitelist database.
+
+ $f->remove_all_addresses_from_whitelist ($mail)
+ 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.
+
+ $f->add_address_to_blacklist ($addr)
+ Given a string containing an email address, add it to the automatic
+ whitelist database with a high score, effectively blacklisting them.
+
+ $f->add_all_addresses_to_blacklist ($mail)
+ 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.
+
+ $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.2.x/doc/Mail_SpamAssassin_AICache.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AICache.html?view=auto&rev=559437
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AICache.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AICache.html Wed Jul 25 05:52:42 2007
@@ -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:jm@apache.org" />
+</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>
+</dl>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AICache.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AICache.txt?view=auto&rev=559437
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AICache.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AICache.txt Wed Jul 25 05:52:42 2007
@@ -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.2.x/doc/Mail_SpamAssassin_ArchiveIterator.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_ArchiveIterator.html?view=auto&rev=559437
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_ArchiveIterator.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_ArchiveIterator.html Wed Jul 25 05:52:42 2007
@@ -0,0 +1,246 @@
+<!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:jm@apache.org" />
+</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_all' => 1,
+ '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 wanted
+and results 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_all">opt_all</a></strong><br />
+</dt>
+<dd>
+Typically messages over 250k are skipped by ArchiveIterator. Use this option
+to keep from skipping messages based on size.
+</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_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></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>
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_ArchiveIterator.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_ArchiveIterator.txt?view=auto&rev=559437
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_ArchiveIterator.txt (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_ArchiveIterator.txt Wed Jul 25 05:52:42 2007
@@ -0,0 +1,153 @@
+NAME
+ Mail::SpamAssassin::ArchiveIterator - find and process messages one at a
+ time
+
+SYNOPSIS
+ my $iter = new Mail::SpamAssassin::ArchiveIterator(
+ {
+ 'opt_all' => 1,
+ 'opt_cache' => 1,
+ }
+ );
+
+ $iter->set_functions( \&wanted, sub { } );
+
+ eval { $iter->run(@ARGV); };
+
+ sub wanted {
+ my($class, $filename, $recv_date, $msg_array) = @_;
+
+ ...
+ }
+
+DESCRIPTION
+ 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 wanted and
+ results functions appropriately per message.
+
+METHODS
+ $item = new Mail::SpamAssassin::ArchiveIterator( [ { opt => val, ... } ]
+ )
+ Constructs a new "Mail::SpamAssassin::ArchiveIterator" object. You
+ may pass the following attribute-value pairs to the constructor. The
+ pairs are optional unless otherwise noted.
+
+ opt_all
+ Typically messages over 250k are skipped by ArchiveIterator. Use
+ this option to keep from skipping messages based on size.
+
+ opt_scanprob
+ 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.
+
+ This setting can be specified separately for each target.
+
+ opt_before
+ 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')
+
+ This setting can be specified separately for each target.
+
+ opt_after
+ Same as opt_before, except the messages are only used if after
+ the given time_t value.
+
+ This setting can be specified separately for each target.
+
+ opt_want_date
+ Set to 1 (default) if you want the received date to be filled in
+ in the "wanted_sub" 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.
+
+ opt_cache
+ 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 "opt_cachedir" also be set.
+
+ opt_cachedir
+ Set to the path of a directory where you wish to store cached
+ information for "opt_cache", if you don't want to mix them with
+ the input files (as is the default). The directory must be both
+ readable and writable.
+
+ wanted_sub
+ 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).
+
+ Note that if "opt_want_date" is set to 0, the received date
+ scalar will be undefined.
+
+ result_sub
+ 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).
+
+ Note that if "opt_want_date" is set to 0, the received date
+ scalar will be undefined.
+
+ scan_progress_sub
+ 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.
+
+ set_functions( \&wanted_sub, \&result_sub )
+ Sets the subroutines used for message processing (wanted_sub), and
+ result reporting. For more information, see *new()* above.
+
+ run ( @target_paths )
+ Generates the list of messages to process, then runs each message
+ through the configured wanted subroutine. Files which have a name
+ ending in ".gz" or ".bz2" will be properly uncompressed via call to
+ "gzip -dc" and "bzip2 -dc" respectively.
+
+ The target_paths array is expected to be either one element per path
+ in the following format: "class:format:raw_location", or a hash
+ reference containing key-value option pairs and a 'target' key with
+ a value in that format.
+
+ 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.
+
+ run() returns 0 if there was an error (can't open a file, etc,) and
+ 1 if there were no errors.
+
+ class
+ 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.
+
+ format
+ Specifies the format of the raw_location. "dir" is a directory
+ whose files are individual messages, "file" a file with a single
+ message, "mbox" an mbox formatted file, or "mbx" for an mbx
+ formatted directory.
+
+ "detect" can also be used. This assumes "mbox" for any file
+ whose path contains the pattern "/\.mbox/i", "file" anything
+ that is not a directory, or "directory" otherwise.
+
+ raw_location
+ Path to file or directory. File globbing is allowed using the
+ standard csh-style globbing (see "perldoc -f glob"). "~" at the
+ front of the value will be replaced by the "HOME" environment
+ variable. Escaped whitespace is protected as well.
+
+ NOTE: "~user" is not allowed.
+
+ NOTE 2: "-" is not allowed as a raw location. To have
+ ArchiveIterator deal with STDIN, generate a temp file.
+
+SEE ALSO
+ "Mail::SpamAssassin" "spamassassin" "mass-check"
+
Added: spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AsyncLoop.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AsyncLoop.html?view=auto&rev=559437
==============================================================================
--- spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AsyncLoop.html (added)
+++ spamassassin/site/full/3.2.x/doc/Mail_SpamAssassin_AsyncLoop.html Wed Jul 25 05:52:42 2007
@@ -0,0 +1,175 @@
+<!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::AsyncLoop - scanner asynchronous event loop</title>
+<link rev="made" href="mailto:jm@apache.org" />
+</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="#description">DESCRIPTION</a></li>
+ <li><a href="#methods">METHODS</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop</p>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>An asynchronous event loop used for long-running operations, performed ``in the
+background'' during the Mail::SpamAssassin::check() scan operation, such as DNS
+blocklist lookups.</p>
+<p>
+</p>
+<hr />
+<h1><a name="methods">METHODS</a></h1>
+<dl>
+<dt><strong><a name="item_start_lookup">$obj = $async-><code>start_lookup($obj)</code></a></strong><br />
+</dt>
+<dd>
+Register the start of a long-running asynchronous lookup operation. <code>$obj</code>
+is a hash reference containing the following items:
+</dd>
+<dl>
+<dt><strong><a name="item_key">key (required)</a></strong><br />
+</dt>
+<dd>
+A key string, unique to this lookup. This is what is reported in
+debug messages, used as the key for <a href="#item_get_lookup"><code>get_lookup()</code></a>, etc.
+</dd>
+<p></p>
+<dt><strong><a name="item_id">id (required)</a></strong><br />
+</dt>
+<dd>
+An ID string, also unique to this lookup. Typically, this is the DNS packet ID
+as returned by DnsResolver's <code>bgsend</code> method. Sadly, the Net::DNS
+architecture forces us to keep a separate ID string for this task instead of
+reusing <a href="#item_key"><code>key</code></a> -- if you are not using DNS lookups through DnsResolver, it
+should be OK to just reuse <a href="#item_key"><code>key</code></a>.
+</dd>
+<p></p>
+<dt><strong><a name="item_type">type (required)</a></strong><br />
+</dt>
+<dd>
+A string, typically one word, used to describe the type of lookup in log
+messages, such as <code>DNSBL</code>, <code>MX</code>, <code>TXT</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_poll_callback">poll_callback (optional)</a></strong><br />
+</dt>
+<dd>
+A code reference, which will be called periodically during the
+background-processing period. If you will be performing an async lookup on a
+non-DNS-based service, you will need to implement this so that it checks for
+new responses and calls <a href="#item_set_response_packet"><code>set_response_packet()</code></a> or <a href="#item_report_id_complete"><code>report_id_complete()</code></a> as
+appropriate. DNS-based lookups can leave it undefined, since
+DnsResolver::poll_responses() will be called automatically anyway.
+</dd>
+<dd>
+<p>The code reference will be called with one argument, the <code>$ent</code> object.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_completed_callback">completed_callback (optional)</a></strong><br />
+</dt>
+<dd>
+A code reference, which will be called when the lookup has been reported as
+complete via <a href="#item_set_response_packet"><code>set_response_packet()</code></a> or <a href="#item_report_id_complete"><code>report_id_complete()</code></a>.
+</dd>
+<dd>
+<p>The code reference will be called with one argument, the <code>$ent</code> object.</p>
+</dd>
+<p></p></dl>
+<p><code>$obj</code> is returned by this method.</p>
+<dt><strong><a name="item_get_lookup">$obj = $async-><code>get_lookup($key)</code></a></strong><br />
+</dt>
+<dd>
+Retrieve the pending-lookup object for the given key <code>$key</code>.
+</dd>
+<dd>
+<p>If the lookup is complete, this will return <code>undef</code>.</p>
+</dd>
+<dd>
+<p>Note that a lookup is still considered ``pending'' until <a href="#item_complete_lookups"><code>complete_lookups()</code></a> is
+called, even if it has been reported as complete via <a href="#item_set_response_packet"><code>set_response_packet()</code></a>
+or <a href="#item_report_id_complete"><code>report_id_complete()</code></a>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_pending_lookups">@objs = $async-><code>get_pending_lookups()</code></a></strong><br />
+</dt>
+<dd>
+Retrieve the lookup objects for all pending lookups.
+</dd>
+<dd>
+<p>Note that a lookup is still considered ``pending'' until <a href="#item_complete_lookups"><code>complete_lookups()</code></a> is
+called, even if it has been reported as complete via <a href="#item_set_response_packet"><code>set_response_packet()</code></a>
+or <a href="#item_report_id_complete"><code>report_id_complete()</code></a>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_complete_lookups">$alldone = $async-><code>complete_lookups()</code></a></strong><br />
+</dt>
+<dd>
+Perform a poll of the pending lookups, to see if any are completed; if they
+are, their <completed_callback> is called with the entry object for that
+lookup.
+</dd>
+<dd>
+<p>If there are no lookups remaining, or if too long has elapsed since any results
+were returned, <code>1</code> is returned, otherwise <code>0</code>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_abort_remaining_lookups">$async-><code>abort_remaining_lookups()</code></a></strong><br />
+</dt>
+<dd>
+Abort any remaining lookups.
+</dd>
+<p></p>
+<dt><strong><a name="item_set_response_packet">$async->set_response_packet($id, $pkt)</a></strong><br />
+</dt>
+<dd>
+Register a ``response packet'' for a given query. <code>$id</code> is the ID for the
+query, and must match the <a href="#item_id"><code>id</code></a> supplied in <a href="#item_start_lookup"><code>start_lookup()</code></a>. <code>$pkt</code> is the
+packet object for the response.
+</dd>
+<dd>
+<p>If this was called, <code>$pkt</code> will be available in the <a href="#item_completed_callback"><code>completed_callback</code></a>
+function as <code>$ent-<gt</code>{response_packet}>.</p>
+</dd>
+<dd>
+<p>One or the other of <a href="#item_set_response_packet"><code>set_response_packet()</code></a> or <a href="#item_report_id_complete"><code>report_id_complete()</code></a>
+should be called, but not both.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_report_id_complete">$async-><code>report_id_complete($id)</code></a></strong><br />
+</dt>
+<dd>
+Register that a query has completed, and is no longer ``pending''. <code>$id</code> is the
+ID for the query, and must match the <a href="#item_id"><code>id</code></a> supplied in <a href="#item_start_lookup"><code>start_lookup()</code></a>.
+</dd>
+<dd>
+<p>One or the other of <a href="#item_set_response_packet"><code>set_response_packet()</code></a> or <a href="#item_report_id_complete"><code>report_id_complete()</code></a>
+should be called, but not both.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_get_last_start_lookup_time">$time = $async-><code>get_last_start_lookup_time()</code></a></strong><br />
+</dt>
+<dd>
+Get the time of the last call to <a href="#item_start_lookup"><code>start_lookup()</code></a>. If <a href="#item_start_lookup"><code>start_lookup()</code></a> was
+never called or <a href="#item_abort_remaining_lookups"><code>abort_remaining_lookups()</code></a> has been called
+<a href="#item_get_last_start_lookup_time"><code>get_last_start_lookup_time()</code></a> will return undef.
+</dd>
+<p></p></dl>
+
+</body>
+
+</html>