root/Convert-RACE/trunk/README

Revision 44 (checked in by miyagawa, 19 years ago)

added address

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1 NAME
2     Convert::RACE - Conversion between Unicode and RACE
3
4 SYNOPSIS
5       use Convert::RACE;
6
7       $domain = to_race($utf16str);
8       $utf16str = from_race($domain);
9
10 DESCRIPTION
11     This module provides functions to convert between RACE (Row-based ASCII-
12     Compatible Encoding) and Unicode Encodings.
13
14     RACE converts strings with internationalized characters into strings of
15     US-ASCII that are acceptable as host name parts in current DNS host naming
16     usage.
17
18     See http://www.ietf.org/internet-drafts/draft-ietf-idn-race-03.txt for
19     more details.
20
21 FUNCTION
22     Following functions are provided; they are all in @EXPORT array. See the
23     Exporter manpage for details.
24
25     to_race($utf16)
26         to_race() takes UTF-16 encoding and returns RACE-encoded strings such
27         as 'bq--aewrcsy'.
28
29         This function throws an exception such as 'String includes no
30         internationalized characters', 'String too long' and 'Invalid encoding
31         to compress'. Exceptions are thrown with Carp::croak(), so you can
32         cath 'em with eval {};
33
34     from_race($domain_name)
35         from_race() takes 'bq--' prefixed string and returns original UTF-16
36         string.
37
38         This function throws an exception such as 'String not begin with bq--
39         ', 'Decoded string includes no internationalized characters' and '
40         Invalid format to decompress'. Exceptions are thrown with
41         Carp::croak(), so you can cath 'em with eval {};
42
43     See the Unicode::String manpage, the Unicode::Map8 manpage, the Jcode
44     manpage for Unicode conversions.
45
46 CLASS METHOD
47     Following class methods are provided to change the behaviour of
48     Convert::RACE.
49
50     prefix_tag()
51         Set and get the domain prefix tag. By default, 'bq--'.
52
53 EXAMPLES
54       use Jcode;
55       use Unicode::String 'latin1';
56       use Convert::RACE 'to_race';
57
58       # EUC-japanese here
59       $name = to_race(Jcode->new('ÆüËÜžì','euc')->ucs2);
60      
61       # or, Latin here
62       $name = to_race(latin1($latin_string)->utf16);
63
64       # in doubt of exception
65       eval { $name = to_race($utf); };
66       if ($@) {
67           warn "Can't encode to RACE: $@";
68       }
69
70       # change the prefix
71       Convert::RACE->prefix_tag('xx--');
72
73 TODO AND CAVEATS
74     *   Using XS would be by far efficient.
75
76     *   No validation is done for the input UTF-16 string in to_race(). The
77         internet draft says checking for prohibited name parts must be done
78         before doing the conversion.
79
80 AUTHOR
81     Tatsuhiko Miyagawa <miyagawa@bulknews.net>, with much help from Eugen
82     SAVIN <seugen@serifu.com>, Philip Newton <pne@cpan.org>, Michael J Schout
83     <mschout@gkg.net>.
84
85     This library is free software; you can redistribute it and/or modify it
86     under the same terms as Perl itself.
87
88 SEE ALSO
89     http://www.i-d-n.net/, http://www.ietf.org/internet-drafts/draft-ietf-idn-
90     race-03.txt, RFC 1035, the Unicode::String manpage, the Jcode manpage, the
91     Convert::Base32 manpage.
92
93 Revision history for Perl extension Convert::RACE.
94
95 0.05  Tue Mar  6 16:44:33 JST 2001
96         - fixed bug in case that input strings contain characters
97           from only 2 rows, both of which are not 0x00.
98           Thanks to Michael J Schout <mschout@gkg.net>
99
100 0.04  Thu Mar  1 23:03:06 JST 2001
101         - fixed the bug that if a character has a byte of 0x0a,
102           it is ignored.
103           Thanks to Philip Newton <pne@cpan.org>
104
105 0.02  Wed Feb 28 02:52:49 JST 2001
106         - fixed the bug in case that all of the upper octets are
107           either 0x00 or one single other value.
108           Thanks to Eugen SAVIN <seugen@serifu.com>
109
110 0.01  Sat Dec  9 21:01:11 2000
111         - original version; created by h2xs 1.19
112
Note: See TracBrowser for help on using the browser.