From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/debian-unstable/man3/builtin.3perl | 409 ++++++++++++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 upstream/debian-unstable/man3/builtin.3perl (limited to 'upstream/debian-unstable/man3/builtin.3perl') diff --git a/upstream/debian-unstable/man3/builtin.3perl b/upstream/debian-unstable/man3/builtin.3perl new file mode 100644 index 00000000..494087f2 --- /dev/null +++ b/upstream/debian-unstable/man3/builtin.3perl @@ -0,0 +1,409 @@ +.\" -*- 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 "builtin 3perl" +.TH builtin 3perl 2024-01-12 "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 +builtin \- Perl pragma to import built\-in utility functions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 11 +\& use builtin qw( +\& true false is_bool +\& weaken unweaken is_weak +\& blessed refaddr reftype +\& created_as_string created_as_number +\& ceil floor +\& indexed +\& trim +\& is_tainted +\& export_lexically +\& ); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Perl provides several utility functions in the \f(CW\*(C`builtin\*(C'\fR package. These are +plain functions, and look and behave just like regular user-defined functions +do. They do not provide new syntax or require special parsing. These functions +are always present in the interpreter and can be called at any time by their +fully-qualified names. By default they are not available as short names, but +can be requested for convenience. +.PP +Individual named functions can be imported by listing them as import +parameters on the \f(CW\*(C`use\*(C'\fR statement for this pragma. +.PP +The overall \f(CW\*(C`builtin\*(C'\fR mechanism, as well as every individual function it +provides, are currently \fBexperimental\fR. +.PP +\&\fBWarning\fR: At present, the entire \f(CW\*(C`builtin\*(C'\fR namespace is experimental. +Calling functions in it will trigger warnings of the \f(CW\*(C`experimental::builtin\*(C'\fR +category. +.SS "Lexical Import" +.IX Subsection "Lexical Import" +This pragma module creates \fIlexical\fR aliases in the currently-compiling scope +to these builtin functions. This is similar to the lexical effect of other +pragmas such as strict and feature. +.PP +.Vb 3 +\& sub classify +\& { +\& my $val = shift; +\& +\& use builtin \*(Aqis_bool\*(Aq; +\& return is_bool($val) ? "boolean" : "not a boolean"; +\& } +\& +\& # the is_bool() function is no longer visible here +\& # but may still be called by builtin::is_bool() +.Ve +.PP +Because these functions are imported lexically, rather than by package +symbols, the user does not need to take any special measures to ensure they +don't accidentally appear as object methods from a class. +.PP +.Vb 4 +\& package An::Object::Class { +\& use builtin \*(Aqtrue\*(Aq, \*(Aqfalse\*(Aq; +\& ... +\& } +\& +\& # does not appear as a method +\& An::Object::Class\->true; +\& +\& # Can\*(Aqt locate object method "true" via package "An::Object::Class" +\& # at ... +.Ve +.SH FUNCTIONS +.IX Header "FUNCTIONS" +.SS true +.IX Subsection "true" +.Vb 1 +\& $val = true; +.Ve +.PP +Returns the boolean truth value. While any scalar value can be tested for +truth and most defined, non-empty and non-zero values are considered "true" +by perl, this one is special in that "is_bool" considers it to be a +distinguished boolean value. +.PP +This gives an equivalent value to expressions like \f(CW\*(C`!!1\*(C'\fR or \f(CW\*(C`!0\*(C'\fR. +.SS false +.IX Subsection "false" +.Vb 1 +\& $val = false; +.Ve +.PP +Returns the boolean fiction value. While any non-true scalar value is +considered "false" by perl, this one is special in that "is_bool" considers +it to be a distinguished boolean value. +.PP +This gives an equivalent value to expressions like \f(CW\*(C`!!0\*(C'\fR or \f(CW\*(C`!1\*(C'\fR. +.SS is_bool +.IX Subsection "is_bool" +.Vb 1 +\& $bool = is_bool($val); +.Ve +.PP +Returns true when given a distinguished boolean value, or false if not. A +distinguished boolean value is the result of any boolean-returning builtin +function (such as \f(CW\*(C`true\*(C'\fR or \f(CW\*(C`is_bool\*(C'\fR itself), boolean-returning operator +(such as the \f(CW\*(C`eq\*(C'\fR or \f(CW\*(C`==\*(C'\fR comparison tests or the \f(CW\*(C`!\*(C'\fR negation operator), +or any variable containing one of these results. +.PP +This function used to be named \f(CW\*(C`isbool\*(C'\fR. A compatibility alias is provided +currently but will be removed in a later version. +.SS weaken +.IX Subsection "weaken" +.Vb 1 +\& weaken($ref); +.Ve +.PP +Weakens a reference. A weakened reference does not contribute to the reference +count of its referent. If only weakened references to a referent remain, it +will be disposed of, and all remaining weak references to it will have their +value set to \f(CW\*(C`undef\*(C'\fR. +.SS unweaken +.IX Subsection "unweaken" +.Vb 1 +\& unweaken($ref); +.Ve +.PP +Strengthens a reference, undoing the effects of a previous call to "weaken". +.SS is_weak +.IX Subsection "is_weak" +.Vb 1 +\& $bool = is_weak($ref); +.Ve +.PP +Returns true when given a weakened reference, or false if not a reference or +not weak. +.PP +This function used to be named \f(CW\*(C`isweak\*(C'\fR. A compatibility alias is provided +currently but will be removed in a later version. +.SS blessed +.IX Subsection "blessed" +.Vb 1 +\& $str = blessed($ref); +.Ve +.PP +Returns the package name for an object reference, or \f(CW\*(C`undef\*(C'\fR for a +non-reference or reference that is not an object. +.SS refaddr +.IX Subsection "refaddr" +.Vb 1 +\& $num = refaddr($ref); +.Ve +.PP +Returns the memory address for a reference, or \f(CW\*(C`undef\*(C'\fR for a non-reference. +This value is not likely to be very useful for pure Perl code, but is handy as +a means to test for referential identity or uniqueness. +.SS reftype +.IX Subsection "reftype" +.Vb 1 +\& $str = reftype($ref); +.Ve +.PP +Returns the basic container type of the referent of a reference, or \f(CW\*(C`undef\*(C'\fR +for a non-reference. This is returned as a string in all-capitals, such as +\&\f(CW\*(C`ARRAY\*(C'\fR for array references, or \f(CW\*(C`HASH\*(C'\fR for hash references. +.SS created_as_string +.IX Subsection "created_as_string" +.Vb 1 +\& $bool = created_as_string($val); +.Ve +.PP +Returns a boolean representing if the argument value was originally created as +a string. It will return true for any scalar expression whose most recent +assignment or modification was of a string-like nature \- such as assignment +from a string literal, or the result of a string operation such as +concatenation or regexp. It will return false for references (including any +object), numbers, booleans and undef. +.PP +It is unlikely that you will want to use this for regular data validation +within Perl, as it will not return true for regular numbers that are still +perfectly usable as strings, nor for any object reference \- especially objects +that overload the stringification operator in an attempt to behave more like +strings. For example +.PP +.Vb 1 +\& my $val = URI\->new( "https://metacpan.org/" ); +\& +\& if( created_as_string $val ) { ... } # this will not execute +.Ve +.SS created_as_number +.IX Subsection "created_as_number" +.Vb 1 +\& $bool = created_as_number($val); +.Ve +.PP +Returns a boolean representing if the argument value was originally created as +a number. It will return true for any scalar expression whose most recent +assignment or modification was of a numerical nature \- such as assignment from +a number literal, or the result of a numerical operation such as addition. It +will return false for references (including any object), strings, booleans and +undef. +.PP +It is unlikely that you will want to use this for regular data validation +within Perl, as it will not return true for regular strings of decimal digits +that are still perfectly usable as numbers, nor for any object reference \- +especially objects that overload the numification operator in an attempt to +behave more like numbers. For example +.PP +.Vb 1 +\& my $val = Math::BigInt\->new( 123 ); +\& +\& if( created_as_number $val ) { ... } # this will not execute +.Ve +.PP +While most Perl code should operate on scalar values without needing to know +their creation history, these two functions are intended to be used by data +serialisation modules such as JSON encoders or similar situations, where +language interoperability concerns require making a distinction between values +that are fundamentally stringlike versus numberlike in nature. +.SS ceil +.IX Subsection "ceil" +.Vb 1 +\& $num = ceil($num); +.Ve +.PP +Returns the smallest integer value greater than or equal to the given +numerical argument. +.SS floor +.IX Subsection "floor" +.Vb 1 +\& $num = floor($num); +.Ve +.PP +Returns the largest integer value less than or equal to the given numerical +argument. +.SS indexed +.IX Subsection "indexed" +.Vb 1 +\& @ivpairs = indexed(@items) +.Ve +.PP +Returns an even-sized list of number/value pairs, where each pair is formed +of a number giving an index in the original list followed by the value at that +position in it. I.e. returns a list twice the size of the original, being +equal to +.PP +.Vb 1 +\& (0, $items[0], 1, $items[1], 2, $items[2], ...) +.Ve +.PP +Note that unlike the core \f(CW\*(C`values\*(C'\fR function, this function returns copies of +its original arguments, not aliases to them. Any modifications of these copies +are \fInot\fR reflected in modifications to the original. +.PP +.Vb 2 +\& my @x = ...; +\& $_++ for indexed @x; # The @x array remains unaffected +.Ve +.PP +This function is primarily intended to be useful combined with multi-variable +\&\f(CW\*(C`foreach\*(C'\fR loop syntax; as +.PP +.Vb 3 +\& foreach my ($index, $value) (indexed LIST) { +\& ... +\& } +.Ve +.PP +In scalar context this function returns the size of the list that it would +otherwise have returned, and provokes a warning in the \f(CW\*(C`scalar\*(C'\fR category. +.SS trim +.IX Subsection "trim" +.Vb 1 +\& $stripped = trim($string); +.Ve +.PP +Returns the input string with whitespace stripped from the beginning +and end. \fBtrim()\fR will remove these characters: +.PP +" ", an ordinary space. +.PP +"\et", a tab. +.PP +"\en", a new line (line feed). +.PP +"\er", a carriage return. +.PP +and all other Unicode characters that are flagged as whitespace. +A complete list is in "Whitespace" in perlrecharclass. +.PP +.Vb 4 +\& $var = " Hello world "; # "Hello world" +\& $var = "\et\et\etHello world"; # "Hello world" +\& $var = "Hello world\en"; # "Hello world" +\& $var = "\ex{2028}Hello world\ex{3000}"; # "Hello world" +.Ve +.PP +\&\f(CW\*(C`trim\*(C'\fR is equivalent to: +.PP +.Vb 1 +\& $str =~ s/\eA\es+|\es+\ez//urg; +.Ve +.PP +For Perl versions where this feature is not available look at the +String::Util module for a comparable implementation. +.SS is_tainted +.IX Subsection "is_tainted" +.Vb 1 +\& $bool = is_tainted($var); +.Ve +.PP +Returns true when given a tainted variable. +.SS export_lexically +.IX Subsection "export_lexically" +.Vb 1 +\& export_lexically($name1, $ref1, $name2, $ref2, ...) +.Ve +.PP +Exports new lexical names into the scope currently being compiled. Names given +by the first of each pair of values will refer to the corresponding item whose +reference is given by the second. Types of item that are permitted are +subroutines, and scalar, array, and hash variables. If the item is a +subroutine, the name may optionally be prefixed with the \f(CW\*(C`&\*(C'\fR sigil, but for +convenience it doesn't have to. For items that are variables the sigil is +required, and must match the type of the variable. +.PP +.Vb 2 +\& export_lexically func => \e&func, +\& \*(Aq&func\*(Aq => \e&func; # same as above +\& +\& export_lexically \*(Aq$scalar\*(Aq => \emy $var; +.Ve +.PP + +.PP +.Vb 3 +\& # The following are not permitted +\& export_lexically \*(Aq$var\*(Aq => \e@arr; # sigil does not match +\& export_lexically name => \e$scalar; # implied \*(Aq&\*(Aq sigil does not match +\& +\& export_lexically \*(Aq*name\*(Aq => \e*globref; # globrefs are not supported +.Ve +.PP +This must be called at compile time; which typically means during a \f(CW\*(C`BEGIN\*(C'\fR +block. Usually this would be used as part of an \f(CW\*(C`import\*(C'\fR method of a module, +when invoked as part of a \f(CW\*(C`use ...\*(C'\fR statement. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +perlop, perlfunc, Scalar::Util -- cgit v1.2.3