src/plugins/perl/cm_perl.pod

   1 =head1 NAME
   2
   3 cm_perl -- A Perl Plugin for Claws Mail
   4
   5 =head1 DESCRIPTION
   6
   7 This plugin provides an extended filtering engine for the email
   8 client Claws Mail. It allows for the use of full Perl power
   9 in email filters.
  10
  11 =head1 QUICK START
  12
  13 To get started, you can use the B<matcherrc2perlfilter.pl> script
  14 in the B<tools>-directory to translate your old filtering rules to
  15 Perl. Simply execute the script and follow the instructions.
  16 (note that with recent versions of Claws Mail, this script might not
  17 work due to upstream syntax changes. This will get updated in the
  18 future. Send me an email if you have problems getting started).
  19
  20 However, you might want to consider reading the rest of this
  21 manual and rewriting your rules if you choose to use the plugin,
  22 since the Perl code produced by this script is not exactly
  23 pretty.
  24
  25 Don't speak Perl? No problem, L<"perldoc perlintro"|perlintro>
  26 should give you enough information to do fancy stuff.
  27
  28 =head1 USAGE
  29
  30 The Perl plugin expects a Perl script file called B<perl_filter>
  31 in Claws Mail' config directory (usually $HOME/.claws-mail --
  32 try `claws-mail --config-dir' if you're unsure). If that file
  33 doesn't exist on plugin start, an empty one is created.  This
  34 file, which doesn't need to start with a sha-bang (!#/bin/perl),
  35 holds the Perl instructions for your email filters. To encourage
  36 some good manners, the code is executed in a C<use strict;>
  37 environment.
  38
  39 Both Claws Mail' filtering B<conditions> and B<actions> are
  40 mapped to Perl functions with corresponding names, wherever this
  41 is possible.
  42
  43 =head1 FUNCTION LISTING
  44
  45 For a detailed function description, see section L</"FUNCTION
  46 DESCRIPTIONS">, below.
  47
  48 =over 4
  49
  50 =item Standard Filtering Conditions
  51
  52  all, marked, unread, deleted, new, replied,
  53  forwarded, locked, ignore_thread, colorlabel,
  54  match, matchcase, regexp, S<regexpcase, test,
  55  size_greater, size_smaller, size_equal,
  56  score_greater, score_lower, score_equal, age_greater,
  57  age_lower, partial, tagged
  58
  59 =item Standard Filtering Actions
  60
  61  mark, unmark, dele, mark_as_unread, mark_as_read,
  62  lock, unlock, move, copy, color, execute,
  63  hide, set_score, change_score, stop, forward,
  64  forward_as_attachment, redirect, set_tag, unset_tag,
  65  clear_tags
  66
  67 =item Fun stuff
  68
  69  header, body, filepath, extract_addresses,
  70  move_to_trash, abort, addr_in_addressbook,
  71  from_in_addressbook, get_attribute_value, SA_is_spam,
  72  exit, manual, make_sure_folder_exists,
  73  filter_log, filter_log_verbosity,
  74  make_sure_tag_exists
  75
  76 =back
  77
  78 =head1 FUNCTION DESCRIPTIONS
  79
  80 In general, after the filtering invoked by the Perl script, the
  81 mail is passed on to Claws' internal filtering engine, I<unless>
  82 a B<final> rule was hit. Final rules stop not only the Perl
  83 filtering script at the point of their occurrence, but also
  84 prevent processing that email by Claws' internal filtering engine
  85 (this might sound confusing, but you are already familiar with
  86 that concept from standard filters: After an email was
  87 e.g. I<move>d, the following rules don't apply anymore).
  88
  89 Also, be careful with the way you quote. In particular, remember
  90 that the @-sign has a special meaning in Perl, and gets
  91 interpolated inside double quotes. See L<perlop/"Quote and
  92 Quote-like Operators"> to learn more about quoting and
  93 interpolation.
  94
  95
  96 =head2 Standard Filtering Conditions
  97
  98 =over 8
  99
 100 =item all
 101
 102 Returns a true value. Available for completeness only.
 103
 104 =item marked
 105
 106 Returns a true value if the marked flag is set, false otherwise.
 107
 108 =item unread
 109
 110 Returns a true value if the unread flag is set, false otherwise.
 111
 112 =item deleted
 113
 114 Returns a true value if the deleted flag is set, false otherwise.
 115
 116 =item new
 117
 118 Returns a true value if the new flag is set, false otherwise.
 119
 120 =item replied
 121
 122 Returns a true value if the replied flag is set, false otherwise.
 123
 124 =item forwarded
 125
 126 Returns a true value if the forwarded flag is set, false otherwise.
 127
 128 =item locked
 129
 130 Returns a true value if the locked flag is set, false otherwise.
 131
 132 =item ignore_thread
 133
 134 Returns a true value if the "Ignore Thread" flag is set, false otherwise.
 135
 136 =item colorlabel COLOR
 137
 138 =item colorlabel
 139
 140 Returns a true value if message has the color COLOR. COLOR can be
 141 either a numeric value between 0 and 7 (with colors corresponding
 142 to the internal filtering engine), or the english color name as
 143 it is introduced in the filtering dialog (that is, one of: none,
 144 orange, red, pink, sky blue, blue, green or brown, while upper
 145 and lower case letters make no difference). If COLOR is omitted,
 146 0 (none) is assumed.
 147
 148 =item size_greater SIZE
 149
 150 Returns a true value if message size is greater than SIZE, false otherwise.
 151
 152 =item size_smaller SIZE
 153
 154 Returns a true value if message size is smaller than SIZE, false otherwise.
 155
 156 =item size_equal SIZE
 157
 158 Returns a true value if message size is equal to SIZE, false otherwise.
 159
 160 =item score_greater SCORE
 161
 162 Returns a true value if message score is greater than SCORE, false otherwise.
 163
 164 =item score_lower SCORE
 165
 166 Returns a true value if message score is lower than SCORE, false otherwise.
 167
 168 =item score_equal SCORE
 169
 170 Returns a true value if message score is equal to SCORE, false otherwise.
 171
 172 =item age_greater AGE
 173
 174 Returns a true value if message age is greater than AGE, false otherwise.
 175
 176 =item age_lower AGE
 177
 178 Returns a true value if message age is lower than AGE, false otherwise.
 179
 180 =item partial
 181
 182 Returns a true value if message has only partially been
 183 downloaded, false otherwise.
 184
 185 =item tagged
 186
 187 Returns a true value if the messages has one or more tags.
 188
 189 =item test
 190
 191 Corresponds the 'test' internal filtering rule. In particular, it
 192 accepts the same symbols, namely:
 193
 194 =over
 195
 196 =item %%
 197
 198 %
 199
 200 =item %s
 201
 202 Subject
 203
 204 =item %f
 205
 206 From
 207
 208 =item %t
 209
 210 To
 211
 212 =item %c
 213
 214 Cc
 215
 216 =item %d
 217
 218 Date
 219
 220 =item %i
 221
 222 Message-ID
 223
 224 =item %n
 225
 226 Newsgroups
 227
 228 =item %r
 229
 230 References
 231
 232 =item %F
 233
 234 Filename -- should not be modified
 235
 236 =back
 237
 238 =item match WHERE WHAT
 239
 240 =item matchcase WHERE WHAT
 241
 242 =item regexp WHERE WHAT
 243
 244 =item regexpcase WHERE WHAT
 245
 246 The matching functions have a special syntax. The first argument
 247 is either any of to_or_cc, body_part, headers_part, headers_cont,
 248 message, to, from, subject, cc, newsgroups, inreplyto,
 249 references, or tag (those strings may or may not be quoted), the
 250 pattern matching works on that area. If it is any other string
 251 (which must then be quoted), this string is taken to be the name
 252 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 strengths 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 occurred. 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 occurred.
 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 2
 541
 542 =item C<0>
 543
 544 Be silent
 545
 546 =item C<1>
 547
 548 Log MANUAL type
 549
 550 =item C<2>
 551
 552 Log Action type
 553
 554 =item C<3>
 555
 556 Log MATCH type
 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 C<0>
 588
 589 logging disabled
 590
 591 =item C<1>
 592
 593 log only manual messages, that is, messages introduced by the
 594 C<filter_log> command in filter scripts
 595
 596 =item C<2>
 597
 598 log manual messages and filter actions
 599
 600 =item C<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 incoming 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 "incoming_folder". If if has, the value of this
 683  # attribute is supposed to be the target folder.
 684  my $value = get_attribute_value $from, "incoming_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