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.

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.