MIME::Tools MIME::Body MIME::Decoder MIME::Entity
MIME::Head MIME::IO MIME::Latin1 MIME::Parser
MIME::ParserBase MIME::ToolUtils MIME::Tools MIME::Words

MIME::
Words

MIME!


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?= <keld@dkuug.dk>',
          );

    # Split string into array of decoded [DATA,CHARSET] pairs:
    @decoded = decode_mimewords(
          'To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.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 module is 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?= <moore@cs.utk.edu>
      To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>
      CC: =?ISO-8859-1?Q?Andr=E9_?= Pirard <PIRARD@vm1.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 the Latin characters with 7 bit sequences /o and 'e):

      From: Keith Moore <moore@cs.utk.edu>
      To: Keld J/orn Simonsen <keld@dkuug.dk>
      CC: Andr'e  Pirard <PIRARD@vm1.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?= <keld@dkuug.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 that all charsets in the ENCODED string are identical, it might be useful to you.

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 character sets which overlap ASCII. You may want to roll your own variant, using encoded_mimeword(), for your application.


NOTES

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


AUTHOR

Copyright (c) 1997 by Eryq, eryq@zeegee.com.

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Thanks also to...

      Kent Boortz        For providing the idea, and the baseline 
                         RFC-1522-decoding code!
      kjj@primenet.com   For requesting that this be split into
                         its own module.


VERSION

$Revision: 4.101 $ $Date: 1997/12/09 06:37:39 $


Last updated: Sat Feb 14 16:35:29 1998
Generated by pod2coolhtml 1.101. Want a copy? Just email eryq@zeegee.com. (Yes, it's free.)