Scroll to navigation

ExtUtils::ParseXS::Utilities(3pm) User Contributed Perl Documentation ExtUtils::ParseXS::Utilities(3pm)

NAME

ExtUtils::ParseXS::Utilities - Subroutines used with ExtUtils::ParseXS

SYNOPSIS

  use ExtUtils::ParseXS::Utilities qw(
    standard_typemap_locations
    trim_whitespace
    tidy_type
    C_string
    valid_proto_string
    process_typemaps
    make_targetable
    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.

"tidy_type()"

•
Purpose
 
Rationalize any asterisks ("*") by joining them into bunches, removing interior whitespace, then trimming leading and trailing whitespace.
•
Arguments
 
    ($ret_type) = tidy_type($_);
 
String to be cleaned up.
•
Return Value
 
String cleaned up.

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

"make_targetable()"

•
Purpose
 
Populate %targetable. This constitutes a refinement of the output of "process_typemaps()" with respect to its fourth output, $output_expr_ref.
•
Arguments
 
  %targetable = make_targetable($output_expr_ref);
 
Single hash reference: the fourth such ref returned by "process_typemaps()".
•
Return Value
 
Hash.

"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.
2012-02-02 perl v5.14.2