Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 255 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/ExtUtils::Constant::Base.3pm b/upstream/mageia-cauldron/man3pm/ExtUtils::Constant::Base.3pm
new file mode 100644
index 00000000..9b2ab9f2
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/ExtUtils::Constant::Base.3pm
@@ -0,0 +1,255 @@
+.\" -*- 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 "ExtUtils::Constant::Base 3pm"
+.TH ExtUtils::Constant::Base 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
+ExtUtils::Constant::Base \- base class for ExtUtils::Constant objects
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&    require ExtUtils::Constant::Base;
+\&    @ISA = \*(AqExtUtils::Constant::Base\*(Aq;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+ExtUtils::Constant::Base provides a base implementation of methods to
+generate C code to give fast constant value lookup by named string. Currently
+it's mostly used ExtUtils::Constant::XS, which generates the lookup code
+for the \fBconstant()\fR subroutine found in many XS modules.
+.SH USAGE
+.IX Header "USAGE"
+ExtUtils::Constant::Base exports no subroutines. The following methods are
+available
+.IP header 4
+.IX Item "header"
+A method returning a scalar containing definitions needed, typically for a
+C header file.
+.IP "memEQ_clause args_hashref" 4
+.IX Item "memEQ_clause args_hashref"
+A method to return a suitable C \f(CW\*(C`if\*(C'\fR statement to check whether \fIname\fR
+is equal to the C variable \f(CW\*(C`name\*(C'\fR. If \fIchecked_at\fR is defined, then it
+is used to avoid \f(CW\*(C`memEQ\*(C'\fR for short names, or to generate a comment to
+highlight the position of the character in the \f(CW\*(C`switch\*(C'\fR statement.
+.Sp
+If i<checked_at> is a reference to a scalar, then instead it gives
+the characters pre-checked at the beginning, (and the number of chars by
+which the C variable name has been advanced. These need to be chopped from
+the front of \fIname\fR).
+.IP "dump_names arg_hashref, ITEM..." 4
+.IX Item "dump_names arg_hashref, ITEM..."
+An internal function to generate the embedded perl code that will regenerate
+the constant subroutines.  \fIdefault_type\fR, \fItypes\fR and \fIITEM\fRs are the
+same as for C_constant.  \fIindent\fR is treated as number of spaces to indent
+by.  If \f(CW\*(C`declare_types\*(C'\fR is true a \f(CW$types\fR is always declared in the perl
+code generated, if defined and false never declared, and if undefined \f(CW$types\fR
+is only declared if the values in \fItypes\fR as passed in cannot be inferred from
+\&\fIdefault_types\fR and the \fIITEM\fRs.
+.IP "assign arg_hashref, VALUE..." 4
+.IX Item "assign arg_hashref, VALUE..."
+A method to return a suitable assignment clause. If \fItype\fR is aggregate
+(eg \fIPVN\fR expects both pointer and length) then there should be multiple
+\&\fIVALUE\fRs for the components. \fIpre\fR and \fIpost\fR if defined give snippets
+of C code to proceed and follow the assignment. \fIpre\fR will be at the start
+of a block, so variables may be defined in it.
+.IP "return_clause arg_hashref, ITEM" 4
+.IX Item "return_clause arg_hashref, ITEM"
+A method to return a suitable \f(CW\*(C`#ifdef\*(C'\fR clause. \fIITEM\fR is a hashref
+(as passed to \f(CW\*(C`C_constant\*(C'\fR and \f(CW\*(C`match_clause\*(C'\fR. \fIindent\fR is the number
+of spaces to indent, defaulting to 6.
+.IP "switch_clause arg_hashref, NAMELEN, ITEMHASH, ITEM..." 4
+.IX Item "switch_clause arg_hashref, NAMELEN, ITEMHASH, ITEM..."
+An internal method to generate a suitable \f(CW\*(C`switch\*(C'\fR clause, called by
+\&\f(CW\*(C`C_constant\*(C'\fR \fIITEM\fRs are in the hash ref format as given in the description
+of \f(CW\*(C`C_constant\*(C'\fR, and must all have the names of the same length, given by
+\&\fINAMELEN\fR.  \fIITEMHASH\fR is a reference to a hash, keyed by name, values being
+the hashrefs in the \fIITEM\fR list.  (No parameters are modified, and there can
+be keys in the \fIITEMHASH\fR that are not in the list of \fIITEM\fRs without
+causing problems \- the hash is passed in to save generating it afresh for
+each call).
+.IP "params WHAT" 4
+.IX Item "params WHAT"
+An "internal" method, subject to change, currently called to allow an
+overriding class to cache information that will then be passed into all
+the \f(CW\*(C`*param*\*(C'\fR calls. (Yes, having to read the source to make sense of this is
+considered a known bug). \fIWHAT\fR is be a hashref of types the constant
+function will return. In ExtUtils::Constant::XS this method is used to
+returns a hashref keyed IV NV PV SV to show which combination of pointers will
+be needed in the C argument list generated by
+C_constant_other_params_definition and C_constant_other_params
+.IP "dogfood arg_hashref, ITEM..." 4
+.IX Item "dogfood arg_hashref, ITEM..."
+An internal function to generate the embedded perl code that will regenerate
+the constant subroutines.  Parameters are the same as for C_constant.
+.Sp
+Currently the base class does nothing and returns an empty string.
+.IP "normalise_items args, default_type, seen_types, seen_items, ITEM..." 4
+.IX Item "normalise_items args, default_type, seen_types, seen_items, ITEM..."
+Convert the items to a normalised form. For 8 bit and Unicode values converts
+the item to an array of 1 or 2 items, both 8 bit and UTF\-8 encoded.
+.IP "C_constant arg_hashref, ITEM..." 4
+.IX Item "C_constant arg_hashref, ITEM..."
+A function that returns a \fBlist\fR of C subroutine definitions that return
+the value and type of constants when passed the name by the XS wrapper.
+\&\fIITEM...\fR gives a list of constant names. Each can either be a string,
+which is taken as a C macro name, or a reference to a hash with the following
+keys
+.RS 4
+.IP name 8
+.IX Item "name"
+The name of the constant, as seen by the perl code.
+.IP type 8
+.IX Item "type"
+The type of the constant (\fIIV\fR, \fINV\fR etc)
+.IP value 8
+.IX Item "value"
+A C expression for the value of the constant, or a list of C expressions if
+the type is aggregate. This defaults to the \fIname\fR if not given.
+.IP macro 8
+.IX Item "macro"
+The C pre-processor macro to use in the \f(CW\*(C`#ifdef\*(C'\fR. This defaults to the
+\&\fIname\fR, and is mainly used if \fIvalue\fR is an \f(CW\*(C`enum\*(C'\fR. If a reference an
+array is passed then the first element is used in place of the \f(CW\*(C`#ifdef\*(C'\fR
+line, and the second element in place of the \f(CW\*(C`#endif\*(C'\fR. This allows
+pre-processor constructions such as
+.Sp
+.Vb 5
+\&    #if defined (foo)
+\&    #if !defined (bar)
+\&    ...
+\&    #endif
+\&    #endif
+.Ve
+.Sp
+to be used to determine if a constant is to be defined.
+.Sp
+A "macro" 1 signals that the constant is always defined, so the \f(CW\*(C`#if\*(C'\fR/\f(CW\*(C`#endif\*(C'\fR
+test is omitted.
+.IP default 8
+.IX Item "default"
+Default value to use (instead of \f(CW\*(C`croak\*(C'\fRing with "your vendor has not
+defined...") to return if the macro isn't defined. Specify a reference to
+an array with type followed by value(s).
+.IP pre 8
+.IX Item "pre"
+C code to use before the assignment of the value of the constant. This allows
+you to use temporary variables to extract a value from part of a \f(CW\*(C`struct\*(C'\fR
+and return this as \fIvalue\fR. This C code is places at the start of a block,
+so you can declare variables in it.
+.IP post 8
+.IX Item "post"
+C code to place between the assignment of value (to a temporary) and the
+return from the function. This allows you to clear up anything in \fIpre\fR.
+Rarely needed.
+.IP def_pre 8
+.IX Item "def_pre"
+.PD 0
+.IP def_post 8
+.IX Item "def_post"
+.PD
+Equivalents of \fIpre\fR and \fIpost\fR for the default value.
+.IP utf8 8
+.IX Item "utf8"
+Generated internally. Is zero or undefined if name is 7 bit ASCII,
+"no" if the name is 8 bit (and so should only match if \fBSvUTF8()\fR is false),
+"yes" if the name is utf8 encoded.
+.Sp
+The internals automatically clone any name with characters 128\-255 but none
+256+ (ie one that could be either in bytes or utf8) into a second entry
+which is utf8 encoded.
+.IP weight 8
+.IX Item "weight"
+Optional sorting weight for names, to determine the order of
+linear testing when multiple names fall in the same case of a switch clause.
+Higher comes earlier, undefined defaults to zero.
+.RE
+.RS 4
+.Sp
+In the argument hashref, \fIpackage\fR is the name of the package, and is only
+used in comments inside the generated C code. \fIsubname\fR defaults to
+\&\f(CW\*(C`constant\*(C'\fR if undefined.
+.Sp
+\&\fIdefault_type\fR is the type returned by \f(CW\*(C`ITEM\*(C'\fRs that don't specify their
+type. It defaults to the value of \f(CWdefault_type()\fR. \fItypes\fR should be given
+either as a comma separated list of types that the C subroutine \fIsubname\fR
+will generate or as a reference to a hash. \fIdefault_type\fR will be added to
+the list if not present, as will any types given in the list of \fIITEM\fRs. The
+resultant list should be the same list of types that \f(CW\*(C`XS_constant\*(C'\fR is
+given. [Otherwise \f(CW\*(C`XS_constant\*(C'\fR and \f(CW\*(C`C_constant\*(C'\fR may differ in the number of
+parameters to the constant function. \fIindent\fR is currently unused and
+ignored. In future it may be used to pass in information used to change the C
+indentation style used.]  The best way to maintain consistency is to pass in a
+hash reference and let this function update it.
+.Sp
+\&\fIbreakout\fR governs when child functions of \fIsubname\fR are generated.  If there
+are \fIbreakout\fR or more \fIITEM\fRs with the same length of name, then the code
+to switch between them is placed into a function named \fIsubname\fR_\fIlen\fR, for
+example \f(CW\*(C`constant_5\*(C'\fR for names 5 characters long.  The default \fIbreakout\fR is
+3.  A single \f(CW\*(C`ITEM\*(C'\fR is always inlined.
+.RE
+.SH BUGS
+.IX Header "BUGS"
+Not everything is documented yet.
+.PP
+Probably others.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Nicholas Clark <nick@ccl4.org> based on the code in \f(CW\*(C`h2xs\*(C'\fR by Larry Wall and
+others