1Mail::SpamAssassin::PluUgsienr(3C)ontributed Perl DocumeMnatialt:i:oSnpamAssassin::Plugin(3)
2
3
4

NAME

6       Mail::SpamAssassin::Plugin - SpamAssassin plugin base class
7

SYNOPSIS

9   SpamAssassin configuration:
10         loadplugin MyPlugin /path/to/myplugin.pm
11
12   Perl code:
13         package MyPlugin;
14
15         use Mail::SpamAssassin::Plugin;
16         our @ISA = qw(Mail::SpamAssassin::Plugin);
17
18         sub new {
19           my ($class, $mailsa) = @_;
20
21           # the usual perlobj boilerplate to create a subclass object
22           $class = ref($class) || $class;
23           my $self = $class->SUPER::new($mailsa);
24           bless ($self, $class);
25
26           # then register an eval rule, if desired...
27           $self->register_eval_rule ("check_for_foo");
28
29           # and return the new plugin object
30           return $self;
31         }
32
33         ...methods...
34
35         1;
36

DESCRIPTION

38       This is the base class for SpamAssassin plugins; all plugins must be
39       objects that implement this class.
40
41       This class provides no-op stub methods for all the callbacks that a
42       plugin can receive.  It is expected that your plugin will override one
43       or more of these stubs to perform its actions.
44
45       SpamAssassin implements a plugin chain; each callback event is passed
46       to each of the registered plugin objects in turn.  Any plugin can call
47       "$self->inhibit_further_callbacks()" to block delivery of that event to
48       later plugins in the chain.  This is useful if the plugin has handled
49       the event, and there will be no need for later plugins to handle it as
50       well.
51
52       If you're looking to write a simple eval rule, skip straight to
53       "register_eval_rule()", below.
54

INTERFACE

56       In all the plugin APIs below, "options" refers to a reference to a hash
57       containing name-value pairs.   This is used to ensure future-
58       compatibility, in that we can add new options in future without
59       affecting objects built to an earlier version of the API.
60
61       For example, here would be how to print out the "line" item in a
62       "parse_config()" method:
63
64         sub parse_config {
65           my ($self, $opts) = @_;
66           print "MyPlugin: parse_config got ".$opts->{line}."\n";
67         }
68

METHODS

70       The following methods can be overridden by subclasses to handle events.
71
72       $plugin = MyPluginClass->new ($mailsaobject)
73           Constructor.  Plugins that need to register themselves will need to
74           define their own; the default super-class constructor will work
75           fine for plugins that just override a method.
76
77           Note that subclasses must provide the $mailsaobject to the
78           superclass constructor, like so:
79
80             my $self = $class->SUPER::new($mailsaobject);
81
82           Lifecycle note: plugins that will need to store per-scan state
83           should not store that on the Plugin object; instead this should be
84           stored on the PerMsgStatus object, see "check_start()" below.  It
85           is also likewise recommended that configuration settings be stored
86           on the Conf object; see "parse_config()".
87
88       $plugin->parse_config ( { options ... } )
89           Parse a configuration line that hasn't already been handled.
90           "options" is a reference to a hash containing these options:
91
92           line
93               The line of configuration text to parse.   This has leading and
94               trailing whitespace, and comments, removed.
95
96           key The configuration key; ie. the first "word" on the line.
97
98           value
99               The configuration value; everything after the first "word" and
100               any whitespace after that.
101
102           conf
103               The "Mail::SpamAssassin::Conf" object on which the
104               configuration data should be stored.
105
106           user_config
107               A boolean: 1 if reading a user's configuration, 0 if reading
108               the system-wide configuration files.
109
110           If the configuration line was a setting that is handled by this
111           plugin, the method implementation should call
112           "$self->inhibit_further_callbacks()".
113
114           If the setting is not handled by this plugin, the method should
115           return 0 so that a later plugin may handle it, or so that
116           SpamAssassin can output a warning message to the user if no plugin
117           understands it.
118
119           Lifecycle note: it is suggested that configuration be stored on the
120           "Mail::SpamAssassin::Conf" object in use, instead of the plugin
121           object itself.  That can be found as "$plugin->{main}->{conf}", or
122           as "conf" in the $options hash reference above.   By storing it on
123           "conf", this allows per-user and system-wide configuration
124           precedence to be dealt with correctly.
125
126       $plugin->finish_parsing_start ( { options ... } )
127           Signals that the system-wide configuration has been completely
128           read, but internal data structures are not yet created. It is
129           possible to use this hook to dynamically change the configuration
130           already read in or add new config options.
131
132           "options" is a reference to a hash containing these options:
133
134           conf
135               The "Mail::SpamAssassin::Conf" object on which the
136               configuration data should be stored.
137
138           Note: there are no guarantees that the internal data structures of
139           SpamAssassin will not change from release to release.  In
140           particular to this plugin hook, if you modify the rules data
141           structures in a third-party plugin, all bets are off until such
142           time that an API is present for modifying that configuration data.
143
144       $plugin->finish_parsing_end ( { options ... } )
145           Signals that the system-wide configuration parsing has just
146           finished, and SpamAssassin is nearly ready to check messages.
147
148           "options" is a reference to a hash containing these options:
149
150           conf
151               The "Mail::SpamAssassin::Conf" object on which the
152               configuration data should be stored.
153
154           Note: there are no guarantees that the internal data structures of
155           SpamAssassin will not change from release to release.  In
156           particular to this plugin hook, if you modify the rules data
157           structures in a third-party plugin, all bets are off until such
158           time that an API is present for modifying that configuration data.
159
160       $plugin->user_conf_parsing_start ( { options ... } )
161           Signals that the per-user configuration has been completely read,
162           but not converted to internal data structures. It is possible to
163           use this hook to dynamically change the configuration already read
164           in or add new config options.
165
166           If "allow_user_rules" is enabled in the configuration, it is
167           possible that additional rules have been added since the
168           "finish_parsing_start" plugin hook invocation was called.
169
170           conf
171               The "Mail::SpamAssassin::Conf" object on which the
172               configuration data should be stored.
173
174           Note: there are no guarantees that the internal data structures of
175           SpamAssassin will not change from release to release.  In
176           particular to this plugin hook, if you modify the rules data
177           structures in a third-party plugin, all bets are off until such
178           time that an API is present for modifying that configuration data.
179
180       $plugin->user_conf_parsing_end ( { options ... } )
181           Signals that the per-user configuration parsing has just finished,
182           and SpamAssassin is nearly ready to check messages.   If
183           "allow_user_rules" is enabled in the configuration, it is possible
184           that additional rules have been added since the
185           "finish_parsing_end" plugin hook invocation was called.
186
187           "options" is a reference to a hash containing these options:
188
189           conf
190               The "Mail::SpamAssassin::Conf" object on which the
191               configuration data should be stored.
192
193           Note: there are no guarantees that the internal data structures of
194           SpamAssassin will not change from release to release.  In
195           particular to this plugin hook, if you modify the rules data
196           structures in a third-party plugin, all bets are off until such
197           time that an API is present for modifying that configuration data.
198
199       $plugin->signal_user_changed ( { options ... } )
200           Signals that the current user has changed for a new one.
201
202           username
203               The new user's username.
204
205           user_dir
206               The new user's home directory. (equivalent to "~".)
207
208           userstate_dir
209               The new user's storage directory. (equivalent to
210               "~/.spamassassin".)
211
212       $plugin->services_authorized_for_username ( { options ... } )
213           Validates that a given username is authorized to use certain
214           services.
215
216           In order to authorize a user, the plugin should first check that it
217           can handle any of the services passed into the method and then set
218           the value for each allowed service to true (or any non-negative
219           value).
220
221           The current supported services are: bayessql
222
223           username
224               A username
225
226           services
227               Reference to a hash containing the services you want to check.
228
229               {
230
231                 'bayessql' => 0
232
233               }
234
235           conf
236               The "Mail::SpamAssassin::Conf" object on which the
237               configuration data should be stored.
238
239       $plugin->compile_now_start ( { options ... } )
240           This is called at the beginning of
241           Mail::SpamAssassin::compile_now() so plugins can do any necessary
242           initialization for multi-process SpamAssassin (such as spamd or
243           mass-check -j).
244
245           use_user_prefs
246               The value of $use_user_prefs option in compile_now().
247
248           keep_userstate
249               The value of $keep_userstate option in compile_now().
250
251       $plugin->compile_now_finish ( { options ... } )
252           This is called at the end of Mail::SpamAssassin::compile_now() so
253           plugins can do any necessary initialization for multi-process
254           SpamAssassin (such as spamd or mass-check -j).
255
256           use_user_prefs
257               The value of $use_user_prefs option in compile_now().
258
259           keep_userstate
260               The value of $keep_userstate option in compile_now().
261
262       $plugin->check_start ( { options ... } )
263           Signals that a message check operation is starting.
264
265           permsgstatus
266               The "Mail::SpamAssassin::PerMsgStatus" context object for this
267               scan.
268
269               Lifecycle note: it is recommended that rules that need to track
270               test state on a per-scan basis should store that state on this
271               object, not on the plugin object itself, since the plugin
272               object will be shared between all active scanners.
273
274               The message being scanned is accessible through the
275               "$permsgstatus->get_message()" API; there are a number of other
276               public APIs on that object, too.  See
277               "Mail::SpamAssassin::PerMsgStatus" perldoc.
278
279       $plugin->check_main ( { options ... } )
280           Signals that a message should be checked.  Note that
281           implementations of this hook should return 1.
282
283           permsgstatus
284               The "Mail::SpamAssassin::PerMsgStatus" context object for this
285               scan.
286
287       $plugin->check_tick ( { options ... } )
288           Called periodically during a message check operation.  A callback
289           set for this method is a good place to run through an event loop
290           dealing with network events triggered in a "parse_metadata" method,
291           for example.
292
293           permsgstatus
294               The "Mail::SpamAssassin::PerMsgStatus" context object for this
295               scan.
296
297       $plugin->check_post_dnsbl ( { options ... } )
298           Called after the DNSBL results have been harvested.  This is a good
299           place to harvest your own asynchronously-started network lookups.
300
301           permsgstatus
302               The "Mail::SpamAssassin::PerMsgStatus" context object for this
303               scan.
304
305       $plugin->check_post_learn ( { options ... } )
306           Called after auto-learning may (or may not) have taken place.  If
307           you wish to perform additional learning, whether or not auto-
308           learning happens, this is the place to do it.
309
310           permsgstatus
311               The "Mail::SpamAssassin::PerMsgStatus" context object for this
312               scan.
313
314       $plugin->check_end ( { options ... } )
315           Signals that a message check operation has just finished, and the
316           results are about to be returned to the caller.
317
318           permsgstatus
319               The "Mail::SpamAssassin::PerMsgStatus" context object for this
320               scan.  The current score, names of rules that hit, etc. can be
321               retrieved using the public APIs on this object.
322
323       $plugin->finish_tests ( { options ... } )
324           Called via "Mail::SpamAssassin::finish".  This should clear up any
325           tests that a plugin has added to the namespace.
326
327           In certain circumstances, plugins may find it useful to compile
328           perl functions from the ruleset, on the fly.  It is important to
329           remove these once the "Mail::SpamAssassin" object is deleted,
330           however, and this API allows this.
331
332           Each plugin is responsible for its own generated perl functions.
333
334           conf
335               The "Mail::SpamAssassin::Conf" object on which the
336               configuration data should be stored.
337
338           See also the "register_generated_rule_method" helper API, below.
339
340       $plugin->extract_metadata ( { options ... } )
341           Signals that a message is being mined for metadata.  Some plugins
342           may wish to add their own metadata as well.
343
344           msg The "Mail::SpamAssassin::Message" object for this message.
345
346           permsgstatus
347               The "Mail::SpamAssassin::PerMsgStatus" context object for this
348               scan.
349
350       $plugin->parsed_metadata ( { options ... } )
351           Signals that a message's metadata has been parsed, and can now be
352           accessed by the plugin.
353
354           permsgstatus
355               The "Mail::SpamAssassin::PerMsgStatus" context object for this
356               scan.
357
358       $plugin->start_rules ( { options ... } )
359           Called before testing a set of rules of a given type and priority.
360
361           permsgstatus
362               The "Mail::SpamAssassin::PerMsgStatus" context object for this
363               scan.
364
365           ruletype
366               The type of the rules about to be performed.
367
368           priority
369               The priority level of the rules about to be performed.
370
371       $plugin->hit_rule ( { options ... } )
372           Called when a rule fires.
373
374           permsgstatus
375               The "Mail::SpamAssassin::PerMsgStatus" context object for this
376               scan.
377
378           ruletype
379               The type of the rule that fired.
380
381           rulename
382               The name of the rule that fired.
383
384           score
385               The rule's score in the active scoreset.
386
387       $plugin->ran_rule ( { options ... } )
388           Called after a rule has been tested, whether or not it fired.  When
389           the rule fires, the hit_rule callback is always called before this.
390
391           permsgstatus
392               The "Mail::SpamAssassin::PerMsgStatus" context object for this
393               scan.
394
395           ruletype
396               The type of the rule that was tested.
397
398           rulename
399               The name of the rule that was tested.
400
401       $plugin->autolearn_discriminator ( { options ... } )
402           Control whether a just-scanned message should be learned as either
403           spam or ham.   This method should return one of 1 to learn the
404           message as spam, 0 to learn as ham, or "undef" to not learn from
405           the message at all.
406
407           permsgstatus
408               The "Mail::SpamAssassin::PerMsgStatus" context object for this
409               scan.
410
411       $plugin->autolearn ( { options ... } )
412           Signals that a message is about to be auto-learned as either ham or
413           spam.
414
415           permsgstatus
416               The "Mail::SpamAssassin::PerMsgStatus" context object for this
417               scan.
418
419           isspam
420               1 if the message is spam, 0 if ham.
421
422       $plugin->per_msg_finish ( { options ... } )
423           Signals that a "Mail::SpamAssassin::PerMsgStatus" object is being
424           destroyed, and any per-scan context held on that object by this
425           plugin should be destroyed as well.
426
427           Normally, any member variables on the "PerMsgStatus" object will be
428           cleaned up automatically -- but if your plugin has made a circular
429           reference on that object, this is the place to break them so that
430           garbage collection can operate correctly.
431
432           permsgstatus
433               The "Mail::SpamAssassin::PerMsgStatus" context object for this
434               scan.
435
436       $plugin->have_shortcircuited ( { options ... } )
437           Has the current scan operation 'short-circuited'?  In other words,
438           can further scanning be skipped, since the message is already
439           definitively classified as either spam or ham?
440
441           Plugins should return 0 to indicate that scanning should continue,
442           or 1 to indicate that short-circuiting has taken effect.
443
444           permsgstatus
445               The "Mail::SpamAssassin::PerMsgStatus" context object for this
446               scan.
447
448       $plugin->bayes_learn ( { options ... } )
449           Called at the end of a bayes learn operation.
450
451           This phase is the best place to map the raw (original) token value
452           to the SHA1 hashed value.
453
454           toksref
455               Reference to hash returned by call to tokenize.  The hash takes
456               the format of:
457
458                 {
459                   'SHA1 Hash Value' => 'raw (original) value',
460                   ...
461                 }
462
463               NOTE: This data structure has changed since it was originally
464               introduced in version 3.0.0.  The values are no longer perl
465               anonymous hashes, they are a single string containing the raw
466               token value.  You can test for backward compatibility by
467               checking to see if the value for a key is a reference to a perl
468               HASH, for instance:
469
470               if (ref($toksref->{$sometokenkey}) eq 'HASH') {...
471
472               If it is, then you are using the old interface, otherwise you
473               are using the current interface.
474
475           isspam
476               Boolean value stating what flavor of message the tokens
477               represent, if true then message was specified as spam, false is
478               nonspam.  Note, when function is scan then isspam value is not
479               valid.
480
481           msgid
482               Generated message id of the message just learned.
483
484           msgatime
485               Received date of the current message or current time if
486               received date could not be determined.  In addition, if the
487               receive date is more than 24 hrs into the future it will be
488               reset to current datetime.
489
490       $plugin->bayes_forget ( { options ... } )
491           Called at the end of a bayes forget operation.
492
493           toksref
494               Reference to hash returned by call to tokenize.  See
495               bayes_learn documentation for additional information on the
496               format.
497
498           isspam
499               Boolean value stating what flavor of message the tokens
500               represent, if true then message was specified as spam, false is
501               nonspam.  Note, when function is scan then isspam value is not
502               valid.
503
504           msgid
505               Generated message id of the message just forgotten.
506
507       $plugin->bayes_scan ( { options ... } )
508           Called at the end of a bayes scan operation.  NOTE: Will not be
509           called in case of error or if the message is otherwise skipped.
510
511           toksref
512               Reference to hash returned by call to tokenize.  See
513               bayes_learn documentation for additional information on the
514               format.
515
516           probsref
517               Reference to hash of calculated probabilities for tokens found
518               in the database.
519
520                 {
521                   'SHA1 Hash Value' => {
522                           'prob' => 'calculated probability',
523                           'spam_count' => 'Total number of spam msgs w/ token',
524                           'ham_count' => 'Total number of ham msgs w/ token',
525                           'atime' => 'Atime value for token in database'
526                         }
527                 }
528
529           score
530               Score calculated for this particular message.
531
532           msgatime
533               Calculated atime of the message just learned, note it may have
534               been adjusted if it was determined to be too far into the
535               future.
536
537           significant_tokens
538               Array ref of the tokens found to be significant in determining
539               the score for this message.
540
541       $plugin->plugin_report ( { options ... } )
542           Called if the message is to be reported as spam.  If the reporting
543           system is available, the variable
544           "$options->{report}->report_available}" should be set to 1; if the
545           reporting system successfully reported the message, the variable
546           "$options->{report}->report_return}" should be set to 1.
547
548           report
549               Reference to the Reporter object ("$options->{report}" in the
550               paragraph above.)
551
552           text
553               Reference to a markup removed copy of the message in scalar
554               string format.
555
556           msg Reference to the original message object.
557
558       $plugin->plugin_revoke ( { options ... } )
559           Called if the message is to be reported as ham (revokes a spam
560           report). If the reporting system is available, the variable
561           "$options->{revoke}->revoke_available}" should be set to 1; if the
562           reporting system successfully revoked the message, the variable
563           "$options->{revoke}->revoke_return}" should be set to 1.
564
565           revoke
566               Reference to the Reporter object ("$options->{revoke}" in the
567               paragraph above.)
568
569           text
570               Reference to a markup removed copy of the message in scalar
571               string format.
572
573           msg Reference to the original message object.
574
575       $plugin->whitelist_address( { options ... } )
576           Called when a request is made to add an address to a persistent
577           address list.
578
579           address
580               Address you wish to add.
581
582           cli_p
583               Indicate if the call is being made from a command line
584               interface.
585
586       $plugin->blacklist_address( { options ... } )
587           Called when a request is made to add an address to a persistent
588           address list.
589
590           address
591               Address you wish to add.
592
593           cli_p
594               Indicate if the call is being made from a command line
595               interface.
596
597       $plugin->remove_address( { options ... } )
598           Called when a request is made to remove an address to a persistent
599           address list.
600
601           address
602               Address you wish to remove.
603
604           cli_p
605               Indicate if the call is being made from a command line
606               interface.
607
608       $plugin->spamd_child_init ()
609           Called in each new child process when it starts up under spamd.
610
611       $plugin->log_scan_result ( { options ... } )
612           Called when spamd has completed scanning a message.  Currently,
613           only spamd calls this API.
614
615           result
616               The 'result: ...' line for this scan.  Format is as described
617               at http://wiki.apache.org/spamassassin/SpamdSyslogFormat.
618
619       $plugin->spamd_child_post_connection_close ()
620           Called when child returns from handling a connection.
621
622           If there was an accept failure, the child will die and this code
623           will not be called.
624
625       $plugin->finish ()
626           Called when the "Mail::SpamAssassin" object is destroyed.
627
628       $plugin->learner_new ()
629           Used to support human-trained probabilistic classifiers like the
630           BAYES_* ruleset.  Called when a new "Mail::SpamAssassin::Bayes"
631           object has been created; typically when a new user's scan is about
632           to start.
633
634       $plugin->learn_message ()
635           Train the classifier with a training message.
636
637           isspam
638               1 if the message is spam, 0 if it's non-spam.
639
640           msg The message's "Mail::SpamAssassin::Message" object.
641
642           id  An optional message-identification string, used internally to
643               tag the message.  If it is "undef", one will be generated.  It
644               should be unique to that message.
645
646       $plugin->forget_message ()
647           Tell the classifier to 'forget' its training about a specific
648           message.
649
650           msg The message's "Mail::SpamAssassin::Message" object.
651
652           id  An optional message-identification string, used internally to
653               tag the message.  If it is "undef", one will be generated.  It
654               should be unique to that message.
655
656       $plugin->learner_sync ()
657           Tell the classifier to 'sync' any pending changes against the
658           current user's training database.  This is called by "sa-learn
659           --sync".
660
661           If you do not need to implement these for your classifier, create
662           an implementation that just contains "return 1".
663
664       $plugin->learner_expire_old_training ()
665           Tell the classifier to perform infrequent, time-consuming cleanup
666           of the current user's training database.  This is called by
667           "sa-learn --force-expire".
668
669           If you do not need to implement these for your classifier, create
670           an implementation that just contains "return 1".
671
672       $plugin->learner_is_scan_available ()
673           Should return 1 if it is possible to use the current user's
674           training data for a message-scan operation, or 0 otherwise.
675
676       $plugin->learner_dump_database ()
677           Dump information about the current user's training data to
678           "stdout".  This is called by "sa-learn --dump".
679
680           magic
681               Set to 1 if "magic" name-value metadata should be dumped.
682
683           toks
684               Set to 1 if the database of tokens should be dumped.
685
686           regex
687               Either "undef" to dump all tokens, or a value which specifies a
688               regular expression subset of the tokens to dump.
689
690       $plugin->learner_close ()
691           Close any open databases.
692
693           quiet
694               Set to 1 if warning messages should be suppressed.
695

HELPER APIS

697       These methods provide an API for plugins to register themselves to
698       receive specific events, or control the callback chain behaviour.
699
700       $plugin->register_eval_rule ($nameofevalsub)
701           Plugins that implement an eval test will need to call this, so that
702           SpamAssassin calls into the object when that eval test is
703           encountered.  See the REGISTERING EVAL RULES section for full
704           details.
705
706       $plugin->register_generated_rule_method ($nameofsub)
707           In certain circumstances, plugins may find it useful to compile
708           perl functions from the ruleset, on the fly.  It is important to
709           remove these once the "Mail::SpamAssassin" object is deleted,
710           however, and this API allows this.
711
712           Once the method $nameofsub has been generated, call this API with
713           the name of the method (including full package scope).  This
714           indicates that it's a temporary piece of generated code, built from
715           the SpamAssassin ruleset, and when "Mail::SpamAssassin::finish()"
716           is called, the method will be destroyed.
717
718           This API was added in SpamAssassin 3.2.0.
719
720       $plugin->register_method_priority($methodname, $priority)
721           Indicate that the method named $methodname on the current object
722           has a callback priority of $priority.
723
724           This is used by the plugin handler to determine the relative order
725           of callbacks; plugins with lower-numbered priorities are called
726           before plugins with higher-numbered priorities.  Each method can
727           have a different priority value.  The default value is 0.  The
728           ordering of callbacks to methods with equal priority is undefined.
729
730           Typically, you only need to worry about this if you need to ensure
731           your plugin's method is called before another plugin's
732           implementation of that method.  It should be called from your
733           plugin's constructor.
734
735           This API was added in SpamAssassin 3.2.0.
736
737       $plugin->inhibit_further_callbacks()
738           Tells the plugin handler to inhibit calling into other plugins in
739           the plugin chain for the current callback.  Frequently used when
740           parsing configuration settings using "parse_config()".
741

LOGGING

743       Mail::SpamAssassin::Plugin::dbg($message)
744           Output a debugging message $message, if the SpamAssassin object is
745           running with debugging turned on.
746
747           NOTE: This function is not available in the package namespace of
748           general plugins and can't be called via $self->dbg().  If a plugin
749           wishes to output debug information, it should call
750           "Mail::SpamAssassin::Plugin::dbg($msg)".
751
752       Mail::SpamAssassin::Plugin::info($message)
753           Output an informational message $message, if the SpamAssassin
754           object is running with informational messages turned on.
755
756           NOTE: This function is not available in the package namespace of
757           general plugins and can't be called via $self->info().  If a plugin
758           wishes to output debug information, it should call
759           "Mail::SpamAssassin::Plugin::info($msg)".
760
761           In general, it is better for plugins to use the
762           "Mail::SpamAssassin::Logger" module to import "dbg" and "info"
763           directly, like so:
764
765             use Mail::SpamAssassin::Logger;
766             dbg("some message");
767             info("some other message");
768

REGISTERING EVAL RULES

770       Plugins that implement an eval test must register the methods that can
771       be called from rules in the configuration files, in the plugin class'
772       constructor.
773
774       For example,
775
776         $plugin->register_eval_rule ('check_for_foo')
777
778       will cause "$plugin->check_for_foo()" to be called for this
779       SpamAssassin rule:
780
781         header   FOO_RULE     eval:check_for_foo()
782
783       Note that eval rules are passed the following arguments:
784
785       - The plugin object itself
786       - The "Mail::SpamAssassin::PerMsgStatus" object calling the rule
787       - standard arguments for the rule type in use
788       - any and all arguments as specified in the configuration file
789
790       In other words, the eval test method should look something like this:
791
792         sub check_for_foo {
793           my ($self, $permsgstatus, ...arguments...) = @_;
794           ...code returning 0 or 1
795         }
796
797       Note that the headers can be accessed using the "get()" method on the
798       "Mail::SpamAssassin::PerMsgStatus" object, and the body by
799       "get_decoded_stripped_body_text_array()" and other similar methods.
800       Similarly, the "Mail::SpamAssassin::Conf" object holding the current
801       configuration may be accessed through "$permsgstatus->{main}->{conf}".
802
803       The eval rule should return 1 for a hit, or 0 if the rule is not hit.
804
805       State for a single message being scanned should be stored on the
806       $permsgstatus object, not on the $self object, since $self persists
807       between scan operations.  See the 'lifecycle note' on the
808       "check_start()" method above.
809

STANDARD ARGUMENTS FOR RULE TYPES

811       Plugins will be called with the same arguments as a standard EvalTest.
812       Different rule types receive different information by default:
813
814       - header tests: no extra arguments
815       - body tests: fully rendered message as array reference
816       - rawbody tests: fully decoded message as array reference
817       - full tests: pristine message as scalar reference
818
819       The configuration file arguments will be passed in after the standard
820       arguments.
821

BACKWARD COMPATIBILITY

823       Note that if you write a plugin and need to determine if a particular
824       helper method is supported on "Mail::SpamAssassin::Plugin", you can do
825       this:
826
827           if ($self->can("name_of_method")) {
828             eval {
829               $self->name_of_method();        # etc.
830             }
831           } else {
832             # take fallback action
833           }
834
835       The same applies for the public APIs on objects of other types, such as
836       "Mail::SpamAssassin::PerMsgStatus".
837

SEE ALSO

839       Mail::SpamAssassin(3)
840
841       Mail::SpamAssassin::PerMsgStatus(3)
842
843       http://wiki.apache.org/spamassassin/PluginWritingTips
844
845       http://issues.apache.org/SpamAssassin/show_bug.cgi?id=2163
846
847
848
849perl v5.32.1                      2021-04-14     Mail::SpamAssassin::Plugin(3)
Impressum