<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<!-- Generated by pod2coolhtml 1.101
-- Using Pod::CoolHTML 1.104 , (C) 1997 by Eryq (eryq@enteract.com).
--
-- DO NOT EDIT THIS HTML FILE! All your changes will be lost.
-- Edit the POD or Perl file that was used to create it.
-->
<HTML>
<HEAD>
<TITLE>MIME::Words</TITLE>
</HEAD>
<BODY LINK=#C00000 ALINK=#FF2020 VLINK=#900000>
<A NAME="__top"> </A><CENTER><TABLE BORDER=2 CELLPADDING=2 WIDTH=100%>
<TR>
<TD WIDTH=25% ALIGN=CENTER><B><FONT SIZE=+1>
<A HREF="Tools.pm.html">MIME::Tools</A></FONT></B></TD>
<TD WIDTH=25% ALIGN=CENTER><B><SMALL>
<A HREF="Body.pm.html">MIME::Body</A></SMALL></B></TD>
<TD WIDTH=25% ALIGN=CENTER><B><SMALL>
<A HREF="Decoder.pm.html">MIME::Decoder</A></SMALL></B></TD>
<TD WIDTH=25% ALIGN=CENTER><B><SMALL>
<A HREF="Entity.pm.html">MIME::Entity</A></SMALL></B></TD>
<TR>
<TD WIDTH=25% ALIGN=CENTER><B><SMALL>
<A HREF="Head.pm.html">MIME::Head</A></SMALL></B></TD>
<TD WIDTH=25% ALIGN=CENTER><B><SMALL>
<A HREF="IO.pm.html">MIME::IO</A></SMALL></B></TD>
<TD WIDTH=25% ALIGN=CENTER><B><SMALL>
<A HREF="Latin1.pm.html">MIME::Latin1</A></SMALL></B></TD>
<TD WIDTH=25% ALIGN=CENTER><B><SMALL>
<A HREF="Parser.pm.html">MIME::Parser</A></SMALL></B></TD>
<TR>
<TD WIDTH=25% ALIGN=CENTER><B><SMALL>
<A HREF="ParserBase.pm.html">MIME::ParserBase</A></SMALL></B></TD>
<TD WIDTH=25% ALIGN=CENTER><B><SMALL>
<A HREF="ToolUtils.pm.html">MIME::ToolUtils</A></SMALL></B></TD>
<TD WIDTH=25% ALIGN=CENTER><B><SMALL>
<A HREF="Tools.pm.html">MIME::Tools</A></SMALL></B></TD>
<TD WIDTH=25% ALIGN=CENTER><B><SMALL>
MIME::Words</SMALL></B></TD>
</TABLE></CENTER>
<P><TABLE WIDTH="100%">
<TR VALIGN="TOP"><TD ALIGN="LEFT"><CENTER>
<H1><FONT SIZE=7 COLOR=#600020><B>MIME::<BR>Words</B></FONT></H1><IMG SRC="mime-sm.gif" ALT="MIME!"></CENTER>
<TD>
<UL>
<LI><A HREF="#name">NAME</A>
</LI><LI><A HREF="#synopsis">SYNOPSIS</A>
</LI><LI><A HREF="#description">DESCRIPTION</A>
</LI><LI><A HREF="#public_interface">PUBLIC INTERFACE</A>
</LI><LI><A HREF="#notes">NOTES</A>
</LI><LI><A HREF="#author">AUTHOR</A>
</LI><LI><A HREF="#version">VERSION</A>
</LI></UL>
</TABLE>
<P><HR>
<A NAME="name">
<H1><FONT COLOR=#600020>
<A HREF="#__top"><IMG SRC="h1bullet.gif" ALT="" BORDER="0"></A>
NAME</FONT></H1>
</A>
<P>
MIME::Words - deal with RFC-1522 encoded words
<P><HR>
<A NAME="synopsis">
<H1><FONT COLOR=#600020>
<A HREF="#__top"><IMG SRC="h1bullet.gif" ALT="" BORDER="0"></A>
SYNOPSIS</FONT></H1>
</A>
<P>
<PRE> use MIME::Words qw(:all); </PRE>
<P>
<PRE> # Decode the string into another string, forgetting the charsets:
$decoded = decode_mimewords(
'To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>',
);</PRE>
<P>
<PRE> # Split string into array of decoded [DATA,CHARSET] pairs:
@decoded = decode_mimewords(
'To: =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>',
);</PRE>
<P>
<PRE> # Encode a single unsafe word:
$encoded = encode_mimeword("\xABFran\xE7ois\xBB");</PRE>
<P>
<PRE> # Encode a string, trying to find the unsafe words inside it:
$encoded = encode_mimewords("Me and \xABFran\xE7ois\xBB at the beach");</PRE>
<P><HR>
<A NAME="description">
<H1><FONT COLOR=#600020>
<A HREF="#__top"><IMG SRC="h1bullet.gif" ALT="" BORDER="0"></A>
DESCRIPTION</FONT></H1>
</A>
<P>
Fellow Americans, you probably won't know what the hell this module
is for. Europeans, Russians, et al, you probably do. <CODE>:-)</CODE>.
<P>
For example, here's a valid MIME header you might get:
<P>
<PRE> 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!?=</PRE>
<P>
The fields basically decode to (sorry, I can only approximate the
Latin characters with 7 bit sequences /o and 'e):
<P>
<PRE> 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!</PRE>
<P><HR>
<A NAME="public_interface">
<H1><FONT COLOR=#600020>
<A HREF="#__top"><IMG SRC="h1bullet.gif" ALT="" BORDER="0"></A>
PUBLIC INTERFACE</FONT></H1>
</A>
<DL>
<P><DT><B><A NAME="decode_mimewords">decode_mimewords ENCODED, [OPTS...]</A></B><DD>
Go through the string looking for RFC-1522-style "Q"
(quoted-printable, sort of) or "B" (base64) encoding, and decode them.
<P>
<B>In an array context,</B> splits the ENCODED string into a list of decoded
<CODE>[DATA, CHARSET]</CODE> pairs, and returns that list. Unencoded
data are returned in a 1-element array <CODE>[DATA]</CODE>, giving an effective
CHARSET of <CODE>undef</CODE>.
<P>
<PRE> $enc = '=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>';
foreach (decode_mimewords($enc)) {
print "", ($_[1] || 'US-ASCII'), ": ", $_[0], "\n";
}</PRE>
<P>
<B>In a scalar context,</B> 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.
<P>
Any arguments past the ENCODED string are taken to define a hash of options:
<DL>
<P><DT><B><A NAME="field">Field</A></B><DD>
Name of the mail field this string came from. <I>Currently ignored.</I>
</DL>
<P><DT><B><A NAME="encode_mimeword">encode_mimeword RAW, [ENCODING], [CHARSET]</A></B><DD>
Encode a single RAW "word" that has unsafe characters.
<P>
<PRE> # Encode "<<Franc,ois>>":
$encoded = encode_mimeword("\xABFran\xE7ois\xBB");</PRE>
<P>
You may specify the ENCODING (<CODE>"Q"</CODE> or <CODE>"B"</CODE>), which defaults to <CODE>"Q"</CODE>.
You may specify the CHARSET, which defaults to <CODE>iso-8859-1</CODE>.
<P>
The "word" will be encoded in its entirety.
<P><DT><B><A NAME="encode_mimewords">encode_mimewords RAW, [OPTS]</A></B><DD>
Given a RAW string, try to find and encode all "unsafe" sequences
of characters:
<P>
<PRE> # Encode a string with some unsafe "words":
$encoded = encode_mimewords("Me and \xABFran\xE7ois\xBB at the beach");</PRE>
<P>
Returns the encoded string.
Any arguments past the RAW string are taken to define a hash of options:
<DL>
<P><DT><B><A NAME="charset">Charset</A></B><DD>
Encode all unsafe stuff with this charset. Default is 'ISO-8859-1',
a.k.a. "Latin-1".
<P><DT><B><A NAME="encoding">Encoding</A></B><DD>
The encoding to use, <CODE>"q"</CODE> or <CODE>"b"</CODE>. The default is <CODE>"q"</CODE>.
<P><DT><B><A NAME="field">Field</A></B><DD>
Name of the mail field this string will be used in. <I>Currently ignored.</I>
</DL>
<P>
<B>Warning:</B> this is a quick-and-dirty solution, intended for character
sets which overlap ASCII. You may want to roll your own variant,
using <A HREF="#encoded_mimeword">encoded_mimeword()</A>, for your application.
</DL>
<P><HR>
<A NAME="notes">
<H1><FONT COLOR=#600020>
<A HREF="#__top"><IMG SRC="h1bullet.gif" ALT="" BORDER="0"></A>
NOTES</FONT></H1>
</A>
<P>
Exports its principle functions by default, in keeping with
MIME::Base64 and MIME::QuotedPrint.
<P><HR>
<A NAME="author">
<H1><FONT COLOR=#600020>
<A HREF="#__top"><IMG SRC="h1bullet.gif" ALT="" BORDER="0"></A>
AUTHOR</FONT></H1>
</A>
<P>
Copyright (c) 1997 by Eryq, <I><A HREF="mailto:eryq@zeegee.com">eryq@zeegee.com</A></I>.
<P>
All rights reserved. This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
<P>
Thanks also to...
<P>
<PRE> 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.</PRE>
<P><HR>
<A NAME="version">
<H1><FONT COLOR=#600020>
<A HREF="#__top"><IMG SRC="h1bullet.gif" ALT="" BORDER="0"></A>
VERSION</FONT></H1>
</A>
<P>
$Revision: 4.101 $ $Date: 1997/12/09 06:37:39 $
<P><HR>
<SMALL>
Last updated: Sat Jan 17 23:02:06 1998 <BR>
Generated by pod2coolhtml 1.101. Want a copy? Just email
<A HREF="mailto:eryq@enteract.com">eryq@enteract.com</A>.
(Yes, it's free.)
</SMALL></BODY>
</HTML>