MAN page from Mandrake Other perl-MIME-tools-4.121-1.i386.rpm

lib::MIME::Words

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 04
Index

NAME

MIME::Words - deal with RFC-1522 encoded words

SYNOPSIS

    use MIME::Words qw(:all);            # Decode the string into another string, forgetting the charsets:    $decoded = decode_mimewords(          'To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keldAATTdkuug.dk>',          );        # Split string into array of decoded [DATA,CHARSET] pairs:    @decoded = decode_mimewords(          'To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keldAATTdkuug.dk>',          );         # Encode a single unsafe word:    $encoded = encode_mimeword("\xABFran\xE7ois\xBB");        # Encode a string, trying to find the unsafe words inside it:     $encoded = encode_mimewords("Me and \xABFran\xE7ois\xBB at the beach");

DESCRIPTION

Fellow Americans, you probably won't know what the hell this moduleis for. Europeans, Russians, et al, you probably do. :-).

For example, here's a valid MIME header you might get:

      From: =?US-ASCII?Q?Keith_Moore?= <mooreAATTcs.utk.edu>      To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keldAATTdkuug.dk>      CC: =?ISO-8859-1?Q?Andr=E9_?= Pirard <PIRARDAATTvm1.ulg.ac.be>      Subject: =?ISO-8859-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?=       =?ISO-8859-2?B?dSB1bmRlcnN0YW5kIHRoZSBleGFtcGxlLg==?=       =?US-ASCII?Q?.._cool!?=

The fields basically decode to (sorry, I can only approximate theLatin characters with 7 bit sequences /o and `e):

      From: Keith Moore <mooreAATTcs.utk.edu>      To: Keld J/orn Simonsen <keldAATTdkuug.dk>      CC: Andr'e  Pirard <PIRARDAATTvm1.ulg.ac.be>      Subject: If you can read this you understand the example... cool!

PUBLIC INTERFACE

decode_mimewords ENCODED, [OPTS...]

Go through the string looking for RFC-1522-style ``Q''(quoted-printable, sort of) or ``B'' (base64) encoding, and decode them.

In an array context, splits the ENCODED string into a list of decoded [DATA, CHARSET] pairs, and returns that list. Unencoded data are returned in a 1-element array [DATA], giving an effective CHARSET of undef.

    $enc = '=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keldAATTdkuug.dk>';    foreach (decode_mimewords($enc)) {        print "", ($_[1] || 'US-ASCII'), ": ", $_[0], "\n";    }

In a scalar context, joins the ``data'' elements of the above list together,and returns that. This is information-lossy, but if you know thatall charsets in the ENCODED string are identical, it might be useful to you.

In the event of a syntax error, $@ will be set to a description of the error, but parsing will continue as best as possible (so as toget something back when decoding headers).$@ will be false if no error was detected.

Any arguments past the ENCODED string are taken to define a hash of options:

Field

Name of the mail field this string came from. Currently ignored.

encode_mimeword RAW, [ENCODING], [CHARSET]

Encode a single RAW ``word'' that has unsafe characters.

    # Encode "<<Franc,ois>>":    $encoded = encode_mimeword("\xABFran\xE7ois\xBB");

You may specify the ENCODING ("Q" or "B"), which defaults to "Q".You may specify the CHARSET, which defaults to iso-8859-1.
The ``word'' will be encoded in its entirety.

encode_mimewords RAW, [OPTS]

Given a RAW string, try to find and encode all ``unsafe'' sequences of characters:

    # Encode a string with some unsafe "words":    $encoded = encode_mimewords("Me and \xABFran\xE7ois\xBB at the beach");

Returns the encoded string.Any arguments past the RAW string are taken to define a hash of options:

Charset

Encode all unsafe stuff with this charset. Default is `ISO-8859-1',a.k.a. ``Latin-1''.

Encoding

The encoding to use, "q" or "b". The default is "q".

Field

Name of the mail field this string will be used in. Currently ignored.

Warning: this is a quick-and-dirty solution, intended for charactersets which overlap ASCII. You may want to roll your own variant,using the encoded_mimeword() manpage, for your application.

NOTES

Exports its principle functions by default, in keeping with MIME::Base64 and MIME::QuotedPrint.

AUTHOR

Thanks also to...

      Kent Boortz        For providing the idea, and the baseline                          RFC-1522-decoding code!      kjjAATTprimenet.com   For requesting that this be split into                         its own module.      Stephane Barizien  For reporting a nasty bug.

VERSION

$Revision: 4.102 $ $Date: 1998/06/03 04:11:47 $

This document was created byman2html,using the manual pages.