view release on metacpan or  search on metacpan

lib/Convert/YText.pm  view on Meta::CPAN

package Convert::YText;

use strict;
use warnings;
use Carp;

use vars qw/$VERSION @ISA @EXPORT_OK/;
@ISA = 'Exporter';
@EXPORT_OK = qw( encode_ytext decode_ytext validate_ytext);

$VERSION="0.2";

=head1 NAME

Convert::YText - Quotes strings suitably for rfc2822 local part

=head1 VERSION

Version 0.2

=head1 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!";

=head1 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).

=head1 PROCEDURAL INTERFACE

The module can can export C<encode_ytext> which converts arbitrary
unicode string into a "safe" form, and C<decode_ytext> which recovers
the original text.  C<validate_ytext> is a heuristic which returns 0
for bad input.


=cut


sub encode_ytext{
  my $str=shift;
  my $object = Convert::YText->new();
  return $object->encode($str);
}

sub decode_ytext{
  my $str=shift;
  my $object = Convert::YText->new();
  return $object->decode($str);
}

sub validate_ytext{
  my $str=shift;
  my $object = Convert::YText->new();
  return $object->valid($str);
}

=head1 OBJECT ORIENTED INTERFACE.

For more control, you will need to use the OO interface.

=head2 new

Create a new encoding object.

=head3 Arguments

Arguments are by name (i.e. a hash).

=over

=item DIGIT_STRING ("A-Za-z0-9_.") Must be 64 characters long

=item ESCAPE_CHAR ('=') Must not be in digit string.

=item SPACE_CHAR ('+') Non digit to replace space. Can be the empty string.

=item SLASH_CHAR ( '~') Non digit to replace slash. Can be the empty string.

=item EXTRA_CHARS ('._\-') Other characters to leave unencoded.

=back

=cut

sub new {
  my $class = shift;

  my %params=@_;

  my $self = { ESCAPE_CHAR=>'=',
	       SPACE_CHAR=>'+',