.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 >0, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Convert::YText 3pm"
.TH Convert::YText 3pm "2022-11-20" "perl v5.36.0" "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"
Convert::YText \- Quotes strings suitably for rfc2822 local part
.SH "VERSION"
.IX Header "VERSION"
Version 0.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Convert::YText qw(encode_ytext decode_ytext);
.PP
\&\f(CW$encoded\fR=encode_ytext($string);
\&\f(CW$decoded\fR=decode_ytext($encoded);
.PP
($decoded eq \f(CW$string\fR) || die \*(L"this should never happen!\*(R";
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Convert::YText converts strings to and from \*(L"YText\*(R", a format inspired
by xtext defined in \s-1RFC1894,\s0 the \s-1MIME\s0 base64 and quoted-printable
types (\s-1RFC 1394\s0).  The main goal is encode a \s-1UTF8\s0 string into something safe
for use as the local part in an internet email address  (\s-1RFC2822\s0).
.PP
By default spaces are replaced with \*(L"+\*(R", \*(L"/\*(R" with \*(L"~\*(R", the characters
\&\*(L"A\-Za\-z0\-9_.\-\*(R" encode as themselves, and everything else is written
\&\*(L"=USTR=\*(R" where \s-1USTR\s0 is the base64 (using \*(L"A\-Za\-z0\-9_.\*(R" as digits)
encoding of the unicode character code.  The encoding is configurable
(see below).
.SH "PROCEDURAL INTERFACE"
.IX Header "PROCEDURAL INTERFACE"
The module can can export \f(CW\*(C`encode_ytext\*(C'\fR which converts arbitrary
unicode string into a \*(L"safe\*(R" form, and \f(CW\*(C`decode_ytext\*(C'\fR which recovers
the original text.  \f(CW\*(C`validate_ytext\*(C'\fR is a heuristic which returns 0
for bad input.
.SH "OBJECT ORIENTED INTERFACE."
.IX Header "OBJECT ORIENTED INTERFACE."
For more control, you will need to use the \s-1OO\s0 interface.
.SS "new"
.IX Subsection "new"
Create a new encoding object.
.PP
\fIArguments\fR
.IX Subsection "Arguments"
.PP
Arguments are by name (i.e. a hash).
.ie n .IP "\s-1DIGIT_STRING\s0 (""A\-Za\-z0\-9_."") Must be 64 characters long" 4
.el .IP "\s-1DIGIT_STRING\s0 (``A\-Za\-z0\-9_.'') Must be 64 characters long" 4
.IX Item "DIGIT_STRING (A-Za-z0-9_.) Must be 64 characters long"
.PD 0
.IP "\s-1ESCAPE_CHAR\s0 ('=') Must not be in digit string." 4
.IX Item "ESCAPE_CHAR ('=') Must not be in digit string."
.IP "\s-1SPACE_CHAR\s0 ('+') Non digit to replace space. Can be the empty string." 4
.IX Item "SPACE_CHAR ('+') Non digit to replace space. Can be the empty string."
.IP "\s-1SLASH_CHAR\s0 ( '~') Non digit to replace slash. Can be the empty string." 4
.IX Item "SLASH_CHAR ( '~') Non digit to replace slash. Can be the empty string."
.IP "\s-1EXTRA_CHARS\s0 ('._\e\-') Other characters to leave unencoded." 4
.IX Item "EXTRA_CHARS ('._-') Other characters to leave unencoded."
.PD
.SS "encode"
.IX Subsection "encode"
\fIArguments\fR
.IX Subsection "Arguments"
.PP
a string to encode.
.PP
\fIReturns\fR
.IX Subsection "Returns"
.PP
encoded string
.SS "decode"
.IX Subsection "decode"
\fIArguments\fR
.IX Subsection "Arguments"
.PP
a string to decode.
.PP
\fIReturns\fR
.IX Subsection "Returns"
.PP
encoded string
.SS "valid"
.IX Subsection "valid"
Simple necessary but not sufficient test for validity.
.SH "DISCUSSION"
.IX Header "DISCUSSION"
According to \s-1RFC 2822,\s0 the following non-alphanumerics are \s-1OK\s0 for the
local part of an address: \*(L"!#$%&'*+\-/=?^_`{|}~\*(R". On the other hand, it
seems common in practice to block addresses having \*(L"%!/|`#&?\*(R" in the
local part.  The idea is to restrict ourselves to basic \s-1ASCII\s0
alphanumerics, plus a small set of printable \s-1ASCII,\s0 namely \*(L"=_+\-~.\*(R".
.PP
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 permissible.
.SH "AUTHOR"
.IX Header "AUTHOR"
David Bremner, <ddb@cpan.org<gt>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2011 David Bremner.  All Rights Reserved.
.PP
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
MIME::Base64, MIME::Decoder::Base64, MIME::Decoder::QuotedPrint.