ExtUtils::ParseXS::Utilities - Subroutines used with ExtUtils::ParseXS
NAME SYNOPSIS SUBROUTINES standard_typemap_locations() trim_whitespace() C_string() valid_proto_string() process_typemaps() "map_type($self, $type, $varname)" standard_XS_defs() 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
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.
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.