5.8 Filtering functions

This section describes functions that transform data using Mailutils filter pipes. Filter pipe is a string defining data flow between several filters. Each filter takes input, transforms it according to certain rules and produces the transformed data on its output. As in shell, multiple filters are connected using pipe characters (‘|’). For example, the crlf filter inserts a carriage return character before each newline character. A filter doing that kind of transformation is defined as:

"crlf"

Another filter, base64, converts its input to a BASE64 encoded string. To transform each newline into carriage return + newline pair and encode the resulting stream in BASE64, one would write:

"crlf | base64"

Some filters take one or more arguments. These are specified as a comma-delimited list in parentheses after the filter name. For example, the linelen filter limits the length of each output line to the given number of octets. The following filter pipe will limit the length of base64 lines in the filter above to 62 octets:

"crlf | base64 | linelen(62)"

Many filters operate in two modes: encode and decode. By default all MFL functions apply filters in encode mode. The desired mode can be stated explicitly in the filter string by using encode() and decode() functions. They take a filter pipe line as their argument. For example, the following will decode the stream produced by the example filter above:

"decode(base64 | crlf)"

See Filters, for a discussion of available filters and their arguments.

Built-in Function: string filter_string (string input, string filter_pipe)

Transforms the string input using filters in filter_pipe and returns the result. Example:

set input "test\ninput\n"
filter_string(input, "crlf|base64") ⇒ "dGVzdA0KaW5wdXQNCg=="

Built-in Function: void filter_fd (number src_fd, number dst_fd, string filter_pipe)

Given two I/O descriptors, reads data from src_fd, transforms it using filter_pipe and writes the result to descriptor dst_fd.

Both descriptors must be obtained using functions described in I/O functions.