2013-02-28 [mones] 3.9.0cvs105
[claws.git] / src / plugins / perl / cm_perl.pod
1 =head1 NAME
2
3 cm_perl -- A Perl Plugin for Claws Mail
4
5
6 =head1 DESCRIPTION
7
8 This plugin provides an extended filtering engine for the email
9 client Claws Mail. It allows for the use of full Perl power
10 in email filters.
11
12 =head1 QUICK START
13
14 To get started, you can use the B<matcherrc2perlfilter.pl> script
15 in the B<tools>-directory to translate your old filtering rules to
16 Perl. Simply execute the script and follow the instructions.
17 (note that with recent versions of Claws Mail, this script might not
18 work due to upstream syntax changes. This will get updated in the
19 future. Send me an email if you have problems getting started).
20
21 However, you might want to consider reading the rest of this
22 manual and rewriting your rules if you choose to use the plugin,
23 since the Perl code produced by this script is not exactly
24 pretty.
25
26 Don't speak Perl? No problem, L<"perldoc perlintro"|perlintro>
27 should give you enough information to do fancy stuff.
28
29 =head1 USAGE
30
31 The Perl plugin expects a Perl script file called B<perl_filter>
32 in Claws Mail' config directory (usually $HOME/.claws-mail --
33 try `claws-mail --config-dir' if you're unsure). If that file
34 doesn't exist on plugin start, an empty one is created.  This
35 file, which doesn't need to start with a sha-bang (!#/bin/perl),
36 holds the Perl instructions for your email filters. To encourage
37 some good manners, the code is executed in a C<use strict;>
38 environment.
39
40 Both Claws Mail' filtering B<conditions> and B<actions> are
41 mapped to Perl functions with corresponding names, wherever this
42 is possible.
43
44 =head1 FUNCTION LISTING
45
46 For a detailed function description, see section L</"FUNCTION
47 DESCRIPTIONS">, below.
48
49 =over 4
50
51 =item Standard Filtering Conditions
52
53  all, marked, unread, deleted, new, replied,
54  forwarded, locked, ignore_thread, colorlabel,
55  match, matchcase, regexp, S<regexpcase, test,
56  size_greater, size_smaller, size_equal,
57  score_greater, score_lower, score_equal, age_greater,
58  age_lower, partial, tagged
59
60 =item Standard Filtering Actions
61
62  mark, unmark, dele, mark_as_unread, mark_as_read,
63  lock, unlock, move, copy, color, execute,
64  hide, set_score, change_score, stop, forward,
65  forward_as_attachment, redirect, set_tag, unset_tag,
66  clear_tags
67
68 =item Fun stuff
69
70  header, body, filepath, extract_addresses,
71  move_to_trash, abort, addr_in_addressbook,
72  from_in_addressbook, get_attribute_value, SA_is_spam,
73  exit, manual, make_sure_folder_exists,
74  filter_log, filter_log_verbosity,
75  make_sure_tag_exists
76
77 =back
78
79 =head1 FUNCTION DESCRIPTIONS
80
81 In general, after the filtering invoked by the Perl script, the
82 mail is passed on to Claws' internal filtering engine, I<unless>
83 a B<final> rule was hit. Final rules stop not only the Perl
84 filtering script at the point of their occurence, but also
85 prevent processing that email by Claws' internal filtering engine
86 (this might sound confusing, but you are already familiar with
87 that concept from standard filters: After an email was
88 e.g. I<move>d, the following rules don't apply anymore).
89
90 Also, be careful with the way you quote. In particular, remember
91 that the @-sign has a special meaning in Perl, and gets
92 interpolated inside double quotes. See L<perlop/"Quote and
93 Quote-like Operators"> to learn more about quoting and
94 interpolation.
95
96
97 =head2 Standard Filtering Conditions
98
99 =over 8
100
101 =item all
102
103 Returns a true value. Available for completness only.
104
105 =item marked
106
107 Returns a true value if the marked flag is set, false otherwise.
108
109 =item unread
110
111 Returns a true value if the unread flag is set, false otherwise.
112
113 =item deleted
114
115 Returns a true value if the deleted flag is set, false otherwise.
116
117 =item new
118
119 Returns a true value if the new flag is set, false otherwise.
120
121 =item replied
122
123 Returns a true value if the replied flag is set, false otherwise.
124
125 =item forwarded
126
127 Returns a true value if the forwarded flag is set, false otherwise.
128
129 =item locked
130
131 Returns a true value if the locked flag is set, false otherwise.
132
133 =item ignore_thread
134
135 Returns a true value if the "Ignore Thread" flag is set, false otherwise.
136
137 =item colorlabel COLOR
138
139 =item colorlabel
140
141 Returns a true value if message has the color COLOR. COLOR can be
142 either a numeric value between 0 and 7 (with colors corresponding
143 to the internal filtering engine), or the english color name as
144 it is introduced in the filtering dialog (that is, one of: none,
145 orange, red, pink, sky blue, blue, green or brown, while upper
146 and lower case letters make no difference). If COLOR is omitted,
147 0 (none) is assumed.
148
149 =item size_greater SIZE
150
151 Returns a true value if message size is greater than SIZE, false otherwise.
152
153 =item size_smaller SIZE
154
155 Returns a true value if message size is smaller than SIZE, false otherwise.
156
157 =item size_equal SIZE
158
159 Returns a true value if message size is equal to SIZE, false otherwise.
160
161 =item score_greater SCORE
162
163 Returns a true value if message score is greater than SCORE, false otherwise.
164
165 =item score_lower SCORE
166
167 Returns a true value if message score is lower than SCORE, false otherwise.
168
169 =item score_equal SCORE
170
171 Returns a true value if message score is equal to SCORE, false otherwise.
172
173 =item age_greater AGE
174
175 Returns a true value if message age is greater than AGE, false otherwise.
176
177 =item age_lower AGE
178
179 Returns a true value if message age is lower than AGE, false otherwise.
180
181 =item partial
182
183 Returns a true value if message has only partially been
184 downloaded, false otherwise.
185
186 =item tagged
187
188 Returns a true value if the messages has one or more tags.
189
190 =item test
191
192 Corresponds the 'test' internal filtering rule. In particular, it
193 accepts the same symbols, namely:
194
195 =over 
196
197 =item %%
198
199 %
200
201 =item %s
202
203 Subject
204
205 =item %f
206
207 From
208
209 =item %t
210
211 To
212
213 =item %c
214
215 Cc
216
217 =item %d
218
219 Date
220
221 =item %i
222
223 Message-ID
224
225 =item %n
226
227 Newsgroups
228
229 =item %r
230
231 References
232
233 =item %F
234
235 Filename -- should not be modified
236
237 =back
238
239 =item match WHERE WHAT
240
241 =item matchcase WHERE WHAT
242
243 =item regexp WHERE WHAT
244
245 =item regexpcase WHERE WHAT
246
247 The matching functions have a special syntax. The first argument
248 is either any of to_or_cc, body_part, headers_part, message, to,
249 from, subject, cc, newsgroups, inreplyto, references, or tag (those
250 strings may or may not be quoted), the patter matching works on
251 that area. If it is any other string (which must then be quoted),
252 this string is taken to be the name of a header field.
253
254 The second argument is the string to look for. For match,
255 matchcase, regexp and regexpcase we have case sensitive normal
256 matching, case insensitive normal matching, case sensitive
257 regular expression matching and case insensitive regular
258 expression pattern matching, respectively.
259
260 The functions return true if the pattern was found, false
261 otherwise.
262
263 Just as with the built-in filtering engine, the message body is
264 searched and provided as is - no character-set analysis is
265 done. Likewise, no HTML-tags are stripped. It should be possible
266 to use external modules or programs for these tasks though. If
267 you're doing that, drop me a message with your experiences.
268
269 With Perl having its strenghts in pattern matching, using Perl's
270 builtin operators are usually a better option than using these
271 functions.
272
273 =back
274
275 =head2 Standard Filtering Actions
276
277 The actions return a true value upon success, and 'undef' when an
278 error occured. I<Final> message rules are indicated. (See above
279 for a sketch what a final rule is)
280
281 =over 8
282
283 =item mark
284
285 Mark the message.
286
287 =item unmark
288
289 Unmark the message.
290
291 =item dele
292
293 Delete the message. Note the name change of Claws Mail'
294 "delete" to "dele". This is because "delete" is one of Perl's
295 builtin commands which cannot be redefined (if it can, tell me
296 how).
297
298 This is a I<final> rule.
299
300 =item mark_as_read
301
302 Mark the message as read 
303
304 =item mark_as_unread
305
306 Mark the message as unread
307
308 =item lock
309
310 Lock the message
311
312 =item unlock
313
314 Remove the message lock
315
316 =item move DESTINATION
317
318 Move the message to folder DESTINATION. The folder notation is
319 the same that Claws Mail uses. You can copy & paste from the
320 move dialog of the normal filtering, until you get a feeling for
321 the notation.
322
323 This is a I<final> rule.
324
325 =item copy DESTINATION
326
327 Copy the message to folder DESTINATION. The folder notation is
328 the same that Claws Mail uses. You can copy & paste from the
329 move dialog of the normal filtering, until you get a feeling for
330 the notation.
331
332 =item execute COMMAND
333
334 This is the same as the test - rule from section L</"Standard
335 Filtering Conditions"> execpt that it always returns a true
336 value.
337
338 =item hide
339
340 Hide the message
341
342 =item set_score SCORE
343
344 Set message score to SCORE
345
346 =item change_score SCORE
347
348 Change message score by SCORE
349
350 =item stop
351
352 Stop Perl script at this point. Note that this is B<not> a final
353 rule, meaning that the email gets passed on to the internal
354 filtering engine. See "abort" below if you don't want that.
355
356 =item forward ACCOUNT, EMAIL
357
358 Forward the message to email address EMAIL, using the account ID
359 ACCOUNT as sender account. So far, you have to create a rule
360 in the normal filtering engine to find out that number.
361
362 =item forward_as_attachment, ACCOUNT EMAIL
363
364 Forward the message to email address EMAIL in an attachment,
365 using the account ID ACCOUNT as sender account. So far, you
366 have to create a rule in the normal filtering engine to find out
367 that number.
368
369 =item redirect ACCOUNT, EMAIL
370
371 Redirect the message to EMAIL, using the account ID ACCOUNT as
372 sender account. So far, you have to create a rule in the normal
373 filtering engine to find out that number.
374
375 =item set_tag TAG
376
377 Apply tag TAG. TAG must exist.
378
379 =item unset_tag TAG
380
381 Unset tag TAG.
382
383 =item clear_tags
384
385 Clear all tags.
386
387 =back
388
389 =head2 Fun stuff
390
391 =head3 Functions
392
393 =over 8
394
395 =item header ARG
396
397 =item header
398
399 If ARG is not given, returns a list of all header field names of
400 the mail.
401
402 If ARG is given, returns 'undef' if the header field ARG does not
403 exist in the email. Otherwise, it returns
404
405 =over
406
407 =item in scalar context
408
409 The value of the header field ARG.
410
411 =item in list context
412
413 A list of all available header field values. This is useful if a
414 header field occurs more than once in an email (eg the Received -
415 header).
416
417 =back
418
419 The header field "References" forms a special case. In a scalar context,
420 it returns the first reference. In a list context, it returns a list of
421 all references.
422
423 =item body
424
425 Returns the email body in a scalar.
426
427 =item filepath
428
429 Returns the file and path of the email that is currently filtered
430 (corresponds to the %F arguemnt in the 'test' rule).
431
432 =item extract_addresses
433
434 Extracts email addresses from a string and gives back a list of
435 addresses found. Currently an email address is found using the
436 regular expression '[-.+\w]+\@[-.+\w]+'. This will not find all
437 valid email addresses. Feel free to send me a better regexp.
438
439 =item move_to_trash
440
441 Move the email message to default trash folder.
442
443 This is a I<final> rule.
444
445 =item abort
446
447 Stop Perl script at this point.
448
449 In contrast to 'stop', this is a I<final> rule.
450
451 =item addr_in_addressbook EMAIL, ADDRESSBOOK
452
453 =item addr_in_addressbook EMAIL
454
455 Returns a true value if the email address EMAIL is in the addressbook
456 with the name ADDRESSBOOK. If ADDRESSBOOK is not given, returns
457 true if the email address is in any addressbook.
458
459 =item from_in_addressbook ADDRESSBOOK
460
461 =item from_in_addressbook
462
463 Checks if the email address found in the From-header is in
464 addressbook ADDRESSBOOK (or any, if omitted). It is implemented
465 as
466
467  my ($from) = extract_addresses(header("from"));
468  return 0 unless $from;
469  return addr_in_addressbook($from,@_);
470
471 so the same restrictions as to extract_addresses apply.
472
473 =item get_attribute_value EMAIL, ATTRIBUTE, ADDRESSBOOK
474
475 =item get_attribute_value EMAIL, ATTRIBUTE
476
477 Looks through the addressbook ADDRESSBOOK (or all addressbooks,
478 if omitted) for a contact with the an email address EMAIL. If
479 found, the function checks if this contact has a user attribute
480 with name ATTRIBUTE. It returns the value of this attribute, or
481 an empty string if it was not found. As usual, 'undef' is
482 returned if an error occured.
483
484 =item SA_is_spam
485
486 Is an alias to
487
488 not test 'spamc -c < %F > /dev/null'
489
490 =item exit
491
492 Has been redefined to be an alias to 'stop'. You shouldn't use
493 Perl's own 'exit' command, since it would exit Claws Mail.
494
495 =item manual
496
497 Returns a true value if the filter script was invoked manually,
498 that is, via the Tools menu.
499
500 =item make_sure_folder_exists IDENTIFIER
501
502 Returns a true value if the folder with id IDENTIFIER (e.g. #mh/Mail/foo/bar)
503 exists or could be created.
504
505 =item make_sure_tag_exists TAG
506
507 Returns a true value if the tag TAG exists or could be created.
508
509 =item filter_log SECTION, TEXT
510
511 =item filter_log TEXT
512
513 Writes TEXT to the filter logfile. SECTION can be any of
514
515 =over
516
517 =item *
518
519 "LOG_MANUAL"
520
521 =item *
522
523 "LOG_MATCH"
524
525 =item *
526
527 "LOG_ACTION"
528
529 =back
530
531 If the SECTION is omitted, "LOG_MANUAL" is assumed.
532
533 =item filter_log_verbosity VERBOSITY
534
535 =item filter_log_verbosity
536
537 Changes the filter log verbosity for the current mail. VERBOSITY
538 must be any of
539
540 =over
541
542 =item *
543
544 0
545
546 =item *
547
548 1
549
550 =item *
551
552 2
553
554 =item *
555
556 3
557
558 =back
559
560 For the meaning of those numbers, read section L</"LOGGING">. If
561 VERBOSITY is omitted, the filter logfile verbosity is not changed.
562
563 This function returns the filter_log_verbosity number before the
564 change (if any).
565
566 =back
567
568 =head3 Variables
569
570 =over 8
571
572 =item $permanent
573
574 This scalar keeps its value between filtered mail messages. On
575 plugin start, it is initialized to the empty string.
576
577 =back
578
579 =head1 LOGGING
580
581 To keep track of what has been done to the mails while filtering,
582 the plugin supports logging. Three verbosity levels are
583 recognized:
584
585 =over
586
587 =item 0
588
589 logging disabled
590
591 =item 1
592
593 log only manual messages, that is, messages introduced by the
594 C<filter_log> command in filter scripts
595
596 =item 2
597
598 log manual messages and filter actions
599
600 =item 3
601
602 log manual messages, filter actions and filter matches
603
604 =back
605
606 The messages are logged in Claws Mail' log window.
607 The default log level is 2. Log level 3 is not
608 recommended, because the matcher functions log a message if they
609 succeeded, and thus, if you have negative checks, you'll get
610 confusing entries. If you want to keep track of matching, do it
611 manually, using C<filter_log>, or do it by temporary enabling
612 matcher logging using C<filter_log_verbosity>.
613
614 The first time you unload this plugin (or shut down
615 Claws Mail), a section called B<[PerlPlugin]> will be created
616 in Claws Mail' configuration file B<clawsrc>, containing
617 one variable:
618
619  * filter_log_verbosity
620
621 If you want to change the default behaviour, you can edit this
622 line. Make sure Claws Mail is not running while you do
623 this.
624
625 It will be possible to access these setting via the GUI, as soon
626 as I find the time to write a corresponding GTK plugin, or
627 somebody else is interested in contributing that.
628
629 =head1 EXAMPLE
630
631 This section lists a small example of a Perl script file. I'm
632 sure you get the idea..
633
634  #-8<----------------------------------------------------
635  # -*- perl -*-
636  
637  # local functions
638  
639  # Learn ham messages, and move them to specified folder. This is
640  # useful for making sure a bayes filter sees ham as well.
641  sub learn_and_move {
642      execute('put command to learn ham here');
643      move(@_);
644  }
645  
646  # Two-stage spam filter. Every email that scores higher than 15
647  # on SpamAssassin gets moved into the default trash folder.
648  # All mails lower than that, but higher than SpamAssassin's
649  # 'required_hits' go into  #mh/mail/Spam.
650  sub spamcheck {
651      my $surely_spam = 15;
652      my $filepath = filepath;
653      my $spamc = `spamc -c < $filepath`;
654      my ($value,$threshold) = ($spamc =~ m|([-.,0-9]+)/([-.,0-9]+)|);
655      if($value >= $surely_spam) {
656         mark_as_read;
657         move_to_trash;
658      }
659      if($value >= $threshold) {mark_as_read; move '#mh/mail/Spam';}
660  }
661  
662  # Perl script execution starts here.
663  
664  # Some specific sorting
665  learn_and_move '#mh/mail/MailLists/Claws Mail/user'
666    if matchcase('sender','claws-mail-users-admin@lists.sourceforge.net');
667  learn_and_move '#mh/mail/MailLists/Sylpheed'
668    if matchcase('list-id','sylpheed.good-day.net');
669  
670  # Implement imcomming folders using addressbook
671  # attributes. Target folders for specific email addresses are
672  # stored directly in the addressbook. This way, if an email
673  # address changes, we only have to update the addressbook, not
674  # the filter rules! Besides that, we can greatly unclutter the
675  # filter script.
676
677  # get the email address in the from header
678  my $fromheader = header "from";
679  my ($from) = extract_addresses $fromheader;
680
681  # check if this email address has an associated attribute
682  # called "incomming_folder". If if has, the value of this
683  # attribute is supposed to be the target folder.
684  my $value = get_attribute_value $from, "incomming_folder";
685  learn_and_move($value) if $value;
686
687  # An example of a whitelist: If the from-address is in my
688  # "office" addressbook, move the mail to folder #mh/mail/office
689  learn_and_move '#mh/mail/office' if from_in_addressbook("office");
690  
691  # If the from-address is in any other addressbook, move the
692  # mail to folder #mh/mail/inbox/known
693  learn_and_move '#mh/mail/inbox/known' if from_in_addressbook;
694
695  # Feed the remaining mails through SpamAssassin.
696  spamcheck;
697
698  # mails that make it to the end of the script are passed on to
699  # the internal filtering engine. If the internal rules don't say
700  # otherwise, the mails end up in the default inbox.
701  #-8<----------------------------------------------------
702
703
704 =head1 BUGS
705
706 =over 4
707
708 =item *
709
710 Do B<not> use this plugin together with other filtering plugins,
711 especially the B<Spamassassin> and B<ClamAV> plugins. They are
712 registered on the same hook and the order in which the plugins
713 are executed is not guaranteed.
714
715 =item *
716
717 The filter script is not (yet) updated automatically when a
718 folder gets renamed. The same applies for folder names in
719 addressbook user attributes.
720
721 =item *
722
723 This plugin has only be tested with POP3 accounts. If you have
724 experiences with IMAP or newsgroup accounts, drop me a message.
725
726 =item *
727
728 Warning during compile time:
729
730  *** Warning: Linking the shared library perl_plugin.la against the
731  *** static library
732  /usr/lib/perl5/5.8.3/i586-linux-thread-multi/auto/DynaLoader/DynaLoader.a
733  is not portable!
734
735 Ideas to solve this one are welcome :-)
736
737 =back
738
739 Please report comments, suggestions and bugreports to the address
740 given in the L</AUTHOR> section of this document.
741
742
743 =head1 LICENSE and (no) WARRANTY
744
745 This program is free software; you can redistribute it and/or
746 modify it under the terms of the GNU General Public
747 License as published by the Free Software Foundation;
748 either version 3 of the License, or (at your option) any later
749 version.
750
751 This program is distributed in the hope that it will be useful,
752 but WITHOUT ANY WARRANTY; without even the implied warranty of
753 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
754 GNU General Public License for more details.
755
756 You should have received a copy of the GNU General Public License
757 along with this program. If not, see http://www.gnu.org/licenses/.
758
759 =head1 SEE ALSO
760
761 claws-mail(1), perl(1)
762
763
764 =head1 AUTHOR
765
766 Holger Berndt  <berndth@gmx.de>
767
768 =cut