|Sign In||Sign Out||Subscribe to Mailing Lists||Unsubscribe or Change Settings||Help|
smoe.org mailing lists
Introduction to Patterns Patterns are used by various commands and configuration settings: By the archive-sync command, to match archive names. By the lists and rekey commands, to match list names. By the set-pattern, unregister-pattern, unsubscribe-pattern, which, and who commands, to match e-mail addresses. By the access_rules, advertise, bounce_probe_pattern, bounce_rules, delivery_rules, noadvertise, and post_limits settings, to match e-mail addresses. By the admin_body and taboo_body settings, to match lines in the body of a posted message. By the admin_headers and taboo_headers settings, to match lines in the headers of a posted message. By the attachment_filters and attachment_rules settings, to match message content types. By the quote_pattern setting, to count the lines in the body of a posted message that are marked as being written by someone else. By the signature_separator setting, to match the beginning of an e-mail signature. There are four supported types of pattern, described below: Substring Patterns, like "example" Glob Patterns, like %example% Regular Expressions, like /example/ Undelimited Patterns, like example Several examples of regular expressions are illustrated: Example 1 - a list of special characters Example 2 - escaping '.' is required Example 3 - escaping '@' is required Example 4 - matching the beginning and end of string Example 5 - matching anything and everything Example 6 - escaping '*' is required Example 7 - case sensitivity Example 8 - overly safe escaping doesn't hurt Example 9 - matching (or NOT matching) white space Example 10 - negated or inverted matches Majordomo is written in the Perl programming language. Perl regular expressions are a powerful but complicated tool for pattern matching. To eliminate some of the complexity, three simpler forms of pattern matching are provided, in addition to full Perl regular expressions. A pattern is usually enclosed in "delimiters," with optional "modifiers" outside the delimiters. The delimiters indicate where the pattern begins and ends, and the modifiers change how matches are found. For example, in the pattern: "example.net"i the delimiters are quotes, and the 'i' is a modifier. The most common modifier, the letter 'i', makes the matching case-insensitive, meaning that small and capital letters are considered identical. The negation modifier, '!', may be used to invert any of the four kinds of pattern. For example, !edu would match any string of characters that does not contain "edu". The special pattern ALL will match everything. Substring Patterns ------------------ Examples: "example.com" "email@example.com"i The delimiter is a double quote. There are no special characters; the pattern matches if the pattern occurs anywhere within the text to be matched. A trailing 'i' specifies that the matching is case-insensitive. For instance, "bsc" would match unsubscribe "bsc" would not match unsuBsCribe "bsc"i would match unsuBsCribe Glob Patterns ------------- Examples: %user@*example.com%i %u-???@*example.com%i The delimiter is a percent sign. These patterns are reminiscent of file-matching patterns from the DOS and Unix command line interfaces. Special characters include: ? matches any single character * matches any number (including zero) of any character.  are used to define character classes. For instance, [abc] will match any one of the letters a, b, or c. This style of grouping has the same effect as in regular expressions. Regular Expressions ------------------- What follows is a basic discussion of Perl regular expressions. There is one important difference between Majordomo regular expressions and Perl regular expressions: in Perl version 5 and above, the '@' character should be "escaped" with a backslash, \@. Majordomo will compensate if you forget to add the backslash, but for the sake of correctness you should always include it when you are trying to match a literal '@' symbol. Example 1 - a list of special characters A regular expression is a concise way of expressing a pattern in a series of characters. The full power of regular expressions can make some difficult tasks quite easy, but we will only brush the surface here. The character / is used to mark the beginning and end of a regular expression. Letters and numbers stand for themselves. Many of the other characters are symbolic. Some commonly used ones are: ! negates what follows, matching when the expression does NOT \@ the `@' found in nearly all addresses; it must be preceded by a backslash to avoid errors. . (period) any character * previous character, zero or more times; note especially... .* any character, zero or more times + previous character, one or more times; so for example... a+ letter "a", one or more times \ next character stands for itself; so for example... \. literally a period, not meaning "any character" ^ beginning of the string; so for example... ^a a string beginning with letter "a" $ end of the string; so for example... a$ a string ending with letter "a" Example 2 - escaping '.' is required /foo\.example\.com/ Notice that the periods are preceded by a backslash so that they are interpreted as periods, rather than wildcards. This matches any string containing: foo.example.com such as: foo.example.com bar.foo.example.com firstname.lastname@example.org email@example.com Example 3 - escaping '@' is required /johndoe\@.*foo\.example\.com/ The `@' has special meaning to Perl and should be prefixed with a backslash to avoid errors. The string ".*" means "any character, zero or more times". So this matches: firstname.lastname@example.org email@example.com firstname.lastname@example.org But it doesn't match: email@example.com firstname.lastname@example.org Example 4 - matching the beginning and end of string /^johndoe\@.*cs\.example\.org$/ This is similar to Example 4.3, and matches the same first two strings: email@example.com firstname.lastname@example.org But it doesn't match: email@example.com ...because the regular expression says the string has to begin with letter "j" and end with letter "g", by using the ^ and $ symbols, and neither of those is true for firstname.lastname@example.org@example.com. Example 5 - matching anything and everything /.*/ This is the regular expression that matches anything (any character, zero or more times). Example 6 - escaping '*' is required /.\*johndoe/ Here the * is preceded by a \, so it refers literally to an asterisk character and not the symbolic meaning "zero or more times". The '.' still has its symbolic meaning of "any one character", so it would match: a*johndoe s*johndoe Because the . by itself implies one character, it would not match: *johndoe Example 7 - case sensitivity Normally all matches are case sensitive; you can make any match case insensitive by appending an `i' to the end of the expression. /example\.com/i This would match example.com, EXAMPLE.com, ExAmPlE.cOm, etc. Removing the `i': /example\.com/ ...would match example.com but not EXAMPLE.com or any other capitalization. Example 8 - overly safe escaping doesn't hurt To be on the safe side put a \ in front of any characters in the regular expressions that are not numbers or letters. In order to put a / into the regular expression, the same rule holds: precede it with a \. Thus, with \ in front of the / and = characters, this: /\/CO\=US/ ...matches /CO=US and may be a useful regular expression to those of you who need to deal with X.400 addresses that contain / characters. Example 9 - matching (or NOT matching) white space Normally, all whitespace within a pattern is matched verbatim, but it is sometimes desirable to add some additional space within a pattern to make it more readable. For instance, here is a pattern matching some common quoting characters in email: /^(-|:|>|[a-z]+>)/i This can be a bit difficult to follow, so we can space it out a bit: /^( - | : | > | [a-z]+> )/xi The 'x' modifier specifies that whitespace is to be ignored, and makes the pattern a bit easier to read. If you want to match actual whitespace, use '\s'. Note that the 'x' modifier provides additional functionality to Perl code relating to comments, but because Majordomo requires patterns to lie all on a single line, this is not significant here. Example 10 - negated or inverted matches Negated matches (like !/^sub/) work in places where they have meaning, such as the taboo expression matcher which has lots of complicated logic to handle them, but not all places. Majordomo patterns just get sent through a function that turns them into regular expressions... which may or may not make sense in the context you want to use them. For example who-regexp listname !/xxx\.com/ will produce a list of subscribers to "listname" that are NOT from the 'xxx.com' domain. Be careful to escape the period, which otherwise will match any character, not just a period. Undelimited Patterns -------------------- In the previous sections, all of the patterns were considered to be enclosed in quotes, slashes, or percent signs. It is legitimate to use patterns without enclosing them in those delimiters in some cases. However, the kind of matching done will depend upon where the pattern is used. In the archive-sync command, an exact match. In the lists and rekey commands, an exact, case-insensitive match. In the which and who commands, a case-insensitive substring match. In the attachment_filters setting, an exact, case-insensitive match. In the attachment_rules setting, an exact, case-insensitive match. In the post_limits setting, a case-insensitive substring match. In all of the other cases mentioned in the first section, pattern delimiters are required. Using a pattern without delimiters will cause an error. See Also: help admin help archive help configset_access_rules help configset_advertise help configset_admin_body help configset_admin_headers help configset_attachment_filters help configset_attachment_rules help configset_bounce_probe_pattern help configset_bounce_rules help configset_delivery_rules help configset_noadvertise help configset_post_limits help configset_quote_pattern help configset_signature_separator help configset_taboo_body help configset_taboo_headers help lists help overview help rekey help set help unregister help unsubscribe help which help who This is the "patterns" help document for Majordomo 2, version 0.1200401130. For a list of all help documents, send the following command: help topics in the body of a message to email@example.com.
For assistance, please contact the smoe.org administrators.
|Sign In||Sign Out||Subscribe to Mailing Lists||Unsubscribe or Change Settings||Help|