ExtUtil...ilities(3pm)

📦
version 5.42.3 · 8 versions
, in alpine 3.24

🌸 NAME 🌸

This is the ExtUtil...ilities(3pm) page from the Perl Programmers Reference Guide for ExtUtils::ParseXS::Utilities — the subroutines used with ExtUtils::ParseXS. 💖

✨ SYNOPSIS ✨

use ExtUtils::ParseXS::Utilities qw(
  standard_typemap_locations
  trim_whitespace
  C_string
  valid_proto_string
  process_typemaps
  map_type
  standard_XS_defs
  analyze_preprocessor_statement
  set_cond
  Warn
  blurt
  death
  check_conditional_preprocessor_statements
  escape_file_for_line_directive
  report_typemap_failure
);

🎀 SUBROUTINES 🎀

🚨 Bestie, real talk: these functions are not considered part of the public interface. They are documented here for the benefit of future maintainers of this module. 💅

🧚 standard_typemap_locations()

💖 Purpose

Provide a list of filepaths where typemap files may be found. The filepaths — relative paths to files (not just directory paths) — appear in this list in lowest-to-highest priority. 🌈

The highest priority is to look in the current directory.

'typemap'

The second and third highest priorities are to look in the parent of the current directory and a directory called lib/ExtUtils underneath the parent directory.

'../typemap',
'../lib/ExtUtils/typemap',

The fourth through ninth highest priorities are to look in the corresponding grandparent, great-grandparent and great-great-grandparent directories.

'../../typemap',
'../../lib/ExtUtils/typemap',
'../../../typemap',
'../../../lib/ExtUtils/typemap',
'../../../../typemap',
'../../../../lib/ExtUtils/typemap',

The tenth and subsequent priorities are to look in directories named ExtUtils which are subdirectories of directories found in @INC — provided a file named typemap actually exists in such a directory. Example:

'/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',

However, these filepaths appear in the list returned by standard_typemap_locations() in reverse order, i.e., lowest-to-highest.

'/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',
'../../../../lib/ExtUtils/typemap',
'../../../../typemap',
'../../../lib/ExtUtils/typemap',
'../../../typemap',
'../../lib/ExtUtils/typemap',
'../../typemap',
'../lib/ExtUtils/typemap',
'../typemap',
'typemap'

🐚 Arguments

my @stl = standard_typemap_locations( \@INC );

Reference to @INC.

🌟 Return Value

Array holding list of directories to be searched for typemap files.

🧼 trim_whitespace()

💖 Purpose

Perform an in-place trimming of leading and trailing whitespace from the first argument provided to the function. ✂️

🐚 Argument

trim_whitespace($arg);

🌟 Return Value

None. Remember: this is an in-place modification of the argument. 👑

🪄 C_string()

💖 Purpose

Escape backslashes (\) in prototype strings.

🐚 Arguments

$ProtoThisXSUB = C_string($_);

String needing escaping.

🌟 Return Value

Properly escaped string. ✨

🦋 valid_proto_string()

💖 Purpose

Validate prototype string.

🐚 Arguments

String needing checking.

🌟 Return Value

Upon success, returns the same string passed as argument.

Upon failure, returns 0.

🍓 process_typemaps()

💖 Purpose

Process all typemap files.

🐚 Arguments

my $typemaps_object = process_typemaps( $args{typemap}, $pwd );

List of two elements: "typemap" element from %args; current working directory.

🌟 Return Value

Upon success, returns an ExtUtils::Typemaps object. 🫶

🦋 map_type($self, $type, $varname)

Returns a mapped version of the C type $type. In particular, it converts Foo::bar to Foo__bar, converts the special array(type,n) into type *, and inserts $varname (if present) into any function pointer type. So ...(*)... becomes ...(* foo).... 🔥

👑 standard_XS_defs()

💖 Purpose

Writes to the .c output file certain preprocessor directives and function headers needed in all such files.

🐚 Arguments

None.

🌟 Return Value

Returns true. ✅

🪄 analyze_preprocessor_statement()

💖 Purpose

Process a CPP conditional line (#if etc), to keep track of conditional nesting. In particular, it updates @{$self->{XS_parse_stack}} which contains the current list of nested conditions, and $self->{XS_parse_stack_top_if_idx} which indicates the most recent if in that stack. So an #if pushes, an #endif pops, an #else modifies etc. Each element is a hash of the form:

{
  type      => 'if',
  varname   => 'XSubPPtmpAAAA', # maintained by caller

                # XS functions defined within this branch of the
                # conditional (maintained by caller)
  functions =>  {
                  'Foo::Bar::baz' => 1,
                  ...
                }
                # XS functions seen within any previous branch
  other_functions => {... }

}

It also updates $self->{bootcode_early} and $self->{bootcode_late} with extra CPP directives.

🐚 Arguments

$self->analyze_preprocessor_statement($statement);

🎯 set_cond()

💖 Purpose

Return a string containing a snippet of C code which tests for the 'wrong number of arguments passed' condition, depending on whether there are default arguments or ellipsis.

🐚 Arguments

ellipsis true if the xsub's signature has a trailing , ....

$min_args the smallest number of args which may be passed.

$num_args the number of parameters in the signature.

🌟 Return Value

The text of a short C code snippet. 💻

📏 current_line_number()

💖 Purpose

Figures out the current line number in the XS file.

🐚 Arguments

$self

🌟 Return Value

The current line number.

💅 Error handling methods

There are four main methods for reporting warnings and errors.

😭 $self->Warn(@messages)

This is equivalent to:

warn "@messages in foo.xs, line 123\n";

The file and line number are based on the file currently being parsed. It is intended for use where you wish to warn, but can continue parsing and still generate a correct C output file.

💀 $self->blurt(@messages)

This is equivalent to Warn, except that it also increments the internal error count (which can be retrieved with report_error_count()). It is used to report an error, but where parsing can continue (so typically for a semantic error rather than a syntax error). It is expected that the caller will eventually signal failure in some fashion. For example, xsubpp has this as its last line:

exit($self->report_error_count() ? 1 : 0);

🙈 $self->death(@messages)

This normally equivalent to:

$self->Warn(@messages);
exit(1);

It is used for something like a syntax error, where parsing can't continue. However, this is inconvenient for testing purposes, as the error can't be trapped. So if $self is created with the die_on_error flag, or if $ExtUtils::ParseXS::DIE_ON_ERROR is true when process_file() is called, then instead it will die() with that message.

🫶 $self->WarnHint(@messages, $hints)

This is a more obscure twin to Warn, which does the same as Warn, but afterwards, outputs any lines contained in the $hints string, with each line wrapped in parentheses. For example:

$self->WarnHint(@messages,
  "Have you set the foo switch?\nSee the manual for further info");

🧚 check_conditional_preprocessor_statements()

💖 Purpose

Warn if the lines in "@{ $self->{line} }" don't have balanced "#if", "endif" etc.

🐚 Arguments

None

🌟 Return Value

None

🌈 escape_file_for_line_directive()

💖 Purpose

Escapes a given code source name (typically a file name but can also be a command that was read from) so that double-quotes and backslashes are escaped.

🐚 Arguments

A string.

🌟 Return Value

A string with escapes for double-quotes and backslashes.

🎀 report_typemap_failure

💖 Purpose

Do error reporting for missing typemaps.

🐚 Arguments

  • The ExtUtils::ParseXS object.
  • An ExtUtils::Typemaps object.
  • The string that represents the C type that was not found in the typemap.
  • Optionally, the string "death" or "blurt" to choose whether the error is immediately fatal or not. Default: "blurt".

🌟 Return Value

Returns nothing. Depending on the arguments, this may call "death" or "blurt", the former of which is fatal. 💀

okay bye bestie 🫶💖 this page is from perl v5.42.3, dated 2026-11-03 — mwah 💋

📦 where this page comes from