ExtUtils::ParseXS::Utilities(3perl) Perl Programmers Reference Guide 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() o 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' o Arguments my @stl = standard_typemap_locations( \@INC ); Reference to @INC. o Return Value Array holding list of directories to be searched for typemap files. trim_whitespace() o Purpose Perform an in-place trimming of leading and trailing whitespace from the first argument provided to the function. o Argument trim_whitespace($arg); o Return Value None. Remember: this is an in-place modification of the argument. C_string() o Purpose Escape backslashes ("\") in prototype strings. o Arguments $ProtoThisXSUB = C_string($_); String needing escaping. o Return Value Properly escaped string. valid_proto_string() o Purpose Validate prototype string. o Arguments String needing checking. o Return Value Upon success, returns the same string passed as argument. Upon failure, returns 0. process_typemaps() o Purpose Process all typemap files. o Arguments my $typemaps_object = process_typemaps( $args{typemap}, $pwd ); List of two elements: "typemap" element from %args; current working directory. o 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() o Purpose Writes to the ".c" output file certain preprocessor directives and function headers needed in all such files. o Arguments None. o Return Value Returns true. analyze_preprocessor_statement() o 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. o Arguments $self->analyze_preprocessor_statement($statement); set_cond() o 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. o 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. o Return Value The text of a short C code snippet. current_line_number() o Purpose Figures out the current line number in the XS file. o Arguments $self o 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() o Purpose Warn if the lines in "@{ $self->{line} }" don't have balanced "#if", "endif" etc. o Arguments None o Return Value None escape_file_for_line_directive() o 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. o Arguments A string. o Return Value A string with escapes for double-quotes and backslashes. "report_typemap_failure" o Purpose Do error reporting for missing typemaps. o 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" o Return Value Returns nothing. Depending on the arguments, this may call "death" or "blurt", the former of which is fatal. perl v5.42.2 2026-08-11 ExtUtils::ParseXS::Utilities(3perl)