.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "MIME::Words 3pm" .TH MIME::Words 3pm "2016-09-01" "perl v5.22.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" MIME::Words \- deal with RFC 2047 encoded words .SH "SYNOPSIS" .IX Header "SYNOPSIS" Before reading further, you should see MIME::Tools to make sure that you understand where this module fits into the grand scheme of things. Go on, do it now. I'll wait. .PP Ready? Ok... .PP .Vb 1 \& use MIME::Words qw(:all); \& \& ### Decode the string into another string, forgetting the charsets: \& $decoded = decode_mimewords( \& \*(AqTo: =?ISO\-8859\-1?Q?Keld_J=F8rn_Simonsen?= \*(Aq, \& ); \& \& ### Split string into array of decoded [DATA,CHARSET] pairs: \& @decoded = decode_mimewords( \& \*(AqTo: =?ISO\-8859\-1?Q?Keld_J=F8rn_Simonsen?= \*(Aq, \& ); \& \& ### Encode a single unsafe word: \& $encoded = encode_mimeword("\exABFran\exE7ois\exBB"); \& \& ### Encode a string, trying to find the unsafe words inside it: \& $encoded = encode_mimewords("Me and \exABFran\exE7ois\exBB in town"); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Fellow Americans, you probably won't know what the hell this module is for. Europeans, Russians, et al, you probably do. \f(CW\*(C`:\-)\*(C'\fR. .PP For example, here's a valid \s-1MIME\s0 header you might get: .PP .Vb 6 \& From: =?US\-ASCII?Q?Keith_Moore?= \& To: =?ISO\-8859\-1?Q?Keld_J=F8rn_Simonsen?= \& CC: =?ISO\-8859\-1?Q?Andr=E9_?= Pirard \& Subject: =?ISO\-8859\-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?= \& =?ISO\-8859\-2?B?dSB1bmRlcnN0YW5kIHRoZSBleGFtcGxlLg==?= \& =?US\-ASCII?Q?.._cool!?= .Ve .PP The fields basically decode to (sorry, I can only approximate the Latin characters with 7 bit sequences /o and 'e): .PP .Vb 4 \& From: Keith Moore \& To: Keld J/orn Simonsen \& CC: Andr\*(Aqe Pirard \& Subject: If you can read this you understand the example... cool! .Ve .SH "PUBLIC INTERFACE" .IX Header "PUBLIC INTERFACE" .IP "decode_mimewords \s-1ENCODED\s0" 4 .IX Item "decode_mimewords ENCODED" \&\fIFunction.\fR Go through the string looking for \s-1RFC\s0 2047\-style \*(L"Q\*(R" (quoted-printable, sort of) or \*(L"B\*(R" (base64) encoding, and decode them. .Sp \&\fBIn an array context,\fR splits the \s-1ENCODED\s0 string into a list of decoded \&\f(CW\*(C`[DATA, CHARSET]\*(C'\fR pairs, and returns that list. Unencoded data are returned in a 1\-element array \f(CW\*(C`[DATA]\*(C'\fR, giving an effective \&\s-1CHARSET\s0 of \f(CW\*(C`undef\*(C'\fR. .Sp .Vb 4 \& $enc = \*(Aq=?ISO\-8859\-1?Q?Keld_J=F8rn_Simonsen?= \*(Aq; \& foreach (decode_mimewords($enc)) { \& print "", ($_\->[1] || \*(AqUS\-ASCII\*(Aq), ": ", $_\->[0], "\en"; \& } .Ve .Sp \&\fBIn a scalar context,\fR joins the \*(L"data\*(R" elements of the above list together, and returns that. \fIWarning: this is information-lossy,\fR and probably \fInot\fR what you want, but if you know that all charsets in the \s-1ENCODED\s0 string are identical, it might be useful to you. (Before you use this, please see \*(L"unmime\*(R" in MIME::WordDecoder, which is probably what you want.) .Sp 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 to get \fIsomething\fR back when decoding headers). $@ will be false if no error was detected. .Sp Any arguments past the \s-1ENCODED\s0 string are taken to define a hash of options: .IP "encode_mimeword \s-1RAW,\s0 [\s-1ENCODING\s0], [\s-1CHARSET\s0]" 4 .IX Item "encode_mimeword RAW, [ENCODING], [CHARSET]" \&\fIFunction.\fR Encode a single \s-1RAW \s0\*(L"word\*(R" that has unsafe characters. The \*(L"word\*(R" will be encoded in its entirety. .Sp .Vb 2 \& ### Encode "<>": \& $encoded = encode_mimeword("\exABFran\exE7ois\exBB"); .Ve .Sp You may specify the \s-1ENCODING \s0(\f(CW"Q"\fR or \f(CW"B"\fR), which defaults to \f(CW"Q"\fR. You may specify the \s-1CHARSET,\s0 which defaults to \f(CW\*(C`iso\-8859\-1\*(C'\fR. .IP "encode_mimewords \s-1RAW,\s0 [\s-1OPTS\s0]" 4 .IX Item "encode_mimewords RAW, [OPTS]" \&\fIFunction.\fR Given a \s-1RAW\s0 string, try to find and encode all \*(L"unsafe\*(R" sequences of characters: .Sp .Vb 2 \& ### Encode a string with some unsafe "words": \& $encoded = encode_mimewords("Me and \exABFran\exE7ois\exBB"); .Ve .Sp Returns the encoded string. Any arguments past the \s-1RAW\s0 string are taken to define a hash of options: .RS 4 .IP "Charset" 4 .IX Item "Charset" Encode all unsafe stuff with this charset. Default is '\s-1ISO\-8859\-1\s0', a.k.a. \*(L"Latin\-1\*(R". .IP "Encoding" 4 .IX Item "Encoding" The encoding to use, \f(CW"q"\fR or \f(CW"b"\fR. The default is \f(CW"q"\fR. .RE .RS 4 .Sp \&\fBWarning:\fR this is a quick-and-dirty solution, intended for character sets which overlap \s-1ASCII. \s0\fBIt does not comply with the \s-1RFC 2047\s0 rules regarding the use of encoded words in message headers\fR. You may want to roll your own variant, using \f(CW\*(C`encode_mimeword()\*(C'\fR, for your application. \&\fIThanks to Jan Kasprzak for reminding me about this problem.\fR .RE .SH "SEE ALSO" .IX Header "SEE ALSO" MIME::Base64, MIME::QuotedPrint, MIME::Tools .PP For other implementations of this or similar functionality (particularly, ones with proper \s-1UTF8\s0 support), see: .PP Encode::MIME::Header, MIME::EncWords, MIME::AltWords .PP At some future point, one of these implementations will likely replace MIME::Words and MIME::Words will become deprecated. .SH "NOTES" .IX Header "NOTES" Exports its principle functions by default, in keeping with MIME::Base64 and MIME::QuotedPrint. .SH "AUTHOR" .IX Header "AUTHOR" Eryq (\fIeryq@zeegee.com\fR), ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR). Dianne Skoll (dfs@roaringpenguin.com) http://www.roaringpenguin.com .PP All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP Thanks also to... .PP .Vb 5 \& Kent Boortz For providing the idea, and the baseline \& RFC\-1522\-decoding code! \& KJJ at PrimeNet For requesting that this be split into \& its own module. \& Stephane Barizien For reporting a nasty bug. .Ve