PApp::Recode - convert bytes from one charset to another

PApp documentation Contained in the PApp distribution.

Index

Code Index:

NAME

Top

PApp::Recode - convert bytes from one charset to another

SYNOPSIS

Top

 use PApp::Recode;
 # not auto-imported into .papp-files

 $converter = to_utf8 PApp::Recode "iso-8859-1";
 $converter->("string");

DESCRIPTION

Top

This module creates conversion functions that enable you to convert text data from one character set (and/or encoding) to another.

Functions

charset_valid $charset

Returns a boolean indicating wether the named charset is valid on this system (where "valid" is defined as "can be converted from/to UTF-8 using this module").

The PApp::Recode Class

This class can be used to convert textual data between various encodings.

$converter = new PApp::Recode "destination-charset", "source-charset" [, \&fallback]

Returns a new conversion function (a code reference) that converts its argument from the source character set into the destination character set each time it is called (it does remember state, though. A call without arguments resets the state).

Perl's internal UTF-8-flag is ignored on input and not set on output.

Example: create a converter that converts UTF-8 into ascii, html-escaping any non-ascii characters:

   new PApp::Recode "ascii", "utf-8", sub { sprintf "&#x%x;", $_[0] };
$converter = to_utf8 PApp::Recode "source-character-set" [, \&fallback]

Similar to a call to new with the first argument equal to "utf-8". The returned conversion function will, however, forcefully set perl's UTF-8 flag on the returned scalar.

$converter = utf8_to PApp::Recode "destination-character-set" [, \&fallback]

Similar to a call to new with the second argument equal to "utf-8". The returned conversion function will, however, upgrade its argument to UTF-8.

The PApp::Recode::Pconv Class

This is the class that actually implements character conversion. It should not be used directly.

new PApp::Recode::Pconv tocode, fromcode [, fallback]

Create a new encoding convert that encodes from fromcode to tocode, optionally invoking the fallback code reference for every character that is not representable in the target encoding.

PApp::Recode::Pconv::open tocode, fromcode [, fallback]

Convenience function that calls new and returns the converter.

$pconv->convert($string [, reset])

Convert the given string. If reset is true, the internal multibyte state is reset before conversion.

$pconv->reset

Reset the multibyte state.

$pconv->convert_fresh ($string)

Same as convert with reset set to true.

SEE ALSO

Top

PApp.

AUTHOR

Top

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/
PApp documentation Contained in the PApp distribution. 
##########################################################################
## All portions of this code are copyright (c) 2003,2004 nethype GmbH   ##
##########################################################################
## Using, reading, modifying or copying this code requires a LICENSE    ##
## from nethype GmbH, Franz-Werfel-Str. 11, 74078 Heilbronn,            ##
## Germany. If you happen to have questions, feel free to contact us at ##
## license@nethype.de.                                                  ##
##########################################################################


package PApp::Recode;

use Convert::Scalar ();

BEGIN {
   $VERSION = 1.45;

   require XSLoader;
   XSLoader::load 'PApp::Recode', $VERSION;
}


# cache the results, some frequently used charsets are always supported
my %charset_valid = ( "iso-8859-1" => 1, "utf-8" => 1, "ascii" => 1 );

sub charset_valid {
   unless (exists $charset_valid{$_[0]}) {
      $charset_valid{$cs} = eval {
         PApp::Recode::Pconv::open($cs, "utf-8");
         PApp::Recode::Pconv::open("utf-8", $cs);
         1;
      };
   }
   $charset_valid{$cs};
}


sub new($$$;$) {
   my $self = shift;
   my ($to, $from, $fb) = @_;
   my $pconv = PApp::Recode::Pconv::open($to, $from, $fb);
   $pconv && sub {
      unshift @_, $pconv;
      &PApp::Recode::Pconv::convert;
   };
}

sub to_utf8($$;$) {
   my $self = shift;
   my $converter = $self->new("utf-8", $_[0], $_[1]);
   sub {
      Convert::Scalar::utf8_on &$converter;
   };
}

sub utf8_to($$;$) {
   my $self = shift;
   my $converter = $self->new($_[0], "utf-8", $_[1]);
   sub {
      Convert::Scalar::utf8_upgrade($_[0]) if @_;
      &$converter;
   };
}


1;