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