diff options
Diffstat (limited to 'upstream/archlinux/man3/ExtUtils::Constant::Base.3perl')
| -rw-r--r-- | upstream/archlinux/man3/ExtUtils::Constant::Base.3perl | 255 |
1 files changed, 255 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/ExtUtils::Constant::Base.3perl b/upstream/archlinux/man3/ExtUtils::Constant::Base.3perl new file mode 100644 index 00000000..7bb99479 --- /dev/null +++ b/upstream/archlinux/man3/ExtUtils::Constant::Base.3perl @@ -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 3perl" +.TH ExtUtils::Constant::Base 3perl 2024-02-11 "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 |