mingw/html/lib/Encode/Encoder.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Encode::Encoder -- Object Oriented Encoder</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Encode::Encoder -- Object Oriented Encoder</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#abstract">ABSTRACT</a></li>
  25         <li><a href="#description">Description</a></li>
  26         <ul>
  27
  28                 <li><a href="#predefined_methods">Predefined Methods</a></li>
  29                 <li><a href="#example__base64_transcoder">Example: base64 transcoder</a></li>
  30                 <li><a href="#operator_overloading">Operator Overloading</a></li>
  31         </ul>
  32
  33         <li><a href="#see_also">SEE ALSO</a></li>
  34 </ul>
  35 <!-- INDEX END -->
  36
  37 <hr />
  38 <p>
  39 </p>
  40 <h1><a name="name">NAME</a></h1>
  41 <p>Encode::Encoder -- Object Oriented Encoder</p>
  42 <p>
  43 </p>
  44 <hr />
  45 <h1><a name="synopsis">SYNOPSIS</a></h1>
  46 <pre>
  47   use Encode::Encoder;
  48   # Encode::encode(&quot;ISO-8859-1&quot;, $data);
  49   Encode::Encoder-&gt;new($data)-&gt;iso_8859_1; # OOP way
  50   # shortcut
  51   use Encode::Encoder qw(encoder);
  52   encoder($data)-&gt;iso_8859_1;
  53   # you can stack them!
  54   encoder($data)-&gt;iso_8859_1-&gt;base64;  # provided base64() is defined
  55   # you can use it as a decoder as well
  56   encoder($base64)-&gt;bytes('base64')-&gt;latin1;
  57   # stringified
  58   print encoder($data)-&gt;utf8-&gt;latin1;  # prints the string in latin1
  59   # numified
  60   encoder(&quot;\x{abcd}\x{ef}g&quot;)-&gt;utf8 == 6; # true. bytes::length($data)</pre>
  61 <p>
  62 </p>
  63 <hr />
  64 <h1><a name="abstract">ABSTRACT</a></h1>
  65 <p><strong>Encode::Encoder</strong> allows you to use Encode in an object-oriented
  66 style.  This is not only more intuitive than a functional approach,
  67 but also handier when you want to stack encodings.  Suppose you want
  68 your UTF-8 string converted to Latin1 then Base64: you can simply say</p>
  69 <pre>
  70   my $base64 = encoder($utf8)-&gt;latin1-&gt;base64;</pre>
  71 <p>instead of</p>
  72 <pre>
  73   my $latin1 = encode(&quot;latin1&quot;, $utf8);
  74   my $base64 = encode_base64($utf8);</pre>
  75 <p>or the lazier and more convoluted</p>
  76 <pre>
  77   my $base64 = encode_base64(encode(&quot;latin1&quot;, $utf8));</pre>
  78 <p>
  79 </p>
  80 <hr />
  81 <h1><a name="description">Description</a></h1>
  82 <p>Here is how to use this module.</p>
  83 <ul>
  84 <li>
  85 <p>There are at least two instance variables stored in a hash reference,
  86 {data} and {encoding}.</p>
  87 </li>
  88 <li>
  89 <p>When there is no method, it takes the method name as the name of the
  90 encoding and encodes the instance <em>data</em> with <em>encoding</em>.  If successful,
  91 the instance <em>encoding</em> is set accordingly.</p>
  92 </li>
  93 <li>
  94 <p>You can retrieve the result via -&gt;data but usually you don't have to
  95 because the stringify operator (``'') is overridden to do exactly that.</p>
  96 </li>
  97 </ul>
  98 <p>
  99 </p>
 100 <h2><a name="predefined_methods">Predefined Methods</a></h2>
 101 <p>This module predefines the methods below:</p>
 102 <dl>
 103 <dt><strong><a name="item_new">$e = Encode::Encoder-&gt;new([$data, $encoding]);</a></strong>
 104
 105 <dd>
 106 <p>returns an encoder object.  Its data is initialized with $data if
 107 present, and its encoding is set to $encoding if present.</p>
 108 </dd>
 109 <dd>
 110 <p>When $encoding is omitted, it defaults to utf8 if $data is already in
 111 utf8 or ``'' (empty string) otherwise.</p>
 112 </dd>
 113 </li>
 114 <dt><strong><a name="item_encoder"><code>encoder()</code></a></strong>
 115
 116 <dd>
 117 <p>is an alias of Encode::Encoder-&gt;new().  This one is exported on demand.</p>
 118 </dd>
 119 </li>
 120 <dt><strong><a name="item_data">$e-&gt;<code>data([$data])</code></a></strong>
 121
 122 <dd>
 123 <p>When $data is present, sets the instance data to $data and returns the
 124 object itself.  Otherwise, the current instance data is returned.</p>
 125 </dd>
 126 </li>
 127 <dt><strong><a name="item_encoding">$e-&gt;<code>encoding([$encoding])</code></a></strong>
 128
 129 <dd>
 130 <p>When $encoding is present, sets the instance encoding to $encoding and
 131 returns the object itself.  Otherwise, the current instance encoding is
 132 returned.</p>
 133 </dd>
 134 </li>
 135 <dt><strong><a name="item_bytes">$e-&gt;<code>bytes([$encoding])</code></a></strong>
 136
 137 <dd>
 138 <p>decodes instance data from $encoding, or the instance encoding if
 139 omitted.  If the conversion is successful, the instance encoding
 140 will be set to ``''.</p>
 141 </dd>
 142 <dd>
 143 <p>The name <em>bytes</em> was deliberately picked to avoid namespace tainting
 144 -- this module may be used as a base class so method names that appear
 145 in Encode::Encoding are avoided.</p>
 146 </dd>
 147 </li>
 148 </dl>
 149 <p>
 150 </p>
 151 <h2><a name="example__base64_transcoder">Example: base64 transcoder</a></h2>
 152 <p>This module is designed to work with <a href="file://C|\msysgit\mingw\html/lib/Encode/Encoding.html">the Encode::Encoding manpage</a>.
 153 To make the Base64 transcoder example above really work, you could
 154 write a module like this:</p>
 155 <pre>
 156   package Encode::Base64;
 157   use base 'Encode::Encoding';
 158   __PACKAGE__-&gt;Define('base64');
 159   use MIME::Base64;
 160   sub encode{
 161       my ($obj, $data) = @_;
 162       return encode_base64($data);
 163   }
 164   sub decode{
 165       my ($obj, $data) = @_;
 166       return decode_base64($data);
 167   }
 168   1;
 169   __END__</pre>
 170 <p>And your caller module would be something like this:</p>
 171 <pre>
 172   use Encode::Encoder;
 173   use Encode::Base64;</pre>
 174 <pre>
 175   # now you can really do the following</pre>
 176 <pre>
 177   encoder($data)-&gt;iso_8859_1-&gt;base64;
 178   encoder($base64)-&gt;bytes('base64')-&gt;latin1;</pre>
 179 <p>
 180 </p>
 181 <h2><a name="operator_overloading">Operator Overloading</a></h2>
 182 <p>This module overloads two operators, stringify (``'') and numify (0+).</p>
 183 <p>Stringify dumps the data inside the object.</p>
 184 <p>Numify returns the number of bytes in the instance data.</p>
 185 <p>They come in handy when you want to print or find the size of data.</p>
 186 <p>
 187 </p>
 188 <hr />
 189 <h1><a name="see_also">SEE ALSO</a></h1>
 190 <p><a href="file://C|\msysgit\mingw\html/lib/Encode.html">the Encode manpage</a>,
 191 <a href="file://C|\msysgit\mingw\html/lib/Encode/Encoding.html">the Encode::Encoding manpage</a></p>
 192 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 193 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 194 <big><strong><span class="block">&nbsp;Encode::Encoder -- Object Oriented Encoder</span></strong></big>
 195 </td></tr>
 196 </table>
 197
 198 </body>
 199
 200 </html>