ExtUtils::Constant::Base(3p) Perl Programmers Reference Guide

ExtUtils::Constant::Base(3p) Perl Programmers Reference Guide #

ExtUtils::Constant::Base(3p) Perl Programmers Reference Guide

NNAAMMEE #

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

SSYYNNOOPPSSIISS #

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

DDEESSCCRRIIPPTTIIOONN #

 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 ccoonnssttaanntt(()) subroutine found in many XS modules.

UUSSAAGGEE #

 ExtUtils::Constant::Base exports no subroutines. The following methods
 are available

 header
     A method returning a scalar containing definitions needed, typically
     for a C header file.

 memEQ_clause args_hashref
     A method to return a suitable C "if" statement to check whether _n_a_m_e
     is equal to the C variable "name". If _c_h_e_c_k_e_d___a_t is defined, then it
     is used to avoid "memEQ" for short names, or to generate a comment to
     highlight the position of the character in the "switch" statement.

     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 _n_a_m_e).

 dump_names arg_hashref, ITEM...
     An internal function to generate the embedded perl code that will
     regenerate the constant subroutines.  _d_e_f_a_u_l_t___t_y_p_e, _t_y_p_e_s and _I_T_E_Ms
     are the same as for C_constant.  _i_n_d_e_n_t is treated as number of
     spaces to indent by.  If "declare_types" is true a $types is always
     declared in the perl code generated, if defined and false never
     declared, and if undefined $types is only declared if the values in
     _t_y_p_e_s as passed in cannot be inferred from _d_e_f_a_u_l_t___t_y_p_e_s and the
     _I_T_E_Ms.

 assign arg_hashref, VALUE...
     A method to return a suitable assignment clause. If _t_y_p_e is aggregate
     (eg _P_V_N expects both pointer and length) then there should be
     multiple _V_A_L_U_Es for the components. _p_r_e and _p_o_s_t if defined give
     snippets of C code to proceed and follow the assignment. _p_r_e will be
     at the start of a block, so variables may be defined in it.

 return_clause arg_hashref, ITEM
     A method to return a suitable "#ifdef" clause. _I_T_E_M is a hashref (as
     passed to "C_constant" and "match_clause". _i_n_d_e_n_t is the number of
     spaces to indent, defaulting to 6.

 switch_clause arg_hashref, NAMELEN, ITEMHASH, ITEM...
     An internal method to generate a suitable "switch" clause, called by
     "C_constant" _I_T_E_Ms are in the hash ref format as given in the
     description of "C_constant", and must all have the names of the same
     length, given by _N_A_M_E_L_E_N.  _I_T_E_M_H_A_S_H is a reference to a hash, keyed
     by name, values being the hashrefs in the _I_T_E_M list.  (No parameters
     are modified, and there can be keys in the _I_T_E_M_H_A_S_H that are not in
     the list of _I_T_E_Ms without causing problems - the hash is passed in to
     save generating it afresh for each call).

 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 "*param*" calls. (Yes, having to read the source to make
     sense of this is considered a known bug). _W_H_A_T 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

 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.

     Currently the base class does nothing and returns an empty string.

 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.

 C_constant arg_hashref, ITEM...
     A function that returns a lliisstt of C subroutine definitions that
     return the value and type of constants when passed the name by the XS
     wrapper.  _I_T_E_M_._._. 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

     name    The name of the constant, as seen by the perl code.

     type    The type of the constant (_I_V, _N_V etc)

     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
             _n_a_m_e if not given.

     macro   The C pre-processor macro to use in the "#ifdef". This
             defaults to the _n_a_m_e, and is mainly used if _v_a_l_u_e is an
             "enum". If a reference an array is passed then the first
             element is used in place of the "#ifdef" line, and the second
             element in place of the "#endif". This allows pre-processor
             constructions such as

                 #if defined (foo)
                 #if !defined (bar)
                 ...
                 #endif
                 #endif

             to be used to determine if a constant is to be defined.

             A "macro" 1 signals that the constant is always defined, so
             the "#if"/"#endif" test is omitted.

     default Default value to use (instead of "croak"ing 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).

     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 "struct" and return this as
             _v_a_l_u_e. This C code is places 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 allows you
             to clear up anything in _p_r_e.  Rarely needed.

     def_pre
     def_post
             Equivalents of _p_r_e and _p_o_s_t for the default value.

     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
             SSvvUUTTFF88(()) is false), "yes" if the name is utf8 encoded.

             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.

     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.

     In the argument hashref, _p_a_c_k_a_g_e is the name of the package, and is
     only used in comments inside the generated C code. _s_u_b_n_a_m_e defaults
     to "constant" if undefined.

     _d_e_f_a_u_l_t___t_y_p_e is the type returned by "ITEM"s that don't specify their
     type. It defaults to the value of "default_type()". _t_y_p_e_s should be
     given either as a comma separated list of types that the C subroutine
     _s_u_b_n_a_m_e will generate or as a reference to a hash. _d_e_f_a_u_l_t___t_y_p_e will
     be added to the list if not present, as will any types given in the
     list of _I_T_E_Ms. 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. _i_n_d_e_n_t 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.

     _b_r_e_a_k_o_u_t governs when child functions of _s_u_b_n_a_m_e are generated.  If
     there are _b_r_e_a_k_o_u_t or more _I_T_E_Ms with the same length of name, then
     the code to switch between them is placed into a function named
     _s_u_b_n_a_m_e__l_e_n, for example "constant_5" for names 5 characters long.
     The default _b_r_e_a_k_o_u_t is 3.  A single "ITEM" is always inlined.

BBUUGGSS #

 Not everything is documented yet.

 Probably others.

AAUUTTHHOORR #

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

perl v5.36.3 2023-02-15 ExtUtils::Constant::Base(3p)