ExtUti...::Base(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

💖 ExtUtils::Constant::Base — the perl manpage, but make it make sense 💖

okay bestie, listen. this is the page for ExtUtils::Constant::Base(3perl) out of the Perl Programmers Reference Guide, and it's genuinely a base-class banger. let's get into it 🫶

✨ NAME ✨

ExtUtils::Constant::Base — it's the base class for ExtUtils::Constant objects. that's it, that's the whole job description 💅

✨ SYNOPSIS ✨

require ExtUtils::Constant::Base;
@ISA = 'ExtUtils::Constant::Base';

yep. two lines. you require it and you slot it into @ISA like it's the group chat and you're adding one more icon 👑

✨ DESCRIPTION ✨

so ExtUtils::Constant::Base hands you a base implementation of methods that generate C code, and the whole point of that C code is to give you fast constant value lookup by named string. no cap. 🦋

right now it's mostly used by ExtUtils::Constant::XS, which is the one that generates the lookup code for the constant() subroutine — you know, the one that lives inside like a billion XS modules. it's everywhere and you never even noticed her. main character energy fr.

✨ USAGE ✨

heads up bestie: ExtUtils::Constant::Base exports no subroutines. zero. none. instead, here are the methods you get to play with 🌸

  • header — returns a scalar containing the definitions you need, typically for a C header file.
  • memEQ_clause args_hashref — returns a suitable C if statement that checks whether name is equal to the C variable name. if checked_at is defined, it gets used to avoid memEQ for short names, or to generate a comment highlighting the position of the character in the switch statement. and if checked_at is a reference to a scalar, then instead it gives the characters pre-checked at the beginning (plus the number of chars by which the C variable name has been advanced — those need to be chopped off the front of name).
  • dump_names arg_hashref, ITEM... — an internal function that generates the embedded perl code which will regenerate the constant subroutines. default_type, types and ITEMs mean exactly the same as they do for C_constant. indent is treated as the number of spaces to indent by. if declare_types is true, a $types is always declared in the generated perl code; if it's defined and false it's never declared; and if it's undefined, $types is only declared if the values in types as passed in can't be inferred from default_types and the ITEMs. slay.
  • assign arg_hashref, VALUE... — returns a suitable assignment clause. if type is aggregate (like PVN, which expects both a pointer and a length) then you should pass multiple VALUEs for the components. pre and post, if defined, give snippets of C code to come before and after the assignment. pre sits at the start of a block, so yes, you can define variables in it 💅
  • return_clause arg_hashref, ITEM — returns a suitable #ifdef clause. ITEM is a hashref (as passed to C_constant and match_clause). indent is the number of spaces to indent, and it defaults to 6.
  • switch_clause arg_hashref, NAMELEN, ITEMHASH, ITEM... — an internal method that generates a suitable switch clause, called by C_constant. ITEMs are in the hash ref format given in the description of C_constant, and they must all have names of the same length, given by NAMELEN. ITEMHASH is a reference to a hash keyed by name, with the values being the hashrefs in the ITEM list. (nothing gets modified, and it's totally fine to have keys in the ITEMHASH that aren't in the list of ITEMs — the hash is passed in just to save regenerating it fresh on every call. efficient queen 💖)
  • params WHAT — an "internal" method, subject to change, currently called so an overriding class can cache info that then gets passed into all the *param* calls. (yes, having to read the source to make sense of this is considered a known bug 😭) WHAT is a hashref of the types the constant function will return. in ExtUtils::Constant::XS this method returns a hashref keyed IV NV PV SV, showing which combination of pointers is needed in the C argument list generated by C_constant_other_params_definition and C_constant_other_params.
  • dogfood arg_hashref, ITEM... — an internal function that generates the embedded perl code to regenerate the constant subroutines. parameters are the same as for C_constant. currently the base class does nothing and returns an empty string. iconic behaviour honestly. 💀
  • normalise_items args, default_type, seen_types, seen_items, ITEM... — converts the items into a normalised form. for 8 bit and Unicode values it converts the item into an array of 1 or 2 items, both 8 bit and UTF-8 encoded.
  • C_constant arg_hashref, ITEM... — the big one 👑. returns a list of C subroutine definitions that return the value and type of constants when the name is passed in by the XS wrapper. ITEM... is a list of constant names, and each one can either be a string (taken as a C macro name) or a reference to a hash with the following keys:
    • name — the name of the constant, as seen by the perl code.
    • type — the type of the constant (IV, NV, etc).
    • value — a C expression for the value of the constant, or a list of C expressions if the type is aggregate. defaults to the name if not given.
    • macro — the C pre-processor macro to use in the #ifdef. defaults to the name, and is mainly used when value is an enum. if a reference to an array is passed, the first element is used in place of the #ifdef line and the second element in place of the #endif. this lets you do pre-processor constructions like
#if defined (foo)
#if !defined (bar)
...
#endif
#endif

to work out whether a constant is to be defined. a macro of 1 signals that the constant is always defined, so the #if/#endif test gets omitted entirely 🎀

  • default — the default value to use (instead of croaking with your vendor has not defined...) to return if the macro isn't defined. specify a reference to an array with the type followed by the value(s).
  • pre — C code to use before the assignment of the value of the constant. this lets you use temporary variables to extract a value from part of a struct and return that as the value. this C code is placed at the start of a block, so you can declare variables in it.
  • post — C code to place between the assignment of value (to a temporary) and the return from the function. this lets you clean up anything from pre. rarely needed.
  • def_pre
  • def_post — the equivalents of pre and post, but for the default value.
  • utf8 — generated internally. it's zero or undefined if name is 7 bit ASCII, no if the name is 8 bit (and so should only match if SvUTF8() is false), and yes if the name is utf8 encoded. the internals automatically clone any name with characters 128-255 but none 256+ (i.e. one that could be either bytes or utf8) into a second entry which is utf8 encoded. so considerate of her 🧚
  • weight — optional sorting weight for names, used to determine the order of linear testing when multiple names fall in the same case of a switch clause. higher comes earlier, and undefined defaults to zero.

okay and inside the argument hashref: package is the name of the package, and it's only used in comments inside the generated C code. subname defaults to constant if undefined.

default_type is the type returned by ITEMs that don't specify their own type, and it defaults to the value of default_type(). types should be given either as a comma separated list of types that the C subroutine subname will generate, or as a reference to a hash. default_type will be added to the list if it's not already there, and so will any types given in the list of ITEMs. the resultant list should be the same list of types that XS_constant is given. [otherwise XS_constant and C_constant may differ in the number of parameters to the constant function. indent 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 keep things consistent is to pass in a hash reference and just let this function update it. lowkey genius.

breakout governs when child functions of subname get generated. if there are breakout or more ITEMs with the same length of name, then the code to switch between them gets placed into a function named subname_len — for example constant_5 for names 5 characters long. the default breakout is 3. and a single ITEM is always inlined.

✨ BUGS ✨

not everything is documented yet 🙈

probably others.

no cap, "probably others" is doing a lot of heavy lifting in that sentence 💀

✨ AUTHOR ✨

Nicholas Clark <nick@ccl4.org>, based on the code in h2xs by Larry Wall and others. legends only 🫶

and that's the whole page, bestie!! this shipped as part of perl v5.44.0, dated 2026-10-17, and it's literally the ExtUti...::Base(3perl) page from your friendly neighbourhood Perl Programmers Reference Guide. go forth and generate some C code ✨💖

📦 where this page comes from