diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:43:11 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:43:11 +0000 |
commit | fc22b3d6507c6745911b9dfcc68f1e665ae13dbc (patch) | |
tree | ce1e3bce06471410239a6f41282e328770aa404a /upstream/mageia-cauldron/man3pm/Encode::Encoder.3pm | |
parent | Initial commit. (diff) | |
download | manpages-l10n-fc22b3d6507c6745911b9dfcc68f1e665ae13dbc.tar.xz manpages-l10n-fc22b3d6507c6745911b9dfcc68f1e665ae13dbc.zip |
Adding upstream version 4.22.0.upstream/4.22.0
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Encode::Encoder.3pm')
-rw-r--r-- | upstream/mageia-cauldron/man3pm/Encode::Encoder.3pm | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Encode::Encoder.3pm b/upstream/mageia-cauldron/man3pm/Encode::Encoder.3pm new file mode 100644 index 00000000..3ca1ae9a --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Encode::Encoder.3pm @@ -0,0 +1,200 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Encode::Encoder 3pm" +.TH Encode::Encoder 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Encode::Encoder \-\- Object Oriented Encoder +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 10 +\& use Encode::Encoder; +\& # Encode::encode("ISO\-8859\-1", $data); +\& Encode::Encoder\->new($data)\->iso_8859_1; # OOP way +\& # shortcut +\& use Encode::Encoder qw(encoder); +\& encoder($data)\->iso_8859_1; +\& # you can stack them! +\& encoder($data)\->iso_8859_1\->base64; # provided base64() is defined +\& # you can use it as a decoder as well +\& encoder($base64)\->bytes(\*(Aqbase64\*(Aq)\->latin1; +\& # stringified +\& print encoder($data)\->utf8\->latin1; # prints the string in latin1 +\& # numified +\& encoder("\ex{abcd}\ex{ef}g")\->utf8 == 6; # true. bytes::length($data) +.Ve +.SH ABSTRACT +.IX Header "ABSTRACT" +\&\fBEncode::Encoder\fR allows you to use Encode in an object-oriented +style. This is not only more intuitive than a functional approach, +but also handier when you want to stack encodings. Suppose you want +your UTF\-8 string converted to Latin1 then Base64: you can simply say +.PP +.Vb 1 +\& my $base64 = encoder($utf8)\->latin1\->base64; +.Ve +.PP +instead of +.PP +.Vb 2 +\& my $latin1 = encode("latin1", $utf8); +\& my $base64 = encode_base64($utf8); +.Ve +.PP +or the lazier and more convoluted +.PP +.Vb 1 +\& my $base64 = encode_base64(encode("latin1", $utf8)); +.Ve +.SH Description +.IX Header "Description" +Here is how to use this module. +.IP \(bu 4 +There are at least two instance variables stored in a hash reference, +{data} and {encoding}. +.IP \(bu 4 +When there is no method, it takes the method name as the name of the +encoding and encodes the instance \fIdata\fR with \fIencoding\fR. If successful, +the instance \fIencoding\fR is set accordingly. +.IP \(bu 4 +You can retrieve the result via \->data but usually you don't have to +because the stringify operator ("") is overridden to do exactly that. +.SS "Predefined Methods" +.IX Subsection "Predefined Methods" +This module predefines the methods below: +.ie n .IP "$e = Encode::Encoder\->new([$data, $encoding]);" 4 +.el .IP "\f(CW$e\fR = Encode::Encoder\->new([$data, \f(CW$encoding\fR]);" 4 +.IX Item "$e = Encode::Encoder->new([$data, $encoding]);" +returns an encoder object. Its data is initialized with \f(CW$data\fR if +present, and its encoding is set to \f(CW$encoding\fR if present. +.Sp +When \f(CW$encoding\fR is omitted, it defaults to utf8 if \f(CW$data\fR is already in +utf8 or "" (empty string) otherwise. +.IP \fBencoder()\fR 4 +.IX Item "encoder()" +is an alias of Encode::Encoder\->\fBnew()\fR. This one is exported on demand. +.ie n .IP $e\->data([$data]) 4 +.el .IP \f(CW$e\fR\->data([$data]) 4 +.IX Item "$e->data([$data])" +When \f(CW$data\fR is present, sets the instance data to \f(CW$data\fR and returns the +object itself. Otherwise, the current instance data is returned. +.ie n .IP $e\->encoding([$encoding]) 4 +.el .IP \f(CW$e\fR\->encoding([$encoding]) 4 +.IX Item "$e->encoding([$encoding])" +When \f(CW$encoding\fR is present, sets the instance encoding to \f(CW$encoding\fR and +returns the object itself. Otherwise, the current instance encoding is +returned. +.ie n .IP $e\->bytes([$encoding]) 4 +.el .IP \f(CW$e\fR\->bytes([$encoding]) 4 +.IX Item "$e->bytes([$encoding])" +decodes instance data from \f(CW$encoding\fR, or the instance encoding if +omitted. If the conversion is successful, the instance encoding +will be set to "". +.Sp +The name \fIbytes\fR was deliberately picked to avoid namespace tainting +\&\-\- this module may be used as a base class so method names that appear +in Encode::Encoding are avoided. +.SS "Example: base64 transcoder" +.IX Subsection "Example: base64 transcoder" +This module is designed to work with Encode::Encoding. +To make the Base64 transcoder example above really work, you could +write a module like this: +.PP +.Vb 10 +\& package Encode::Base64; +\& use parent \*(AqEncode::Encoding\*(Aq; +\& _\|_PACKAGE_\|_\->Define(\*(Aqbase64\*(Aq); +\& use MIME::Base64; +\& sub encode{ +\& my ($obj, $data) = @_; +\& return encode_base64($data); +\& } +\& sub decode{ +\& my ($obj, $data) = @_; +\& return decode_base64($data); +\& } +\& 1; +\& _\|_END_\|_ +.Ve +.PP +And your caller module would be something like this: +.PP +.Vb 2 +\& use Encode::Encoder; +\& use Encode::Base64; +\& +\& # now you can really do the following +\& +\& encoder($data)\->iso_8859_1\->base64; +\& encoder($base64)\->bytes(\*(Aqbase64\*(Aq)\->latin1; +.Ve +.SS "Operator Overloading" +.IX Subsection "Operator Overloading" +This module overloads two operators, stringify ("") and numify (0+). +.PP +Stringify dumps the data inside the object. +.PP +Numify returns the number of bytes in the instance data. +.PP +They come in handy when you want to print or find the size of data. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Encode, +Encode::Encoding |