--- name: "ExtUtils::ParseXS::Utilities" section: "3p" platform: "openbsd" package: "man" version: "8.0-current-20261101" release: "OpenBSD 8.0-current (2026-11-01)" platforms: ["openbsd"] url: "https://new.carta.tech/ExtUtils::ParseXS::Utilities" --- # ExtUtils::ParseXS::Utilities(3p) Subroutines used with ExtUtils::ParseXS ## NAME ExtUtils::ParseXS::Utilities - 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 The following functions are not considered to be 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.