- NAME
- SYNOPSIS
- SUBROUTINES
  - 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()
  - current_line_number()
  - Warn()
  - blurt()
  - death()
  - check_conditional_preprocessor_statements()
  - escape_file_for_line_directive()
  - report_typemap_failure

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