CONTENTS

• NAME
• SYNOPSIS
• SUBROUTINES
  • standard_typemap_locations()
  • trim_whitespace()
  • C_string()
  • valid_proto_string()
  • process_typemaps()
  • map_type($self, $type, $varname)
  • standard_XS_defs()
  • C_func_signature()
  • analyze_preprocessor_statement()
  • set_cond()
  • current_line_number()
  • Error handling methods
  • 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
  C_func_signature
  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()

• 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($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()

• Purpose

  Writes to the .c output file certain preprocessor directives and function headers needed in all such files.

• Arguments

  None.

• Return Value

  Returns true.

#C_func_signature()

• Purpose

  Generate the argument list to be applied to the call to the "real" C library function which is wrapped by the xsub. It is is the same as the xsub's arguments, except that any initial method pointer is deleted, and args marked as *OUT* are prefixed with '&'.

• Arguments

  $sig_string = $self->C_func_signature($argsref, $class);

  $argref is an array reference containing the xsub's parameters.

  $class if defined, indicates that this is a method.

• Return Value

  A string such as 'foo, &bar, baz'

#analyze_preprocessor_statement()

• Purpose

  Process a CPP conditional line (#if etc), to keep track of conditional nesting. In particular, it updates @{$self->{XS_parse_stack}} which contains the current list of nested conditions, and $self->{XS_parse_stack_top_if_idx} which indicates the most recent if in that stack. So an #if pushes, an #endif pops, an #else modifies etc. Each element is a hash of the form:

  {
    type      => 'if',
    varname   => 'XSubPPtmpAAAA', # maintained by caller
  
                  # XS functions defined within this branch of the
                  # conditional (maintained by caller)
    functions =>  {
                    'Foo::Bar::baz' => 1,
                    ...
                  }
                  # XS functions seen within any previous branch
    other_functions => {... }

  It also updates $self->{bootcode_early} and $self->{bootcode_late} with extra CPP directives.

• Arguments

  $self->analyze_preprocessor_statement($statement);

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

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

Perldoc Browser is maintained by Dan Book (DBOOK). Please contact him via the GitHub issue tracker or email regarding any issues with the site itself, search, or rendering of documentation.

The Perl documentation is maintained by the Perl 5 Porters in the development of Perl. Please contact them via the Perl issue tracker, the mailing list, or IRC to report any issues with the contents or format of the documentation.