convert::ytext(3pm) [debian man page]
Convert::YText(3pm) User Contributed Perl Documentation Convert::YText(3pm) NAME
Convert::YText - Quotes strings suitably for rfc2822 local part VERSION
Version 0.1 SYNOPSIS
use Convert::YText qw(encode_ytext decode_ytext); $encoded=encode_ytext($string); $decoded=decode_ytext($encoded); ($decoded eq $string) || die "this should never happen!"; DESCRIPTION
Convert::YText converts strings to and from "YText", a format inspired by xtext defined in RFC1894, the MIME base64 and quoted-printable types (RFC 1394). The main goal is encode a UTF8 string into something safe for use as the local part in an internet email address (RFC2822). By default spaces are replaced with "+", "/" with "~", the characters "A-Za-z0-9_.-" encode as themselves, and everything else is written "=USTR=" where USTR is the base64 (using "A-Za-z0-9_." as digits) encoding of the unicode character code. The encoding is configurable (see below). PROCEDURAL INTERFACE
The module can can export "encode_ytext" which converts arbitrary unicode string into a "safe" form, and "decode_ytext" which recovers the original text. "validate_ytext" is a heuristic which returns 0 for bad input. OBJECT ORIENTED INTERFACE. For more control, you will need to use the OO interface. new Create a new encoding object. Arguments Arguments are by name (i.e. a hash). DIGIT_STRING ("A-Za-z0-9_.") Must be 64 characters long ESCAPE_CHAR ('=') Must not be in digit string. SPACE_CHAR ('+') Non digit to replace space. Can be the empty string. SLASH_CHAR ( '~') Non digit to replace slash. Can be the empty string. EXTRA_CHARS ('._-') Other characters to leave unencoded. encode Arguments a string to encode. Returns encoded string decode Arguments a string to decode. Returns encoded string valid Simple necessary but not sufficient test for validity. DISCUSSION
According to RFC 2822, the following non-alphanumerics are OK for the local part of an address: "!#$%&'*+-/=?^_`{|}~". On the other hand, it seems common in practice to block addresses having "%!/|`#&?" in the local part. The idea is to restrict ourselves to basic ASCII alphanumerics, plus a small set of printable ASCII, namely "=_+-~.". The characters '+' and '-' are pretty widely used to attach suffixes (although usually only one works on a given mail host). It seems ok to use '+-', since the first marks the beginning of a suffix, and then is a regular character. The character '.' also seems mostly permissable. AUTHOR
David Bremner, <ddb@cpan.org<gt> COPYRIGHT
Copyright (C) 2011 David Bremner. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO
MIME::Base64, MIME::Decoder::Base64, MIME::Decoder::QuotedPrint. perl v5.10.1 2011-04-03 Convert::YText(3pm)
Check Out this Related Man Page
MIME::QuotedPrint(3pm) Perl Programmers Reference Guide MIME::QuotedPrint(3pm) NAME
MIME::QuotedPrint - Encoding and decoding of quoted-printable strings SYNOPSIS
use MIME::QuotedPrint; $encoded = encode_qp($decoded); $decoded = decode_qp($encoded); DESCRIPTION
This module provides functions to encode and decode strings into and from the quoted-printable encoding specified in RFC 2045 - MIME (Multipurpose Internet Mail Extensions). The quoted-printable encoding is intended to represent data that largely consists of bytes that correspond to printable characters in the ASCII character set. Each non-printable character (as defined by English Americans) is represented by a triplet consisting of the character "=" followed by two hexadecimal digits. The following functions are provided: encode_qp( $str) encode_qp( $str, $eol) encode_qp( $str, $eol, $binmode ) This function returns an encoded version of the string ($str) given as argument. The second argument ($eol) is the line-ending sequence to use. It is optional and defaults to " ". Every occurrence of " " is replaced with this string, and it is also used for additional "soft line breaks" to ensure that no line end up longer than 76 characters. Pass it as " 15 12" to produce data suitable for external consumption. The string " " produces the same result on many platforms, but not all. The third argument ($binmode) will select binary mode if passed as a TRUE value. In binary mode " " will be encoded in the same way as any other non-printable character. This ensures that a decoder will end up with exactly the same string whatever line ending sequence it uses. In general it is preferable to use the base64 encoding for binary data; see MIME::Base64. An $eol of "" (the empty string) is special. In this case, no "soft line breaks" are introduced and binary mode is effectively enabled so that any " " in the original data is encoded as well. decode_qp( $str ) This function returns the plain text version of the string given as argument. The lines of the result are " " terminated, even if the $str argument contains " " terminated lines. If you prefer not to import these routines into your namespace, you can call them as: use MIME::QuotedPrint (); $encoded = MIME::QuotedPrint::encode($decoded); $decoded = MIME::QuotedPrint::decode($encoded); Perl v5.8 and better allow extended Unicode characters in strings. Such strings cannot be encoded directly, as the quoted-printable encoding is only defined for single-byte characters. The solution is to use the Encode module to select the byte encoding you want. For example: use MIME::QuotedPrint qw(encode_qp); use Encode qw(encode); $encoded = encode_qp(encode("UTF-8", "x{FFFF} ")); print $encoded; COPYRIGHT
Copyright 1995-1997,2002-2004 Gisle Aas. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO
MIME::Base64 perl v5.18.2 2013-11-04 MIME::QuotedPrint(3pm)