2 Basic Usage

To load mfmod_pcre into your MFL program, first make sure that mailfromd search path (see include search path in Mailfromd Manual) contains directory where the pcre.mf interface file is installed and search path for dynamically loaded modules (see mfmod-path in Mailfromd Manual) contains directory where the loaded library mfmod_pcre.so resides. Once these prerequisites are met, add the require statement:

require 'pcre'

Now you can use Perl-compatible regexps in your code.

Names of all functions exported by the module begin with the pcre_ prefix. For example, pcre_string_matches checks whether its second argument matches a regular expression supplied as its first argument. The function returns true (1) if the string matches the expression, and false (0) otherwise. E.g.:

if pcre_string_matches('.+?@.+', address)
  # do something with address
fi

This function suits for casual use, but you should be aware of its drawbacks. First, it compiles regular expression on each call, which hurts performance. Secondly, while it allows to use capturing groups in regex, it provides no way to retrieve matched substrings.

The function pcre_string_match is free from the second limitation. If the string matches, this function returns a match descriptor, a positive integer value describing the match. This value can then be used with other functions to retrieve information about the match. For example, pcre_numbered_substring retrieves the captured string:

set mh pcre_string_match('(\d+)\s+(.+?)\s+(\S+@\S+)', input_line)
if mh
  # Regular expression matches
  echo "Ordinal number: " . pcre_numbered_substring(mh, 1)
  echo "Personal part: " . pcre_numbered_substring(mh, 2)
  echo "Email: " . pcre_numbered_substring(mh, 3)

  pcre_match_free(mh)
else
  # Expression doesn't match
fi

Notice the use of pcre_match_free: when no longer needed, match descriptor should be disposed of using this function.

A similar function pcre_named_substring is provided to retrieve named captured groups.

Both numbered and named groups can be expanded within a string using the pcre_expand function. Numbered groups are referred to as $n and named ones as $+{name}. For example:

set mh pcre_string_match('(?<ord>\d+)\s+(?<personal>.+?)\s+(?<email>\S+@\S+)', input_line)
if mh
  # Regular expression matches
  set printable_email pcre_expand(mh, '"$+{personal}" <$+{email}>')
  pcre_match_free(mh)
fi

However, pcre_string_match still suffers from the first limitation: it compiles the regular expression on each call. To overcome this limitation, use precompiled regular expressions.

The function pcre_compile compiles the regexp given as its argument and returns regexp descriptor, a numeric value that is used to refer to that expression in other pcre_ calls:

number rx pcre_compile('(\d+)\s+(.+?)\s+(\S+@\S+)')

Thus, a regexp can be compiled once (e.g. in the begin section) and then used as many times as needed. A set of functions is provided to use precompiled regexps. For example, pcre_matches and pcre_match are similar to the functions discussed above, except that they take regexp descriptor as their first argument:

number rx pcre_compile('(\d+)\s+(.+?)\s+(\S+@\S+)')
set mh pcre_match(rx, input_line)
if mh
  # Regular expression matches
  set printable_email pcre_expand(mh, '"$2" <$3>')
  pcre_match_free(mh)
fi