ExtUtils::ParseXS::Utilities(3)

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

    Print warnings with line number details at the end.

•   Arguments

    List of text to output.

•   Return Value

    None.

  WarnHint()

•   Purpose

    Prints warning with line number details. The last argument is assumed to be a hint string.

•   Arguments

    List of strings to warn, followed by one argument representing a hint. If that argument is defined then it will be split on newlines and output line by line after the main warning.

•   Return Value

    None.

  _MsgHint()

•   Purpose

    Constructs an exception message with line number details. The last argument is assumed to be a hint string.

•   Arguments

    List of strings to warn, followed by one argument representing a hint. If that argument is defined then it will be split on newlines and concatenated line by line (parenthesized) after the main message.

•   Return Value

    The constructed string.

  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.