Perl 5 version 16.1 documentation

ExtUtils::ParseXS::Utilities

NAME

ExtUtils::ParseXS::Utilities - Subroutines used with ExtUtils::ParseXS

SYNOPSIS

  1. use ExtUtils::ParseXS::Utilities qw(
  2. standard_typemap_locations
  3. trim_whitespace
  4. tidy_type
  5. C_string
  6. valid_proto_string
  7. process_typemaps
  8. make_targetable
  9. map_type
  10. standard_XS_defs
  11. assign_func_args
  12. analyze_preprocessor_statements
  13. set_cond
  14. Warn
  15. blurt
  16. death
  17. check_conditional_preprocessor_statements
  18. escape_file_for_line_directive
  19. report_typemap_failure
  20. );

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.

    1. '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.

    1. '../typemap',
    2. '../lib/ExtUtils/typemap',

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

    1. '../../typemap',
    2. '../../lib/ExtUtils/typemap',
    3. '../../../typemap',
    4. '../../../lib/ExtUtils/typemap',
    5. '../../../../typemap',
    6. '../../../../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:

    1. '/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.

    1. '/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',
    2. '../../../../lib/ExtUtils/typemap',
    3. '../../../../typemap',
    4. '../../../lib/ExtUtils/typemap',
    5. '../../../typemap',
    6. '../../lib/ExtUtils/typemap',
    7. '../../typemap',
    8. '../lib/ExtUtils/typemap',
    9. '../typemap',
    10. 'typemap'
  • Arguments
    1. 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
    1. trim_whitespace($arg);
  • Return Value

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

tidy_type()

  • Purpose

    Rationalize any asterisks (* ) by joining them into bunches, removing interior whitespace, then trimming leading and trailing whitespace.

  • Arguments
    1. ($ret_type) = tidy_type($_);

    String to be cleaned up.

  • Return Value

    String cleaned up.

C_string()

  • Purpose

    Escape backslashes (\ ) in prototype strings.

  • Arguments
    1. $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
    1. 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.

make_targetable()

  • Purpose

    Populate %targetable . This constitutes a refinement of the output of process_typemaps() with respect to its fourth output, $output_expr_ref .

  • Arguments
    1. %targetable = make_targetable($output_expr_ref);

    Single hash reference: the fourth such ref returned by process_typemaps() .

  • Return Value

    Hash.

map_type()

  • Purpose

    Performs a mapping at several places inside PARAGRAPH loop.

  • Arguments
    1. $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
    1. $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
    1. ( $self, $XSS_work_idx, $BootCode_ref ) =
    2. analyze_preprocessor_statements(
    3. $self, $statement, $XSS_work_idx, $BootCode_ref
    4. );

    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.