NAME Mail::Query - Write Mail::Audit criteria in SQL-like syntax SYNOPSIS use Mail::Query; my $mail = new Mail::Query; if ($mail->query('To LIKE /modperl/i')) { $mail->accept('lists/modperl'); } elsif ($mail->query('Recipient LIKE /ken@mathforum/i')) { $mail->accept('forum-mail'); } elsif ($mail->query("Precedence LIKE 'bulk%'")) { $mail->accept('lists/unknown'); } # Or put rules in a data structure: my @rules = ( 'lists/modperl' => 'To LIKE /modperl/i', 'forum-mail' => 'Recipient LIKE /ken@mathforum/i', 'lists/unknown' => "Precedence LIKE 'bulk%'", ); while (my ($mbox, $criteria) = splice @rules, 0, 2) { $mail->accept($mbox) if $mail->query($criteria); } DESCRIPTION The Mail::Query module adds a criteria-specifying language to the Mail::Audit class. Rather than inventing a new (probably ill-considered) language and making you learn it, Mail::Query uses SQL (Structured Query Language) as its starting point, because SQL is perfectly suited for writing arbitrarily complex boolean criteria in a fairly readable format. Mail::Query is a subclass of Mail::Audit, so any of Mail::Audit's methods are available on a Mail::Query object too. The full syntax of `WHERE' clauses is available when writing criteria, so you may join criteria with `AND' or `OR', using parentheses when necessary to specify precedence. You may negate criteria with `NOT'. See the SPECIFICS manpage for details on what various bits of SQL will mean about the email message you're examining. Currently, the left side of a comparison must be the name of a header field. This name can contain letters, numbers, the underscore character, and the hyphen character. The header name is analogous to a database column name. Two special pseudo-headers are defined - a `Recipient' pesudo-header contains the contents of the `To', `Cc', and `Bcc' headers, joined by commas, and a `Body' pseudo-header contains the body of the message. All other header names are passed through to `Mail::Audit''s `get()' method. SPECIFICS Here is what various SQL operators/identifiers mean. * <header> LIKE /regex/ Checks to see whether the given header matches the given regular expression. You may also use trailing regex modifiers like `/i'. Currently any `@' or `$' characters in the regular expression are escaped, which means you may write `To LIKE /ken@mathforum/' instead of `To LIKE /ken\@mathforum/'. If this doesn't suit your needs, let me know. * <header> LIKE 'spec' This is similar to the regular-expression form of `LIKE', but `'spec'' is a normal SQL `LIKE' string, not a full-blown regular expression. The `%' character is a wildcard matching zero or more unspecified characters, and all other characters just match themselves. * <header> = 'string' * <header> < 'string' * <header> > 'string' * <header> != 'string' * <header> <= 'string' * <header> >= 'string' Does a string-based comparison (using `eq', `lt', and so on) of the given header with the given string. Note that currently `Mail::Audit' doesn't trim whitespace off the end of a header value, so the value will usually contain a newline at the end. Keep this in mind when using the `=' operator (and consider using a `LIKE' clause instead). You may use any of Perl's string-quoting constructs for the `'string'', including `"string"', `'string'', `qq{string}', or `q{string}'. * <header> BETWEEN "string1" AND "string2" This does what you would expect, if you expect something sane. * <header> IS NULL / <header> IS NOT NULL Indicates the absence/presence of a certain header. MOTIVATION I was using Mail::Audit to filter my incoming mail, and I found that as I added more filtering rules, my filtering script got uglier and uglier. Lots of Perl `if' statements proliferated, and I found that the bulk of my code looked quite overwrought - I was supposedly using "the power of Perl" to write my criteria, but it was all `if's, `and's, and `or's. I tend not to like Perl code that uses lots of `if's, `and's, and `or's. Therefore, I decided to take all the filtering rules out of the code, and put them into a data structure that my main code could simply iterate over. However, the criteria didn't fit very easily into a data structure - I didn't relish the thought of translating arbitrarily complicated boolean criteria into some sort of nested data structure, nor did I look forward to looking at the structure later and trying to figure out what they meant. So I decided that we already had this perfectly adequate SQL language for specifying boolean criteria, which would let me flatten my criteria specifications into nice easily readable strings. CAVEATS I get a lot of mail (yes, we all do), but not so much that my mail filtering program needs to be particularly fast. Accordingly, I care much more about ease-of-use than execution speed. `Mail::Query' isn't very fast - it uses a full `Parse::RecDescent' grammar to parse the criteria statements and figure out whether the message matches. Even `Mail::Audit' isn't particularly fast when compared with something like procmail (though I haven't benchmarked it, since I don't really care very much), and `Mail::Query' is about one order slower yet. So don't expect it to handle several pieces of mail per second or anything. TO DO It would be nice to add some functions for use in criteria, like format_date(Date) < '2000-02-02' Once this is done, it would be trivial to let users define their own functions too. `Parse::RecDescent' has a way to pre-compile a grammar so that it doesn't have to be compiled every time the program is run. I'll probably do that in a future release so that the user doesn't have to install `Parse::RecDescent' either. It's fairly easy to do, but for (my) simplicity's sake I haven't done it yet. AUTHOR Ken Williams, ken@mathforum.org SEE ALSO perl(1), Mail::Audit(3)