--- name: "ExtUtils::ParseXS::Utilities" section: "3pm" platform: "linux" package: "libextutils-parsexs-perl" version: "3.240000-1" release: "Debian 8 (Jessie)" platforms: ["linux"] url: "https://new.carta.tech/ExtUtils::ParseXS::Utilities/3pm" --- # ExtUtils::ParseXS::Utilities(3pm) 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 assign_func_args analyze_preprocessor_statements 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()" - • Purpose Performs a mapping at several places inside `"PARAGRAPH"` loop. - • Arguments ``` $type = map_type($self, $type, $varname); ``` List of three arguments. - • Return Value String holding augmented version of second argument. ### "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. ### "assign\_func\_args()" - • Purpose Perform assignment to the `"func_args"` attribute. - • Arguments ``` $string = assign_func_args($self, $argsref, $class); ``` List of three elements. Second is an array reference; third is a string. - • Return Value String. ### "analyze\_preprocessor\_statements()" - • Purpose Within each function inside each Xsub, print to the *.c* output file certain preprocessor statements. - • Arguments ``` ( $self, $XSS_work_idx, $BootCode_ref ) = analyze_preprocessor_statements( $self, $statement, $XSS_work_idx, $BootCode_ref ); ``` List of four elements. - • Return Value Modifed values of three of the arguments passed to the function. In particular, the `"XSStack"` and `"InitFileCode"` attributes are modified. ### "set\_cond()" - • Purpose - • Arguments - • Return Value ### "current\_line\_number()" - • Purpose Figures out the current line number in the XS file. - • Arguments `$self` - • Return Value The current line number. ### "Warn()" - • Purpose - • Arguments - • Return Value ### "blurt()" - • Purpose - • Arguments - • Return Value ### "death()" - • Purpose - • Arguments - • Return Value ### "check\_conditional\_preprocessor\_statements()" - • Purpose - • Arguments - • Return Value ### "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.