summaryrefslogtreecommitdiffstats
path: root/upstream/mageia-cauldron/man3pm/Encode::Encoder.3pm
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:43:11 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:43:11 +0000
commitfc22b3d6507c6745911b9dfcc68f1e665ae13dbc (patch)
treece1e3bce06471410239a6f41282e328770aa404a /upstream/mageia-cauldron/man3pm/Encode::Encoder.3pm
parentInitial commit. (diff)
downloadmanpages-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.3pm200
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