ExtUtils::ParseXS::Utilities(3pm)

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

    Returns a standard list of filepaths where typemap files may be found. This will typically be something like:

            map("$_/ExtUtils/typemap", reverse @INC),
            qw(
                ../../../../lib/ExtUtils/typemap
                ../../../../typemap
                ../../../lib/ExtUtils/typemap
                ../../../typemap
                ../../lib/ExtUtils/typemap
                ../../typemap
                ../lib/ExtUtils/typemap
                ../typemap
                typemap
            )

    but the style of the pathnames may vary with OS. Note that the value to use for @INC is passed as an array reference, and can be something other than @INC itself.

    Pathnames are returned in the order they are expected to be processed; this means that later files will update or override entries found in earlier files. So in particular, typemap in the current directory has highest priority. @INC is searched in reverse order so that earlier entries in @INC are processed later and so have higher priority.

    The values of "-typemap" switches are not used here; they should be added by the caller to the list of pathnames returned by this function.

•   Arguments

      my @stl = standard_typemap_locations(\@INC);

    A single argument: a reference to an array to use as if it were @INC.

•   Return Value

    A list of typemap pathnames.

  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. Reads in any typemap files specified explicitly with "-typemap" switches or similar, plus any typemap files found in standard locations relative to @INC and the current directory.

•   Arguments

      my $typemaps_object = process_typemaps( $args{typemap}, $pwd );

    The first argument is the "typemap" element from %args; the second is the current working directory (which is only needed for error messages).

•   Return Value

    Upon success, returns an ExtUtils::Typemaps object which contains the accumulated results of all processed typemap files.

  "map_type($self, $type, $varname)"
Returns a mapped version of the C type $type. In particular, it converts "Foo::bar" to "Foo__bar", converts the special "array(type,n)" into "type *", and inserts $varname (if present) into any function pointer type. So "...(*)..." becomes "...(* foo)...".

  set_cond()

•   Purpose

    Return a string containing a snippet of C code which tests for the 'wrong number of arguments passed' condition, depending on whether there are default arguments or ellipsis.

•   Arguments

    "ellipsis" true if the xsub's signature has a trailing ", ...".

    $min_args the smallest number of args which may be passed.

    $num_args the number of parameters in the signature.

•   Return Value

    The text of a short C code snippet.

  current_line_number()

•   Purpose

    Figures out the current line number in the XS file.

•   Arguments

    $self

•   Return Value

    The current line number.

  Error handling methods
There are four main methods for reporting warnings and errors.

"$self->Warn(@messages)"
    This is equivalent to:

      warn "@messages in foo.xs, line 123\n";

    The file and line number are based on the file currently being parsed. It is intended for use where you wish to warn, but can continue parsing and still generate a correct C output file.

"$self->blurt(@messages)"
    This is equivalent to "Warn", except that it also increments the internal error count (which can be retrieved with report_error_count()). It is used to report an error, but where parsing can continue (so typically for a semantic error rather than a syntax error). It is expected that the caller will eventually signal failure in some fashion. For example, "xsubpp" has this as its last line:

      exit($self->report_error_count() ? 1 : 0);

"$self->death(@messages)"
    This normally equivalent to:

      $self->Warn(@messages);
      exit(1);

    It is used for something like a syntax error, where parsing can't continue. However, this is inconvenient for testing purposes, as the error can't be trapped. So if $self is created with the "die_on_error" flag, or if $ExtUtils::ParseXS::DIE_ON_ERROR is true when process_file() is called, then instead it will die() with that message.

"$self->WarnHint(@messages, $hints)"
    This is a more obscure twin to "Warn", which does the same as "Warn", but afterwards, outputs any lines contained in the $hints string, with the paragraph wrapped in parentheses. For example:

      $self->WarnHint(@messages,
        "Have you set the foo switch?\nSee the manual for further info");

"$self->deathHint(@messages, $hints)"
    This is a more obscure twin to "death", which does the same as "death", but afterwards, outputs any lines contained in the $hints string, with the paragraph wrapped in parentheses. For example:

      $self->deathHint(@messages,
        "Have you set the foo switch?\nSee the manual for further info");

  check_conditional_preprocessor_statements()

•   Purpose

    Warn if the lines in "@{ $self->{line} }" don't have balanced "#if", "endif" etc.

•   Arguments

    None

•   Return Value

    None

  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.

  "looks like_MODULE_line($line)"
Returns true if the passed line looks like an attempt to be a MODULE line. Note that it doesn't check for valid syntax. This allows the caller to do its own parsing of the line, providing some sort of 'invalid MODULE line' check. As compared with thinking that its not a MODULE line if its syntax is slightly off, leading instead to some weird error about a bad start to an XSUB or something.

In particular, a line starting "MODULE:" returns true, because it's likely to be an attempt by the programmer to write a MODULE line, even though it's invalid syntax.