You are viewing the version of this documentation from Perl 5.41.5. This is a development version of Perl.

CONTENTS

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
  analyze_preprocessor_statement
  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()

trim_whitespace()

C_string()

valid_proto_string()

process_typemaps()

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

standard_XS_defs()

analyze_preprocessor_statement()

set_cond()

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 each line wrapped in parentheses. For example:

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

check_conditional_preprocessor_statements()

escape_file_for_line_directive()

report_typemap_failure