名前¶

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

概要¶

  use ExtUtils::ParseXS::Utilities qw(
    standard_typemap_locations
    trim_whitespace
    tidy_type
    C_string
    valid_proto_string
    process_typemaps
    make_targetable
    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.

tidy_type()¶

• Purpose

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

• Arguments

      ($ret_type) = tidy_type($_);

  String to be cleaned up.

• Return Value

  String cleaned up.

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.

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

    %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

    $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.