.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ExtUtils::ParseXS::Utilities 3perl"
.TH ExtUtils::ParseXS::Utilities 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
ExtUtils::ParseXS::Utilities \- Subroutines used with ExtUtils::ParseXS
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 10
\&  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
\&  );
.Ve
.SH SUBROUTINES
.IX Header "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.
.ie n .SS standard_typemap_locations()
.el .SS \f(CWstandard_typemap_locations()\fP
.IX Subsection "standard_typemap_locations()"
.IP \(bu 4
Purpose
.Sp
Provide a list of filepaths where \fItypemap\fR files may be found.  The
filepaths \-\- relative paths to files (not just directory paths) \-\- appear in this list in lowest-to-highest priority.
.Sp
The highest priority is to look in the current directory.
.Sp
.Vb 1
\&  \*(Aqtypemap\*(Aq
.Ve
.Sp
The second and third highest priorities are to look in the parent of the
current directory and a directory called \fIlib/ExtUtils\fR underneath the parent
directory.
.Sp
.Vb 2
\&  \*(Aq../typemap\*(Aq,
\&  \*(Aq../lib/ExtUtils/typemap\*(Aq,
.Ve
.Sp
The fourth through ninth highest priorities are to look in the corresponding
grandparent, great-grandparent and great-great-grandparent directories.
.Sp
.Vb 6
\&  \*(Aq../../typemap\*(Aq,
\&  \*(Aq../../lib/ExtUtils/typemap\*(Aq,
\&  \*(Aq../../../typemap\*(Aq,
\&  \*(Aq../../../lib/ExtUtils/typemap\*(Aq,
\&  \*(Aq../../../../typemap\*(Aq,
\&  \*(Aq../../../../lib/ExtUtils/typemap\*(Aq,
.Ve
.Sp
The tenth and subsequent priorities are to look in directories named
\&\fIExtUtils\fR which are subdirectories of directories found in \f(CW@INC\fR \-\-
\&\fIprovided\fR a file named \fItypemap\fR actually exists in such a directory.
Example:
.Sp
.Vb 1
\&  \*(Aq/usr/local/lib/perl5/5.10.1/ExtUtils/typemap\*(Aq,
.Ve
.Sp
However, these filepaths appear in the list returned by
\&\f(CWstandard_typemap_locations()\fR in reverse order, \fIi.e.\fR, lowest-to-highest.
.Sp
.Vb 10
\&  \*(Aq/usr/local/lib/perl5/5.10.1/ExtUtils/typemap\*(Aq,
\&  \*(Aq../../../../lib/ExtUtils/typemap\*(Aq,
\&  \*(Aq../../../../typemap\*(Aq,
\&  \*(Aq../../../lib/ExtUtils/typemap\*(Aq,
\&  \*(Aq../../../typemap\*(Aq,
\&  \*(Aq../../lib/ExtUtils/typemap\*(Aq,
\&  \*(Aq../../typemap\*(Aq,
\&  \*(Aq../lib/ExtUtils/typemap\*(Aq,
\&  \*(Aq../typemap\*(Aq,
\&  \*(Aqtypemap\*(Aq
.Ve
.IP \(bu 4
Arguments
.Sp
.Vb 1
\&  my @stl = standard_typemap_locations( \e@INC );
.Ve
.Sp
Reference to \f(CW@INC\fR.
.IP \(bu 4
Return Value
.Sp
Array holding list of directories to be searched for \fItypemap\fR files.
.ie n .SS trim_whitespace()
.el .SS \f(CWtrim_whitespace()\fP
.IX Subsection "trim_whitespace()"
.IP \(bu 4
Purpose
.Sp
Perform an in-place trimming of leading and trailing whitespace from the
first argument provided to the function.
.IP \(bu 4
Argument
.Sp
.Vb 1
\&  trim_whitespace($arg);
.Ve
.IP \(bu 4
Return Value
.Sp
None.  Remember:  this is an \fIin-place\fR modification of the argument.
.ie n .SS C_string()
.el .SS \f(CWC_string()\fP
.IX Subsection "C_string()"
.IP \(bu 4
Purpose
.Sp
Escape backslashes (\f(CW\*(C`\e\*(C'\fR) in prototype strings.
.IP \(bu 4
Arguments
.Sp
.Vb 1
\&      $ProtoThisXSUB = C_string($_);
.Ve
.Sp
String needing escaping.
.IP \(bu 4
Return Value
.Sp
Properly escaped string.
.ie n .SS valid_proto_string()
.el .SS \f(CWvalid_proto_string()\fP
.IX Subsection "valid_proto_string()"
.IP \(bu 4
Purpose
.Sp
Validate prototype string.
.IP \(bu 4
Arguments
.Sp
String needing checking.
.IP \(bu 4
Return Value
.Sp
Upon success, returns the same string passed as argument.
.Sp
Upon failure, returns \f(CW0\fR.
.ie n .SS process_typemaps()
.el .SS \f(CWprocess_typemaps()\fP
.IX Subsection "process_typemaps()"
.IP \(bu 4
Purpose
.Sp
Process all typemap files.
.IP \(bu 4
Arguments
.Sp
.Vb 1
\&  my $typemaps_object = process_typemaps( $args{typemap}, $pwd );
.Ve
.Sp
List of two elements:  \f(CW\*(C`typemap\*(C'\fR element from \f(CW%args\fR; current working
directory.
.IP \(bu 4
Return Value
.Sp
Upon success, returns an ExtUtils::Typemaps object.
.ie n .SS map_type()
.el .SS \f(CWmap_type()\fP
.IX Subsection "map_type()"
.IP \(bu 4
Purpose
.Sp
Performs a mapping at several places inside \f(CW\*(C`PARAGRAPH\*(C'\fR loop.
.IP \(bu 4
Arguments
.Sp
.Vb 1
\&  $type = map_type($self, $type, $varname);
.Ve
.Sp
List of three arguments.
.IP \(bu 4
Return Value
.Sp
String holding augmented version of second argument.
.ie n .SS standard_XS_defs()
.el .SS \f(CWstandard_XS_defs()\fP
.IX Subsection "standard_XS_defs()"
.IP \(bu 4
Purpose
.Sp
Writes to the \f(CW\*(C`.c\*(C'\fR output file certain preprocessor directives and function
headers needed in all such files.
.IP \(bu 4
Arguments
.Sp
None.
.IP \(bu 4
Return Value
.Sp
Returns true.
.ie n .SS assign_func_args()
.el .SS \f(CWassign_func_args()\fP
.IX Subsection "assign_func_args()"
.IP \(bu 4
Purpose
.Sp
Perform assignment to the \f(CW\*(C`func_args\*(C'\fR attribute.
.IP \(bu 4
Arguments
.Sp
.Vb 1
\&  $string = assign_func_args($self, $argsref, $class);
.Ve
.Sp
List of three elements.  Second is an array reference; third is a string.
.IP \(bu 4
Return Value
.Sp
String.
.ie n .SS analyze_preprocessor_statements()
.el .SS \f(CWanalyze_preprocessor_statements()\fP
.IX Subsection "analyze_preprocessor_statements()"
.IP \(bu 4
Purpose
.Sp
Within each function inside each Xsub, print to the \fI.c\fR output file certain
preprocessor statements.
.IP \(bu 4
Arguments
.Sp
.Vb 4
\&      ( $self, $XSS_work_idx, $BootCode_ref ) =
\&        analyze_preprocessor_statements(
\&          $self, $statement, $XSS_work_idx, $BootCode_ref
\&        );
.Ve
.Sp
List of four elements.
.IP \(bu 4
Return Value
.Sp
Modifed values of three of the arguments passed to the function.  In
particular, the \f(CW\*(C`XSStack\*(C'\fR and \f(CW\*(C`InitFileCode\*(C'\fR attributes are modified.
.ie n .SS set_cond()
.el .SS \f(CWset_cond()\fP
.IX Subsection "set_cond()"
.IP \(bu 4
Purpose
.IP \(bu 4
Arguments
.IP \(bu 4
Return Value
.ie n .SS current_line_number()
.el .SS \f(CWcurrent_line_number()\fP
.IX Subsection "current_line_number()"
.IP \(bu 4
Purpose
.Sp
Figures out the current line number in the XS file.
.IP \(bu 4
Arguments
.Sp
\&\f(CW$self\fR
.IP \(bu 4
Return Value
.Sp
The current line number.
.ie n .SS Warn()
.el .SS \f(CWWarn()\fP
.IX Subsection "Warn()"
.IP \(bu 4
Purpose
.Sp
Print warnings with line number details at the end.
.IP \(bu 4
Arguments
.Sp
List of text to output.
.IP \(bu 4
Return Value
.Sp
None.
.ie n .SS WarnHint()
.el .SS \f(CWWarnHint()\fP
.IX Subsection "WarnHint()"
.IP \(bu 4
Purpose
.Sp
Prints warning with line number details. The last argument is assumed
to be a hint string.
.IP \(bu 4
Arguments
.Sp
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.
.IP \(bu 4
Return Value
.Sp
None.
.ie n .SS _MsgHint()
.el .SS \f(CW_MsgHint()\fP
.IX Subsection "_MsgHint()"
.IP \(bu 4
Purpose
.Sp
Constructs an exception message with line number details. The last argument is
assumed to be a hint string.
.IP \(bu 4
Arguments
.Sp
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.
.IP \(bu 4
Return Value
.Sp
The constructed string.
.ie n .SS blurt()
.el .SS \f(CWblurt()\fP
.IX Subsection "blurt()"
.IP \(bu 4
Purpose
.IP \(bu 4
Arguments
.IP \(bu 4
Return Value
.ie n .SS death()
.el .SS \f(CWdeath()\fP
.IX Subsection "death()"
.IP \(bu 4
Purpose
.IP \(bu 4
Arguments
.IP \(bu 4
Return Value
.ie n .SS check_conditional_preprocessor_statements()
.el .SS \f(CWcheck_conditional_preprocessor_statements()\fP
.IX Subsection "check_conditional_preprocessor_statements()"
.IP \(bu 4
Purpose
.IP \(bu 4
Arguments
.IP \(bu 4
Return Value
.ie n .SS escape_file_for_line_directive()
.el .SS \f(CWescape_file_for_line_directive()\fP
.IX Subsection "escape_file_for_line_directive()"
.IP \(bu 4
Purpose
.Sp
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.
.IP \(bu 4
Arguments
.Sp
A string.
.IP \(bu 4
Return Value
.Sp
A string with escapes for double-quotes and backslashes.
.ie n .SS """report_typemap_failure"""
.el .SS \f(CWreport_typemap_failure\fP
.IX Subsection "report_typemap_failure"
.IP \(bu 4
Purpose
.Sp
Do error reporting for missing typemaps.
.IP \(bu 4
Arguments
.Sp
The \f(CW\*(C`ExtUtils::ParseXS\*(C'\fR object.
.Sp
An \f(CW\*(C`ExtUtils::Typemaps\*(C'\fR object.
.Sp
The string that represents the C type that was not found in the typemap.
.Sp
Optionally, the string \f(CW\*(C`death\*(C'\fR or \f(CW\*(C`blurt\*(C'\fR to choose
whether the error is immediately fatal or not. Default: \f(CW\*(C`blurt\*(C'\fR
.IP \(bu 4
Return Value
.Sp
Returns nothing. Depending on the arguments, this
may call \f(CW\*(C`death\*(C'\fR or \f(CW\*(C`blurt\*(C'\fR, the former of which is
fatal.