ExtUtils::ParseXS::Utilities

(source, CPAN)

version 3.51

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

NAME
SYNOPSIS
SUBROUTINES

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

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

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

Print warnings with line number details at the end.
Arguments

List of text to output.
Return Value

None.

#`WarnHint()`

Purpose

Prints warning with line number details. The last argument is assumed to be a hint string.
Arguments

List of strings to warn, followed by one argument representing a hint. If that argument is defined then it will be split on newlines and output line by line after the main warning.
Return Value

None.

#`_MsgHint()`

Purpose

Constructs an exception message with line number details. The last argument is assumed to be a hint string.
Arguments

List of strings to warn, followed by one argument representing a hint. If that argument is defined then it will be split on newlines and concatenated line by line (parenthesized) after the main message.
Return Value

The constructed string.

#`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.

CONTENTS

#NAME

#SYNOPSIS

#SUBROUTINES

#standard_typemap_locations()

#trim_whitespace()

#C_string()

#valid_proto_string()

#process_typemaps()

#map_type()

#standard_XS_defs()

#assign_func_args()

#analyze_preprocessor_statements()

#set_cond()

#current_line_number()

#Warn()

#WarnHint()

#_MsgHint()

#blurt()

#death()

#check_conditional_preprocessor_statements()

#escape_file_for_line_directive()

#report_typemap_failure

#`standard_typemap_locations()`

#`trim_whitespace()`

#`C_string()`

#`valid_proto_string()`

#`process_typemaps()`

#`map_type()`

#`standard_XS_defs()`

#`assign_func_args()`

#`analyze_preprocessor_statements()`

#`set_cond()`

#`current_line_number()`

#`Warn()`

#`WarnHint()`

#`_MsgHint()`

#`blurt()`

#`death()`

#`check_conditional_preprocessor_statements()`

#`escape_file_for_line_directive()`

#`report_typemap_failure`