To contents Next section

14.11.1 Global functions

FUNCTION
MIME.decode - Remove transfer encoding

SYNTAX
string decode(string data, string encoding);

DESCRIPTION
Extract raw data from an encoded string suitable for transport between systems. The encoding can be any of
  • 7bit
  • 8bit
  • base64
  • binary
  • quoted-printable
  • x-uue
  • x-uuencode
The encoding string is not case sensitive.

SEE ALSO
MIME.encode

FUNCTION
MIME.decode_base64 - Decode <tt>base64</tt> transfer encoding

SYNTAX
string decode_base64(string encoded_data);

DESCRIPTION
This function decodes data encoded using the base64 transfer encoding.

SEE ALSO
MIME.encode_base64

FUNCTION
MIME.decode_qp - Decode <tt>quoted-printable</tt> transfer encoding

SYNTAX
string decode_qp(string encoded_data);

DESCRIPTION
This function decodes data encoded using the quoted-printable (a.k.a. quoted-unreadable) transfer encoding.

SEE ALSO
MIME.encode_qp

FUNCTION
MIME.decode_uue - Decode <tt>x-uue</tt> transfer encoding

SYNTAX
string decode_uue(string encoded_data);

DESCRIPTION
This function decodes data encoded using the x-uue transfer encoding. It can also be used to decode generic UUEncoded files.

SEE ALSO
MIME.encode_uue

FUNCTION
MIME.decode_word - De-scramble RFC1522 encoding

SYNTAX
array(string) decode_word(string word);

DESCRIPTION
Extracts the textual content and character set from an encoded word as specified by RFC1522. The result is an array where the first element is the raw text, and the second element the name of the character set. If the input string is not an encoded word, the result is still an array, but the char set element will be set to 0. Note that this function can only be applied to individual encoded words.

EXAMPLE 
> Array.map("=?iso-8859-1?b?S2lscm95?= was =?us-ascii?q?h=65re?="/" ",
                        MIME.decode_word);
Result: ({ /* 3 elements */
        ({ /* 2 elements */
                "Kilroy",
                "iso-8859-1"
        }),
        ({ /* 2 elements */
                "was",
                0
        }),
        ({ /* 2 elements */
                "here",
                "us-ascii"
        })
})

SEE ALSO
MIME.encode_word

FUNCTION
MIME.encode - Apply transfer encoding

SYNTAX
string encode(string data, string encoding,
void|string filename,
void|int no_linebreaks);

DESCRIPTION
Encode raw data into something suitable for transport to other systems. The encoding can be any of
  • 7bit
  • 8bit
  • base64
  • binary
  • quoted-printable
  • x-uue
  • x-uuencode
The encoding string is not case sensitive. For the x-uue encoding, an optional filename string may be supplied. If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks (base64 and quoted-printable only).

SEE ALSO
MIME.decode

FUNCTION
MIME.encode_base64 - Encode string using <tt>base64</tt> transfer encoding

SYNTAX
string encode_base64(string data, void|int no_linebreaks);

DESCRIPTION
This function encodes data using the base64 transfer encoding. If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks.

SEE ALSO
MIME.decode_base64

FUNCTION
MIME.encode_qp - Encode string using <tt>quoted-printable</tt> transfer encoding

SYNTAX
string encode_qp(string data, void|int no_linebreaks);

DESCRIPTION
This function encodes data using the quoted-printable (a.k.a. quoted-unreadable) transfer encoding. If a nonzero value is passed as no_linebreaks, the result string will not contain any linebreaks.

NOTE
Please do not use this function. QP is evil, and there's no excuse for using it.

SEE ALSO
MIME.decode_qp

FUNCTION
MIME.encode_uue - Encode string using <tt>x-uue</tt> transfer encoding

SYNTAX
string encode_uue(string encoded_data, void|string filename);

DESCRIPTION
This function encodes data using the x-uue transfer encoding. The optional argument filename specifies an advisory filename to include in the encoded data, for extraction purposes. This function can also be used to produce generic UUEncoded files.

SEE ALSO
MIME.decode_uue

FUNCTION
MIME.encode_word - Encode word according to RFC1522

SYNTAX
string encode_word(array(string) word, string encoding);

DESCRIPTION
Create an encoded word as specified in RFC1522 from an array containing a raw text string and a char set name. The text will be transfer encoded according to the encoding argument, which can be either "base64" or "quoted-printable" (or either "b" or "q" for short). If either the second element of the array (the char set name), or the encoding argument is 0, the raw text is returned as is.

EXAMPLE 
> MIME.encode_word( ({ "Quetzalcoatl", "iso-8859-1" }), "base64" );
Result: =?iso-8859-1?b?UXVldHphbGNvYXRs?=
> MIME.encode_word( ({ "Foo", 0 }), "base64" );
Result: Foo

SEE ALSO
MIME.decode_word

FUNCTION
MIME.generate_boundary - Create a suitable boundary string for multiparts

SYNTAX
string generate_boundary();

DESCRIPTION
This function will create a string that can be used as a separator string for multipart messages. The generated string is guaranteed not to appear in base64, quoted-printable, or x-uue encoded data. It is also unlikely to appear in normal text. This function is used by the cast method of the Message class if no boundary string is specified.

FUNCTION
MIME.guess_subtype - Provide a reasonable default for the subtype field

SYNTAX
string guess_subtype(string type);

DESCRIPTION
Some pre-RFC1521 mailers provide only a type and no subtype in the Content-Type header field. This function can be used to obtain a reasonable default subtype given the type of a message. (This is done automatically by the MIME.Message class.) Currently, the function uses the following guesses:
typesubtype
textplain
messagerfc822
multipartmixed

FUNCTION
MIME.parse_headers - Separate a bytestream into headers and body

SYNTAX
array(mapping(string:string)|string) parse_headers(string message);

DESCRIPTION
This is a low level function that will separate the headers from the body of an encoded message. It will also translate the headers into a mapping. It will however not try to analyze the meaning of any particular header, This also means that the body is returned as is, with any transfer-encoding intact. It is possible to call this function with just the header part of a message, in which case an empty body will be returned.

The result is returned in the form of an array containing two elements. The first element is a mapping containing the headers found. The second element is a string containing the body.

FUNCTION
MIME.quote - Create an RFC822 header field from lexical elements

SYNTAX
string quote(array(string|int) lexical_elements);

DESCRIPTION
This function is the inverse of the tokenize function. A header field value is constructed from a sequence of lexical elements. Characters (ints) are taken to be special-characters, whereas strings are encoded as atoms or quoted-strings, depending on whether they contain any special characters.

EXAMPLE 
> MIME.quote( ({ "attachment", ';', "filename", '=', "/usr/dict/words" }) );
Result: attachment;filename="/usr/dict/words"

NOTE
There is no way to construct a domain-literal using this function. Neither can it be used to produce comments.

SEE ALSO
MIME.tokenize

FUNCTION
MIME.reconstruct_partial - Join a fragmented message to its original form

SYNTAX
int|object reconstruct_partial(array(object) collection);

DESCRIPTION
This function will attempt to reassemble a fragmented message from its parts. The array collection should contain MIME.Message objects forming a complete set of parts for a single fragmented message. The order of the messages in this array is not important, but every part must exist at least once.

Should the function succeed in reconstructing the original message, a new MIME.Message object is returned. Note that this message may in turn be a part of another, larger, fragmented message. If the function fails to reconstruct an original message, it returns an integer indicating the reason for its failure:

  • If an empty collection is passed in, or one that contains messages which are not of type message/partial, or parts of different fragmented messages, the function returns 0.
  • If more fragments are needed to reconstruct the entire message, the number of additional messages needed is returned.
  • If more fragments are needed, but the function can't tell exactly how many, -1 is returned.

SEE ALSO
MIME.Message->is_partial

FUNCTION
MIME.tokenize - Separate an RFC822 header field into lexical elements

SYNTAX
array(string|int) tokenize(string header);

DESCRIPTION
A structured header field, as specified by RFC822, is constructed from a sequence of lexical elements. These are:
  • individual special characters
  • quoted-strings
  • domain-literals
  • comments
  • atoms
This function will analyze a string containing the header value, and produce an array containing the lexical elements. Individual special characters will be returned as characters (i.e. ints). Quoted-strings, domain-literals and atoms will be decoded and returned as strings. Comments are not returned in the array at all.

EXAMPLE 
> MIME.tokenize("multipart/mixed; boundary=\"foo/bar\" (Kilroy was here)");
Result: ({ /* 7 elements */
    "multipart",
    47,
    "mixed",
    59,
    "boundary",
    61,
    "foo/bar"
})

NOTE
As domain-literals are returned as strings, there is no way to tell the domain-literal [127.0.0.1] from the quoted-string "[127.0.0.1]". Hopefully this won't cause any problems. Domain-literals are used seldom, if at all, anyway...

The set of special-characters is the one specified in RFC1521 (i.e. "<", ">", "@", ",", ";", ":", "\", "/", "?", "="), and not the one specified in RFC822.

SEE ALSO
MIME.quote
To contents Next section