The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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 Exporter 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 Unicode::String, Unicode::Map8, Jcode 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--');

BIG FAT CAVEAT

  • This module does NOT implement Nameprep phase. See mDNkit (http://www.nic.ad.jp/jp/research/idn/mdnkit/download/) for complete implementations.

AUTHOR

Tatsuhiko Miyagawa <miyagawa@bulknews.net>, with much help from Eugen SAVIN <seugen@serifu.com>, Philip Newton <pne@cpan.org>, Michael J Schout <mschout@gkg.net>.

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

There comes NO WARRANTY with this module.

SEE ALSO

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

1 POD Error

The following errors were encountered while parsing the POD:

Around line 268:

Non-ASCII character seen before =encoding in 'to_race(Jcode->new('ÆüËܸì','euc')->ucs2);'. Assuming CP1252