1ExtUtils::Constant::BaseP(e3rplm)Programmers ReferenceEGxutiUdteils::Constant::Base(3pm)
2
3
4

NAME

6       ExtUtils::Constant::Base - base class for ExtUtils::Constant objects
7

SYNOPSIS

9           require ExtUtils::Constant::Base;
10           @ISA = 'ExtUtils::Constant::Base';
11

DESCRIPTION

13       ExtUtils::Constant::Base provides a base implementation of methods to
14       generate C code to give fast constant value lookup by named string.
15       Currently it's mostly used ExtUtils::Constant::XS, which generates the
16       lookup code for the constant() subroutine found in many XS modules.
17

USAGE

19       ExtUtils::Constant::Base exports no subroutines. The following methods
20       are available
21
22       header
23           A method returning a scalar containing definitions needed,
24           typically for a C header file.
25
26       memEQ_clause args_hashref
27           A method to return a suitable C "if" statement to check whether
28           name is equal to the C variable "name". If checked_at is defined,
29           then it is used to avoid "memEQ" for short names, or to generate a
30           comment to highlight the position of the character in the "switch"
31           statement.
32
33           If i<checked_at> is a reference to a scalar, then instead it gives
34           the characters pre-checked at the beginning, (and the number of
35           chars by which the C variable name has been advanced. These need to
36           be chopped from the front of name).
37
38       dump_names arg_hashref, ITEM...
39           An internal function to generate the embedded perl code that will
40           regenerate the constant subroutines.  default_type, types and ITEMs
41           are the same as for C_constant.  indent is treated as number of
42           spaces to indent by.  If "declare_types" is true a $types is always
43           declared in the perl code generated, if defined and false never
44           declared, and if undefined $types is only declared if the values in
45           types as passed in cannot be inferred from default_types and the
46           ITEMs.
47
48       assign arg_hashref, VALUE...
49           A method to return a suitable assignment clause. If type is
50           aggregate (eg PVN expects both pointer and length) then there
51           should be multiple VALUEs for the components. pre and post if
52           defined give snippets of C code to proceed and follow the
53           assignment. pre will be at the start of a block, so variables may
54           be defined in it.
55
56       return_clause arg_hashref, ITEM
57           A method to return a suitable "#ifdef" clause. ITEM is a hashref
58           (as passed to "C_constant" and "match_clause". indent is the number
59           of spaces to indent, defaulting to 6.
60
61       switch_clause arg_hashref, NAMELEN, ITEMHASH, ITEM...
62           An internal method to generate a suitable "switch" clause, called
63           by "C_constant" ITEMs are in the hash ref format as given in the
64           description of "C_constant", and must all have the names of the
65           same length, given by NAMELEN.  ITEMHASH is a reference to a hash,
66           keyed by name, values being the hashrefs in the ITEM list.  (No
67           parameters are modified, and there can be keys in the ITEMHASH that
68           are not in the list of ITEMs without causing problems - the hash is
69           passed in to save generating it afresh for each call).
70
71       params WHAT
72           An "internal" method, subject to change, currently called to allow
73           an overriding class to cache information that will then be passed
74           into all the "*param*" calls. (Yes, having to read the source to
75           make sense of this is considered a known bug). WHAT is be a hashref
76           of types the constant function will return. In
77           ExtUtils::Constant::XS this method is used to returns a hashref
78           keyed IV NV PV SV to show which combination of pointers will be
79           needed in the C argument list generated by
80           C_constant_other_params_definition and C_constant_other_params
81
82       dogfood arg_hashref, ITEM...
83           An internal function to generate the embedded perl code that will
84           regenerate the constant subroutines.  Parameters are the same as
85           for C_constant.
86
87           Currently the base class does nothing and returns an empty string.
88
89       normalise_items args, default_type, seen_types, seen_items, ITEM...
90           Convert the items to a normalised form. For 8 bit and Unicode
91           values converts the item to an array of 1 or 2 items, both 8 bit
92           and UTF-8 encoded.
93
94       C_constant arg_hashref, ITEM...
95           A function that returns a list of C subroutine definitions that
96           return the value and type of constants when passed the name by the
97           XS wrapper.  ITEM... gives a list of constant names. Each can
98           either be a string, which is taken as a C macro name, or a
99           reference to a hash with the following keys
100
101           name    The name of the constant, as seen by the perl code.
102
103           type    The type of the constant (IV, NV etc)
104
105           value   A C expression for the value of the constant, or a list of
106                   C expressions if the type is aggregate. This defaults to
107                   the name if not given.
108
109           macro   The C pre-processor macro to use in the "#ifdef". This
110                   defaults to the name, and is mainly used if value is an
111                   "enum". If a reference an array is passed then the first
112                   element is used in place of the "#ifdef" line, and the
113                   second element in place of the "#endif". This allows pre-
114                   processor constructions such as
115
116                       #if defined (foo)
117                       #if !defined (bar)
118                       ...
119                       #endif
120                       #endif
121
122                   to be used to determine if a constant is to be defined.
123
124                   A "macro" 1 signals that the constant is always defined, so
125                   the "#if"/"#endif" test is omitted.
126
127           default Default value to use (instead of "croak"ing with "your
128                   vendor has not defined...") to return if the macro isn't
129                   defined. Specify a reference to an array with type followed
130                   by value(s).
131
132           pre     C code to use before the assignment of the value of the
133                   constant. This allows you to use temporary variables to
134                   extract a value from part of a "struct" and return this as
135                   value. This C code is places at the start of a block, so
136                   you can declare variables in it.
137
138           post    C code to place between the assignment of value (to a
139                   temporary) and the return from the function. This allows
140                   you to clear up anything in pre.  Rarely needed.
141
142           def_pre
143           def_post
144                   Equivalents of pre and post for the default value.
145
146           utf8    Generated internally. Is zero or undefined if name is 7 bit
147                   ASCII, "no" if the name is 8 bit (and so should only match
148                   if SvUTF8() is false), "yes" if the name is utf8 encoded.
149
150                   The internals automatically clone any name with characters
151                   128-255 but none 256+ (ie one that could be either in bytes
152                   or utf8) into a second entry which is utf8 encoded.
153
154           weight  Optional sorting weight for names, to determine the order
155                   of linear testing when multiple names fall in the same case
156                   of a switch clause.  Higher comes earlier, undefined
157                   defaults to zero.
158
159           In the argument hashref, package is the name of the package, and is
160           only used in comments inside the generated C code. subname defaults
161           to "constant" if undefined.
162
163           default_type is the type returned by "ITEM"s that don't specify
164           their type. It defaults to the value of "default_type()". types
165           should be given either as a comma separated list of types that the
166           C subroutine subname will generate or as a reference to a hash.
167           default_type will be added to the list if not present, as will any
168           types given in the list of ITEMs. The resultant list should be the
169           same list of types that "XS_constant" is given. [Otherwise
170           "XS_constant" and "C_constant" may differ in the number of
171           parameters to the constant function. indent is currently unused and
172           ignored. In future it may be used to pass in information used to
173           change the C indentation style used.]  The best way to maintain
174           consistency is to pass in a hash reference and let this function
175           update it.
176
177           breakout governs when child functions of subname are generated.  If
178           there are breakout or more ITEMs with the same length of name, then
179           the code to switch between them is placed into a function named
180           subname_len, for example "constant_5" for names 5 characters long.
181           The default breakout is 3.  A single "ITEM" is always inlined.
182

BUGS

184       Not everything is documented yet.
185
186       Probably others.
187

AUTHOR

189       Nicholas Clark <nick@ccl4.org> based on the code in "h2xs" by Larry
190       Wall and others
191
192
193
194perl v5.26.3                      2018-03-01     ExtUtils::Constant::Base(3pm)
Impressum