perldoc > ExtUtils::ParseXS::Utilities(3perl)

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.