NAME

cyrillic - Library for fast and easy cyrillic text manipulation

SYNOPSIS

 use cyrillic qw/866 win2dos convert locase upcase detect/;

 print convert( 866, 1251, $str );
 print convert( 'dos','win', \$str );
 print win2dos $str;

DESCRIPTION

This module includes cyrillic string converting functions from one and to another charset, to upper and to lower case without locale switching. Also included single-byte charsets detection routine. It is easy to add new code pages. For this purpose it is necessary only to add appropriate string of a code page.

Supported charsets: ibm866, koi8-r, cp855, windows-1251, MacWindows, iso_8859-5, unicode, utf8;

If the first imported parameter - number of a code page, then locale will be switched to it.

FUNCTIONS

• cset_factory - between charsets convertion function generator

• case_factory - case convertion function generator

• convert - between charsets convertor

• upcase - convert to upper case

• locase - convert to lower case

• upfirst - convert first char to upper case

• lofirst - convert first char to lower case

• detect - detect codepage number

• charset - returns charset name for codepage number

At importing list also might be listed named convertors. For Ex.:

 use cyrillic qw/dos2win win2koi mac2dos ibm2dos/;

NOTE! Specialisations (like win2dos, utf2win) call faster then convert.

NOTE! Only convert function and they specialisation work with Unicode and UTF-8 strings. All others function work only with single-byte sharsets.

Names for using in named charset convertors:

 dos ibm866       866
 koi koi8-r       20866
 ibm cp855        855
 win windows-1251 1251
 mac ms-cyrillic  10007
 iso iso-8859-5   28585
 uni Unicode
 utf UTF-8

The following rules are correct for converting functions:

 VAR may be SCALAR or REF to SCALAR.
 If VAR is REF to SCALAR then SCALAR will be converted.
 If VAR is ommited then $_ operated.
 If function called to void context and VAR is not REF
 then result placed to $_.

CONVERSION METHODS

cset_factory SRC_CP, DST_CP

Generates between codepages convertor function, from SRC_CP to DST_CP, and returns reference to his.

The converting Unicode or UTF-8 data requires presence of installed Unicode::String and Unicode::Map.

case_factory CODEPAGE, [TO_UP], [ONLY_FIRST_LETTER]

Generates case convertor function for single-byte CODEPAGE and returns reference to his.

convert SRC_CP, DST_CP, [VAR]

Convert VAR from SRC_CP codepage to DST_CP codepage and returns converted string. Internaly calls cset_factory.

upcase CODEPAGE, [VAR]

Convert VAR to uppercase using CODEPAGE table and returns converted string. Internaly calls case_factory.

locase CODEPAGE, [VAR]

Convert VAR to lowercase using CODEPAGE table and returns converted string. Internaly calls case_factory.

upfirst CODEPAGE, [VAR]

Convert first char of VAR to uppercase using CODEPAGE table and returns converted string. Internaly calls case_factory.

lofirst CODEPAGE, [VAR]

Convert first char of VAR to lowercase using CODEPAGE table and returns converted string. Internaly calls case_factory.

MAINTAINANCE METHODS

charset CODEPAGE

Returns charset name for CODEPAGE.

detect ARRAY

Detect single-byte codepage of data in ARRAY and returns codepage number. If first element of ARRAY is REF to array of codepages numbers, then detecting will made between these codepages, otherwise - between all single-byte codepages. If codepage not detected then returns undefined value;

EXAMPLES

 use cyrillic qw/convert locase upcase detect dos2win win2dos/;

 $_ = "\x8F\xE0\xA8\xA2\xA5\xE2 \xF0\xA6\x88\xAA\x88!";

 printf "    dos: '%s'\n", $_;
 upcase 866;
 printf " upcase: '%s'\n", $_;
 dos2win;
 printf "dos2win: '%s'\n", $_;
 win2dos;
 printf "win2dos: '%s'\n", $_;
 locase 866;
 printf " locase: '%s'\n", $_;
 printf " detect: '%s'\n", detect $_;

 # detect between 866 and 20866 codepages
 printf " detect: '%s'\n", detect [866, 20866], $_;


 # CONVERTING TEST:

 use cyrillic qw/utf2dos mac2utf dos2mac win2dos utf2win/;

 $_ = "Хелло Ворльд!\n";

 print "UTF-8: $_";
 print "  DOS: ", utf2dos mac2utf dos2mac win2dos utf2win $_;


 # EQVIVALENT CALLS:

 dos2win( $str );        # called to void context -> result placed to $_
 $_ = dos2win( $str );

 dos2win( \$str );       # called with REF to string -> direct converting
 $str = dos2win( $str );

 dos2win();              # with ommited param called -> $_ converted
 dos2win( \$_ );
 $_ = dos2win( $_ );

 my $convert = cset_factory 866, 1251;
 &$convert( $str );            # faster call convertor function via ref to his
   convert( 866, 1251, $str ); # slower call convertor function


 # FOR EASY SWITCH LOCALE CODEPAGE

 use cyrillic qw/866/;   # locale switched to Russian_Russia.866

 use locale;
 print $str =~ /(\w+)/;

 no locale;
 print $str =~ /(\w+)/;

FAQ

 * Q: Why module say: Can't create Unicode::Map for 'koi8-r' charset!
   A: Your Unicode::Map module can't find map file for 'koi8-r' charset.
      Copy file koi8-r.map to site/lib/Unicode/Map and add to file
      site/lib/Unicode/Map/registry followings three strings:

      name:    KOI8-R
      map:     $UnicodeMappings/koi8-r.map
      alias:   csKOI8R

 * Q: Why perl say: "Undefined subroutine koi2win called" ?
   A: The function B<koi2win> is specialization of the function B<convert>,
      which is created at inclusion it of the name in the list of import.

AUTHOR

Albert MICHEEV <Albert@f80.n5049.z2.fidonet.org>

COPYRIGHT

Copyright (C) 2000, Albert MICHEEV

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

AVAILABILITY

The latest version of this library is likely to be available from:

http://www.perl.com/CPAN

SEE ALSO

Unicode::String, Unicode::Map.

cpanm cyrillic

perl -MCPAN -e shell
install cyrillic