NAME
   Convert::RACE - Conversion between Unicode and RACE

SYNOPSIS
     use Convert::RACE;

     $domain = to_race($utf16str);
     $utf16str = from_race($domain);

DESCRIPTION
   This module provides functions to convert between RACE (Row-based ASCII-
   Compatible Encoding) and Unicode Encodings.

   RACE converts strings with internationalized characters into strings of
   US-ASCII that are acceptable as host name parts in current DNS host naming
   usage.

   See http://www.ietf.org/internet-drafts/draft-ietf-idn-race-03.txt for
   more details.

FUNCTION
   Following functions are provided; they are all in @EXPORT array. See the
   Exporter manpage for details.

   to_race($utf16)
       to_race() takes UTF-16 encoding and returns RACE-encoded strings such
       as 'bq--aewrcsy'.

       This function throws an exception such as 'String includes no
       internationalized characters', 'String too long' and 'Invalid encoding
       to compress'. Exceptions are thrown with Carp::croak(), so you can
       cath 'em with eval {};

   from_race($domain_name)
       from_race() takes 'bq--' prefixed string and returns original UTF-16
       string.

       This function throws an exception such as 'String not begin with bq--
       ', 'Decoded string includes no internationalized characters' and '
       Invalid format to decompress'. Exceptions are thrown with
       Carp::croak(), so you can cath 'em with eval {};

   See the Unicode::String manpage, the Unicode::Map8 manpage, the Jcode
   manpage for Unicode conversions.

CLASS METHOD
   Following class methods are provided to change the behaviour of
   Convert::RACE.

   prefix_tag()
       Set and get the domain prefix tag. By default, 'bq--'.

EXAMPLES
     use Jcode;
     use Unicode::String 'latin1';
     use Convert::RACE 'to_race';

     # EUC-japanese here
     $name = to_race(Jcode->new('��ܸ�','euc')->ucs2);

     # or, Latin here
     $name = to_race(latin1($latin_string)->utf16);

     # in doubt of exception
     eval { $name = to_race($utf); };
     if ($@) {
         warn "Can't encode to RACE: $@";
     }

     # change the prefix
     Convert::RACE->prefix_tag('xx--');

TODO AND CAVEATS
   *   Using XS would be by far efficient.

   *   No validation is done for the input UTF-16 string in to_race(). The
       internet draft says checking for prohibited name parts must be done
       before doing the conversion.

AUTHOR
   Tatsuhiko Miyagawa <[email protected]>, with much help from Eugen
   SAVIN <[email protected]>, Philip Newton <[email protected]>, Michael J Schout
   <[email protected]>.

   This library is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself.

SEE ALSO
   http://www.i-d-n.net/, http://www.ietf.org/internet-drafts/draft-ietf-idn-
   race-03.txt, RFC 1035, the Unicode::String manpage, the Jcode manpage, the
   Convert::Base32 manpage.

Revision history for Perl extension Convert::RACE.

0.05  Tue Mar  6 16:44:33 JST 2001
       - fixed bug in case that input strings contain characters
         from only 2 rows, both of which are not 0x00.
         Thanks to Michael J Schout <[email protected]>

0.04  Thu Mar  1 23:03:06 JST 2001
       - fixed the bug that if a character has a byte of 0x0a,
         it is ignored.
         Thanks to Philip Newton <[email protected]>

0.02  Wed Feb 28 02:52:49 JST 2001
       - fixed the bug in case that all of the upper octets are
         either 0x00 or one single other value.
         Thanks to Eugen SAVIN <[email protected]>

0.01  Sat Dec  9 21:01:11 2000
       - original version; created by h2xs 1.19

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.