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)