home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / lib / perl5 / Text / Iconv.pm < prev   
Encoding:
Perl POD Document  |  2004-07-17  |  3.6 KB  |  119 lines
  1. package Text::Iconv;
  2. # @(#) $Id: Iconv.pm,v 1.6 2004/07/17 22:25:46 mxp Exp $
  3. # Copyright (c) 2004 Michael Piotrowski
  4.  
  5. use strict;
  6. use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
  7.  
  8. require Exporter;
  9. require DynaLoader;
  10. require AutoLoader;
  11.  
  12. @ISA = qw(Exporter AutoLoader DynaLoader);
  13. # Items to export into callers namespace by default. Note: do not export
  14. # names by default without a very good reason. Use EXPORT_OK instead.
  15. # Do not simply export all your public functions/methods/constants.
  16. @EXPORT_OK = qw(
  17.     convert
  18. );
  19. $VERSION = '1.4';
  20.  
  21. bootstrap Text::Iconv $VERSION;
  22.  
  23. # Preloaded methods go here.
  24.  
  25. # Autoload methods go after =cut, and are processed by the autosplit program.
  26.  
  27. 1;
  28. __END__
  29. # Below is the documentation for the module.
  30.  
  31. =head1 NAME
  32.  
  33. Text::Iconv - Perl interface to iconv() codeset conversion function
  34.  
  35. =head1 SYNOPSIS
  36.  
  37.   use Text::Iconv;
  38.   $converter = Text::Iconv->new("fromcode", "tocode");
  39.   $converted = $converter->convert("Text to convert");
  40.  
  41. =head1 DESCRIPTION
  42.  
  43. The B<Text::Iconv> module provides a Perl interface to the iconv()
  44. function as defined by the Single UNIX Specification.  The convert()
  45. method converts the encoding of characters in the input string from
  46. the I<fromcode> codeset to the I<tocode> codeset, and returns the
  47. result.
  48.  
  49. Settings of I<fromcode> and I<tocode> and their permitted combinations
  50. are implementation-dependent.  Valid values are specified in the
  51. system documentation
  52.  
  53. As an experimental feature, this version of B<Text::Iconv> objects
  54. provide the retval() method:
  55.  
  56.   $result = $converter->convert("lorem ipsum dolor sit amet");
  57.   $retval = $converter->retval;
  58.  
  59. This method can be called after calling convert().  It returns the
  60. return value of the underlying iconv() function for the last
  61. conversion; according to the Single UNIX Specification, this value
  62. indicates "the number of non-identical conversions performed."  Note,
  63. however, that iconv implementations vary widely in the interpretation
  64. of this specification.
  65.  
  66. When called before the first call to convert(), or if an error occured
  67. during the conversion, retval() returns B<undef>.
  68.  
  69. =head1 ERRORS
  70.  
  71. If the conversion can't be initialized an exception is raised (using
  72. croak()).
  73.  
  74. =head2 Handling of conversion errors
  75.  
  76. I<Text::Iconv> provides a class attribute B<raise_error> and a
  77. corresponding class method for setting and getting its value.  The
  78. handling of errors during conversion depends on the setting of this
  79. attribute.  If B<raise_error> is set to a true value, an exception is
  80. raised; otherwise, the convert() method only returns B<undef>.  By
  81. default B<raise_error> is false.  Example usage:
  82.  
  83.   Text::Iconv->raise_error(1);     # Conversion errors raise exceptions
  84.   Text::Iconv->raise_error(0);     # Conversion errors return undef
  85.   $a = Text::Iconv->raise_error(); # Get current setting
  86.  
  87. =head2 Per-object handling of conversion errors
  88.  
  89. As an experimental feature, I<Text::Iconv> also provides an instance
  90. attribute B<raise_error> and a corresponding method for setting and
  91. getting its value.  If B<raise_error> is B<undef>, the class-wide
  92. settings apply.  If B<raise_error> is 1 or 0 (true or false), the
  93. object settings override the class-wide settings.
  94.  
  95. Consult L<iconv(3)> for details on errors that might occur.
  96.  
  97. =head2 Conversion of B<undef>
  98.  
  99. Converting B<undef>, e.g.,
  100.  
  101.   $converted = $converter->convert(undef);
  102.  
  103. always returns B<undef>.  This is not considered an error.
  104.  
  105. =head1 NOTES
  106.  
  107. The supported codesets, their names, the supported conversions, and
  108. the quality of the conversions are all system-dependent.
  109.  
  110. =head1 AUTHOR
  111.  
  112. Michael Piotrowski <mxp@dynalabs.de>
  113.  
  114. =head1 SEE ALSO
  115.  
  116. iconv(1), iconv(3)
  117.  
  118. =cut
  119.