Changeset 40

Show
Ignore:
Timestamp:
02/28/01 03:32:44
Author:
miyagawa
Message:

fixed README

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved
  • Convert-RACE/trunk/README

    r39 r40  
     1NAME 
     2    Convert::RACE - Conversion between Unicode and RACE 
     3 
     4SYNOPSIS 
     5      use Convert::RACE; 
     6 
     7      $domain = to_race($utf16str); 
     8      $utf16str = from_race($domain); 
     9 
     10DESCRIPTION 
     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 
     21FUNCTION 
     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 
     46CLASS 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 
     53EXAMPLES 
     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 
     73TODO 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 
     80AUTHOR 
     81    Tatsuhiko Miyagawa <miyagawa@bulknews.net> 
     82 
     83    This library is free software; you can redistribute it and/or modify it 
     84    under the same terms as Perl itself. 
     85 
     86SEE ALSO 
     87    http://www.i-d-n.net/, http://www.ietf.org/internet-drafts/draft-ietf-idn- 
     88    race-03.txt, RFC 1035, the Unicode::String manpage, the Jcode manpage, the 
     89    Convert::Base32 manpage. 
     90