Mail::SpamAssassin::Plugin(3pm)

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 is
85           also likewise recommended that configuration settings be stored on
86           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_dnsbl ( { options ... } )
298           Called when DNSBL or other network lookups are being launched,
299           implying current running priority of -100.  This is the place to
300           start your own asynchronously-started network lookups.
301
302           permsgstatus
303               The "Mail::SpamAssassin::PerMsgStatus" context object for this
304               scan.
305
306       $plugin->check_post_dnsbl ( { options ... } )
307           Called after the DNSBL results have been harvested.  This is a good
308           place to harvest your own asynchronously-started network lookups.
309
310           permsgstatus
311               The "Mail::SpamAssassin::PerMsgStatus" context object for this
312               scan.
313
314       $plugin->check_cleanup ( { options ... } )
315           Called just before message check is finishing and before possible
316           auto-learning.  This is guaranteed to be always called, unlike
317           check_tick and check_post_dnsbl.  Used for cleaning up left
318           callbacks or forked children etc, last chance to make rules hit.
319
320           permsgstatus
321               The "Mail::SpamAssassin::PerMsgStatus" context object for this
322               scan.
323
324       $plugin->check_post_learn ( { options ... } )
325           Called after auto-learning may (or may not) have taken place.  If
326           you wish to perform additional learning, whether or not auto-
327           learning happens, this is the place to do it.
328
329           permsgstatus
330               The "Mail::SpamAssassin::PerMsgStatus" context object for this
331               scan.
332
333       $plugin->check_end ( { options ... } )
334           Signals that a message check operation has just finished, and the
335           results are about to be returned to the caller.
336
337           permsgstatus
338               The "Mail::SpamAssassin::PerMsgStatus" context object for this
339               scan.  The current score, names of rules that hit, etc. can be
340               retrieved using the public APIs on this object.
341
342       $plugin->finish_tests ( { options ... } )
343           Called via "Mail::SpamAssassin::finish".  This should clear up any
344           tests that a plugin has added to the namespace.
345
346           In certain circumstances, plugins may find it useful to compile
347           perl functions from the ruleset, on the fly.  It is important to
348           remove these once the "Mail::SpamAssassin" object is deleted,
349           however, and this API allows this.
350
351           Each plugin is responsible for its own generated perl functions.
352
353           conf
354               The "Mail::SpamAssassin::Conf" object on which the
355               configuration data should be stored.
356
357           See also the "register_generated_rule_method" helper API, below.
358
359       $plugin->extract_metadata ( { options ... } )
360           Signals that a message is being mined for metadata.  Some plugins
361           may wish to add their own metadata as well.
362
363           msg The "Mail::SpamAssassin::Message" object for this message.
364
365           permsgstatus
366               The "Mail::SpamAssassin::PerMsgStatus" context object for this
367               scan.
368
369       $plugin->parsed_metadata ( { options ... } )
370           Signals that a message's metadata has been parsed, and can now be
371           accessed by the plugin.
372
373           permsgstatus
374               The "Mail::SpamAssassin::PerMsgStatus" context object for this
375               scan.
376
377       $plugin->start_rules ( { options ... } )
378           Called before testing a set of rules of a given type and priority.
379
380           permsgstatus
381               The "Mail::SpamAssassin::PerMsgStatus" context object for this
382               scan.
383
384           ruletype
385               The type of the rules about to be performed.
386
387           priority
388               The priority level of the rules about to be performed.
389
390       $plugin->hit_rule ( { options ... } )
391           Called when a rule fires.
392
393           permsgstatus
394               The "Mail::SpamAssassin::PerMsgStatus" context object for this
395               scan.
396
397           ruletype
398               The type of the rule that fired.
399
400           rulename
401               The name of the rule that fired.
402
403           score
404               The rule's score in the active scoreset.
405
406       $plugin->ran_rule ( { options ... } )
407           Called after a rule has been tested, whether or not it fired.  When
408           the rule fires, the hit_rule callback is always called before this.
409
410           permsgstatus
411               The "Mail::SpamAssassin::PerMsgStatus" context object for this
412               scan.
413
414           ruletype
415               The type of the rule that was tested.
416
417           rulename
418               The name of the rule that was tested.
419
420       $plugin->autolearn_discriminator ( { options ... } )
421           Control whether a just-scanned message should be learned as either
422           spam or ham.   This method should return one of 1 to learn the
423           message as spam, 0 to learn as ham, or "undef" to not learn from
424           the message at all.
425
426           permsgstatus
427               The "Mail::SpamAssassin::PerMsgStatus" context object for this
428               scan.
429
430       $plugin->autolearn ( { options ... } )
431           Signals that a message is about to be auto-learned as either ham or
432           spam.
433
434           permsgstatus
435               The "Mail::SpamAssassin::PerMsgStatus" context object for this
436               scan.
437
438           isspam
439               1 if the message is spam, 0 if ham.
440
441       $plugin->per_msg_finish ( { options ... } )
442           Signals that a "Mail::SpamAssassin::PerMsgStatus" object is being
443           destroyed, and any per-scan context held on that object by this
444           plugin should be destroyed as well.
445
446           Normally, any member variables on the "PerMsgStatus" object will be
447           cleaned up automatically -- but if your plugin has made a circular
448           reference on that object, this is the place to break them so that
449           garbage collection can operate correctly.
450
451           permsgstatus
452               The "Mail::SpamAssassin::PerMsgStatus" context object for this
453               scan.
454
455       $plugin->have_shortcircuited ( { options ... } )
456           Has the current scan operation 'short-circuited'?  In other words,
457           can further scanning be skipped, since the message is already
458           definitively classified as either spam or ham?
459
460           Plugins should return 0 to indicate that scanning should continue,
461           or 1 to indicate that short-circuiting has taken effect.
462
463           permsgstatus
464               The "Mail::SpamAssassin::PerMsgStatus" context object for this
465               scan.
466
467       $plugin->bayes_learn ( { options ... } )
468           Called at the end of a bayes learn operation.
469
470           This phase is the best place to map the raw (original) token value
471           to the SHA1 hashed value.
472
473           toksref
474               Reference to hash returned by call to tokenize.  The hash takes
475               the format of:
476
477                 {
478                   'SHA1 Hash Value' => 'raw (original) value',
479                   ...
480                 }
481
482               NOTE: This data structure has changed since it was originally
483               introduced in version 3.0.0.  The values are no longer perl
484               anonymous hashes, they are a single string containing the raw
485               token value.  You can test for backward compatibility by
486               checking to see if the value for a key is a reference to a perl
487               HASH, for instance:
488
489               if (ref($toksref->{$sometokenkey}) eq 'HASH') {...
490
491               If it is, then you are using the old interface, otherwise you
492               are using the current interface.
493
494           isspam
495               Boolean value stating what flavor of message the tokens
496               represent, if true then message was specified as spam, false is
497               nonspam.  Note, when function is scan then isspam value is not
498               valid.
499
500           msgid
501               Generated message id of the message just learned.
502
503           msgatime
504               Received date of the current message or current time if
505               received date could not be determined.  In addition, if the
506               receive date is more than 24 hrs into the future it will be
507               reset to current datetime.
508
509       $plugin->bayes_forget ( { options ... } )
510           Called at the end of a bayes forget operation.
511
512           toksref
513               Reference to hash returned by call to tokenize.  See
514               bayes_learn documentation for additional information on the
515               format.
516
517           isspam
518               Boolean value stating what flavor of message the tokens
519               represent, if true then message was specified as spam, false is
520               nonspam.  Note, when function is scan then isspam value is not
521               valid.
522
523           msgid
524               Generated message id of the message just forgotten.
525
526       $plugin->bayes_scan ( { options ... } )
527           Called at the end of a bayes scan operation.  NOTE: Will not be
528           called in case of error or if the message is otherwise skipped.
529
530           toksref
531               Reference to hash returned by call to tokenize.  See
532               bayes_learn documentation for additional information on the
533               format.
534
535           probsref
536               Reference to hash of calculated probabilities for tokens found
537               in the database.
538
539                 {
540                   'SHA1 Hash Value' => {
541                           'prob' => 'calculated probability',
542                           'spam_count' => 'Total number of spam msgs w/ token',
543                           'ham_count' => 'Total number of ham msgs w/ token',
544                           'atime' => 'Atime value for token in database'
545                         }
546                 }
547
548           score
549               Score calculated for this particular message.
550
551           msgatime
552               Calculated atime of the message just learned, note it may have
553               been adjusted if it was determined to be too far into the
554               future.
555
556           significant_tokens
557               Array ref of the tokens found to be significant in determining
558               the score for this message.
559
560       $plugin->plugin_report ( { options ... } )
561           Called if the message is to be reported as spam.  If the reporting
562           system is available, the variable
563           "$options->{report}->report_available}" should be set to 1; if the
564           reporting system successfully reported the message, the variable
565           "$options->{report}->report_return}" should be set to 1.
566
567           report
568               Reference to the Reporter object ("$options->{report}" in the
569               paragraph above.)
570
571           text
572               Reference to a markup removed copy of the message in scalar
573               string format.
574
575           msg Reference to the original message object.
576
577       $plugin->plugin_revoke ( { options ... } )
578           Called if the message is to be reported as ham (revokes a spam
579           report). If the reporting system is available, the variable
580           "$options->{revoke}->revoke_available}" should be set to 1; if the
581           reporting system successfully revoked the message, the variable
582           "$options->{revoke}->revoke_return}" should be set to 1.
583
584           revoke
585               Reference to the Reporter object ("$options->{revoke}" in the
586               paragraph above.)
587
588           text
589               Reference to a markup removed copy of the message in scalar
590               string format.
591
592           msg Reference to the original message object.
593
594       $plugin->welcomelist_address( { options ... } )
595           Previously whitelist_address which will work interchangeably until
596           4.1.
597
598           Called when a request is made to add an address to a persistent
599           address list.
600
601           address
602               Address you wish to add.
603
604           cli_p
605               Indicate if the call is being made from a command line
606               interface.
607
608       $plugin->blocklist_address( { options ... } )
609           Previously blacklist_address which will work interchangeably until
610           4.1.
611
612           Called when a request is made to add an address to a persistent
613           address list.
614
615           address
616               Address you wish to add.
617
618           cli_p
619               Indicate if the call is being made from a command line
620               interface.
621
622       $plugin->remove_address( { options ... } )
623           Called when a request is made to remove an address to a persistent
624           address list.
625
626           address
627               Address you wish to remove.
628
629           cli_p
630               Indicate if the call is being made from a command line
631               interface.
632
633       $plugin->spamd_child_init ()
634           Called in each new child process when it starts up under spamd.
635
636       $plugin->log_scan_result ( { options ... } )
637           Called when spamd has completed scanning a message.  Currently,
638           only spamd calls this API.
639
640           result
641               The 'result: ...' line for this scan.  Format is as described
642               at https://wiki.apache.org/spamassassin/SpamdSyslogFormat.
643
644       $plugin->spamd_child_post_connection_close ()
645           Called when child returns from handling a connection.
646
647           If there was an accept failure, the child will die and this code
648           will not be called.
649
650       $plugin->finish ()
651           Called when the "Mail::SpamAssassin" object is destroyed.
652
653       $plugin->learner_new ()
654           Used to support human-trained probabilistic classifiers like the
655           BAYES_* ruleset.  Called when a new "Mail::SpamAssassin::Bayes"
656           object has been created; typically when a new user's scan is about
657           to start.
658
659       $plugin->learn_message ()
660           Train the classifier with a training message.
661
662           isspam
663               1 if the message is spam, 0 if it's non-spam.
664
665           msg The message's "Mail::SpamAssassin::Message" object.
666
667           id  An optional message-identification string, used internally to
668               tag the message.  If it is "undef", one will be generated.  It
669               should be unique to that message.
670
671       $plugin->forget_message ()
672           Tell the classifier to 'forget' its training about a specific
673           message.
674
675           msg The message's "Mail::SpamAssassin::Message" object.
676
677           id  An optional message-identification string, used internally to
678               tag the message.  If it is "undef", one will be generated.  It
679               should be unique to that message.
680
681       $plugin->learner_sync ()
682           Tell the classifier to 'sync' any pending changes against the
683           current user's training database.  This is called by "sa-learn
684           --sync".
685
686           If you do not need to implement these for your classifier, create
687           an implementation that just contains "return 1".
688
689       $plugin->learner_expire_old_training ()
690           Tell the classifier to perform infrequent, time-consuming cleanup
691           of the current user's training database.  This is called by
692           "sa-learn --force-expire".
693
694           If you do not need to implement these for your classifier, create
695           an implementation that just contains "return 1".
696
697       $plugin->learner_is_scan_available ()
698           Should return 1 if it is possible to use the current user's
699           training data for a message-scan operation, or 0 otherwise.
700
701       $plugin->learner_dump_database ()
702           Dump information about the current user's training data to
703           "stdout".  This is called by "sa-learn --dump".
704
705           magic
706               Set to 1 if "magic" name-value metadata should be dumped.
707
708           toks
709               Set to 1 if the database of tokens should be dumped.
710
711           regex
712               Either "undef" to dump all tokens, or a value which specifies a
713               regular expression subset of the tokens to dump.
714
715       $plugin->learner_close ()
716           Close any open databases.
717
718           quiet
719               Set to 1 if warning messages should be suppressed.
720

HELPER APIS

722       These methods provide an API for plugins to register themselves to
723       receive specific events, or control the callback chain behaviour.
724
725       $plugin->register_eval_rule ($nameofevalsub, $ruletype)
726           Plugins that implement an eval test will need to call this, so that
727           SpamAssassin calls into the object when that eval test is
728           encountered.  See the REGISTERING EVAL RULES section for full
729           details.
730
731           Since 4.0, optional $ruletype can be specified to enforce that eval
732           function cannot be called with wrong ruletype from configuration,
733           for example user using "header FOO eval:foobar()" instead of "body
734           FOO eval:foobar()".  Mismatch will result in lint failure.
735           $ruletype can be one of:
736
737             $Mail::SpamAssassin::Conf::TYPE_HEAD_EVALS
738             $Mail::SpamAssassin::Conf::TYPE_BODY_EVALS  (allows both body and rawbody)
739             $Mail::SpamAssassin::Conf::TYPE_RAWBODY_EVALS
740             $Mail::SpamAssassin::Conf::TYPE_FULL_EVALS
741
742       $plugin->register_generated_rule_method ($nameofsub)
743           In certain circumstances, plugins may find it useful to compile
744           perl functions from the ruleset, on the fly.  It is important to
745           remove these once the "Mail::SpamAssassin" object is deleted,
746           however, and this API allows this.
747
748           Once the method $nameofsub has been generated, call this API with
749           the name of the method (including full package scope).  This
750           indicates that it's a temporary piece of generated code, built from
751           the SpamAssassin ruleset, and when Mail::SpamAssassin::finish() is
752           called, the method will be destroyed.
753
754           This API was added in SpamAssassin 3.2.0.
755
756       $plugin->register_method_priority($methodname, $priority)
757           Indicate that the method named $methodname on the current object
758           has a callback priority of $priority.
759
760           This is used by the plugin handler to determine the relative order
761           of callbacks; plugins with lower-numbered priorities are called
762           before plugins with higher-numbered priorities.  Each method can
763           have a different priority value.  The default value is 0.  The
764           ordering of callbacks to methods with equal priority is undefined.
765
766           Typically, you only need to worry about this if you need to ensure
767           your plugin's method is called before another plugin's
768           implementation of that method.  It should be called from your
769           plugin's constructor.
770
771           This API was added in SpamAssassin 3.2.0.
772
773       $plugin->inhibit_further_callbacks()
774           Tells the plugin handler to inhibit calling into other plugins in
775           the plugin chain for the current callback.  Frequently used when
776           parsing configuration settings using parse_config().
777

LOGGING

779       Mail::SpamAssassin::Plugin::dbg($message)
780           Output a debugging message $message, if the SpamAssassin object is
781           running with debugging turned on.
782
783           NOTE: This function is not available in the package namespace of
784           general plugins and can't be called via $self->dbg().  If a plugin
785           wishes to output debug information, it should call
786           Mail::SpamAssassin::Plugin::dbg($msg).
787
788       Mail::SpamAssassin::Plugin::info($message)
789           Output an informational message $message, if the SpamAssassin
790           object is running with informational messages turned on.
791
792           NOTE: This function is not available in the package namespace of
793           general plugins and can't be called via $self->info().  If a plugin
794           wishes to output debug information, it should call
795           Mail::SpamAssassin::Plugin::info($msg).
796
797           In general, it is better for plugins to use the
798           "Mail::SpamAssassin::Logger" module to import "dbg" and "info"
799           directly, like so:
800
801             use Mail::SpamAssassin::Logger;
802             dbg("some message");
803             info("some other message");
804

REGISTERING EVAL RULES

806       Plugins that implement an eval test must register the methods that can
807       be called from rules in the configuration files, in the plugin class'
808       constructor.
809
810       For example,
811
812         $plugin->register_eval_rule ('check_for_foo', $Mail::SpamAssassin::Conf::TYPE_HEAD_EVALS)
813
814       will cause "$plugin->check_for_foo()" to be called for this
815       SpamAssassin rule:
816
817         header   FOO_RULE     eval:check_for_foo()
818
819       Note that eval rules are passed the following arguments:
820
821       - The plugin object itself
822       - The "Mail::SpamAssassin::PerMsgStatus" object calling the rule
823       - standard arguments for the rule type in use
824       - any and all arguments as specified in the configuration file
825
826       In other words, the eval test method should look something like this:
827
828         sub check_for_foo {
829           my ($self, $permsgstatus, ...arguments...) = @_;
830           ...code returning 0 (miss), 1 (hit), or undef (async function)
831         }
832
833       The eval rule should return 1 for a hit, or 0 if the rule is not hit.
834       Special case of "return undef" must be used when result is not yet
835       ready and it will be later declared with PerMsgStatus functions
836       got_hit() or rule_ready() - see their documentation for more info.
837       Make sure not to return undef by mistake.
838
839       Note that the headers can be accessed using the get() method on the
840       "Mail::SpamAssassin::PerMsgStatus" object, and the body by
841       get_decoded_stripped_body_text_array() and other similar methods.
842       Similarly, the "Mail::SpamAssassin::Conf" object holding the current
843       configuration may be accessed through "$permsgstatus->{main}->{conf}".
844
845       State for a single message being scanned should be stored on the
846       $permsgstatus object, not on the $self object, since $self persists
847       between scan operations.  See the 'lifecycle note' on the check_start()
848       method above.
849

STANDARD ARGUMENTS FOR RULE TYPES

851       Plugins will be called with the same arguments as a standard EvalTest.
852       Different rule types receive different information by default:
853
854       - header tests: no extra arguments
855       - body tests: fully rendered message as array reference
856       - rawbody tests: fully decoded message as array reference
857       - full tests: pristine message as scalar reference
858
859       The configuration file arguments will be passed in after the standard
860       arguments.
861

BACKWARD COMPATIBILITY

863       Note that if you write a plugin and need to determine if a particular
864       helper method is supported on "Mail::SpamAssassin::Plugin", you can do
865       this:
866
867           if ($self->can("name_of_method")) {
868             eval {
869               $self->name_of_method();        # etc.
870             }
871           } else {
872             # take fallback action
873           }
874
875       The same applies for the public APIs on objects of other types, such as
876       "Mail::SpamAssassin::PerMsgStatus".
877