1ExtUtils::ParseXS::UtilUisteiresC(o3n)tributed Perl DocuEmxetnUttaitliso:n:ParseXS::Utilities(3)
2
3
4

NAME

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

SYNOPSIS

9         use ExtUtils::ParseXS::Utilities qw(
10           standard_typemap_locations
11           trim_whitespace
12           tidy_type
13           C_string
14           valid_proto_string
15           process_typemaps
16           make_targetable
17           map_type
18           standard_XS_defs
19           assign_func_args
20           analyze_preprocessor_statements
21           set_cond
22           Warn
23           blurt
24           death
25           check_conditional_preprocessor_statements
26           escape_file_for_line_directive
27           report_typemap_failure
28         );
29

SUBROUTINES

31       The following functions are not considered to be part of the public
32       interface.  They are documented here for the benefit of future
33       maintainers of this module.
34
35   "standard_typemap_locations()"
36       ·   Purpose
37
38           Provide a list of filepaths where typemap files may be found.  The
39           filepaths -- relative paths to files (not just directory paths) --
40           appear in this list in lowest-to-highest priority.
41
42           The highest priority is to look in the current directory.
43
44             'typemap'
45
46           The second and third highest priorities are to look in the parent
47           of the current directory and a directory called lib/ExtUtils
48           underneath the parent directory.
49
50             '../typemap',
51             '../lib/ExtUtils/typemap',
52
53           The fourth through ninth highest priorities are to look in the
54           corresponding grandparent, great-grandparent and great-great-
55           grandparent directories.
56
57             '../../typemap',
58             '../../lib/ExtUtils/typemap',
59             '../../../typemap',
60             '../../../lib/ExtUtils/typemap',
61             '../../../../typemap',
62             '../../../../lib/ExtUtils/typemap',
63
64           The tenth and subsequent priorities are to look in directories
65           named ExtUtils which are subdirectories of directories found in
66           @INC -- provided a file named typemap actually exists in such a
67           directory.  Example:
68
69             '/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',
70
71           However, these filepaths appear in the list returned by
72           "standard_typemap_locations()" in reverse order, i.e., lowest-to-
73           highest.
74
75             '/usr/local/lib/perl5/5.10.1/ExtUtils/typemap',
76             '../../../../lib/ExtUtils/typemap',
77             '../../../../typemap',
78             '../../../lib/ExtUtils/typemap',
79             '../../../typemap',
80             '../../lib/ExtUtils/typemap',
81             '../../typemap',
82             '../lib/ExtUtils/typemap',
83             '../typemap',
84             'typemap'
85
86       ·   Arguments
87
88             my @stl = standard_typemap_locations( \@INC );
89
90           Reference to @INC.
91
92       ·   Return Value
93
94           Array holding list of directories to be searched for typemap files.
95
96   "trim_whitespace()"
97       ·   Purpose
98
99           Perform an in-place trimming of leading and trailing whitespace
100           from the first argument provided to the function.
101
102       ·   Argument
103
104             trim_whitespace($arg);
105
106       ·   Return Value
107
108           None.  Remember:  this is an in-place modification of the argument.
109
110   "tidy_type()"
111       ·   Purpose
112
113           Rationalize any asterisks ("*") by joining them into bunches,
114           removing interior whitespace, then trimming leading and trailing
115           whitespace.
116
117       ·   Arguments
118
119               ($ret_type) = tidy_type($_);
120
121           String to be cleaned up.
122
123       ·   Return Value
124
125           String cleaned up.
126
127   "C_string()"
128       ·   Purpose
129
130           Escape backslashes ("\") in prototype strings.
131
132       ·   Arguments
133
134                 $ProtoThisXSUB = C_string($_);
135
136           String needing escaping.
137
138       ·   Return Value
139
140           Properly escaped string.
141
142   "valid_proto_string()"
143       ·   Purpose
144
145           Validate prototype string.
146
147       ·   Arguments
148
149           String needing checking.
150
151       ·   Return Value
152
153           Upon success, returns the same string passed as argument.
154
155           Upon failure, returns 0.
156
157   "process_typemaps()"
158       ·   Purpose
159
160           Process all typemap files.
161
162       ·   Arguments
163
164             my $typemaps_object = process_typemaps( $args{typemap}, $pwd );
165
166           List of two elements:  "typemap" element from %args; current
167           working directory.
168
169       ·   Return Value
170
171           Upon success, returns an ExtUtils::Typemaps object.
172
173   "make_targetable()"
174       ·   Purpose
175
176           Populate %targetable.  This constitutes a refinement of the output
177           of "process_typemaps()" with respect to its fourth output,
178           $output_expr_ref.
179
180       ·   Arguments
181
182             %targetable = make_targetable($output_expr_ref);
183
184           Single hash reference:  the fourth such ref returned by
185           "process_typemaps()".
186
187       ·   Return Value
188
189           Hash.
190
191   "map_type()"
192       ·   Purpose
193
194           Performs a mapping at several places inside "PARAGRAPH" loop.
195
196       ·   Arguments
197
198             $type = map_type($self, $type, $varname);
199
200           List of three arguments.
201
202       ·   Return Value
203
204           String holding augmented version of second argument.
205
206   "standard_XS_defs()"
207       ·   Purpose
208
209           Writes to the ".c" output file certain preprocessor directives and
210           function headers needed in all such files.
211
212       ·   Arguments
213
214           None.
215
216       ·   Return Value
217
218           Returns true.
219
220   "assign_func_args()"
221       ·   Purpose
222
223           Perform assignment to the "func_args" attribute.
224
225       ·   Arguments
226
227             $string = assign_func_args($self, $argsref, $class);
228
229           List of three elements.  Second is an array reference; third is a
230           string.
231
232       ·   Return Value
233
234           String.
235
236   "analyze_preprocessor_statements()"
237       ·   Purpose
238
239           Within each function inside each Xsub, print to the .c output file
240           certain preprocessor statements.
241
242       ·   Arguments
243
244                 ( $self, $XSS_work_idx, $BootCode_ref ) =
245                   analyze_preprocessor_statements(
246                     $self, $statement, $XSS_work_idx, $BootCode_ref
247                   );
248
249           List of four elements.
250
251       ·   Return Value
252
253           Modifed values of three of the arguments passed to the function.
254           In particular, the "XSStack" and "InitFileCode" attributes are
255           modified.
256
257   "set_cond()"
258       ·   Purpose
259
260       ·   Arguments
261
262       ·   Return Value
263
264   "current_line_number()"
265       ·   Purpose
266
267           Figures out the current line number in the XS file.
268
269       ·   Arguments
270
271           $self
272
273       ·   Return Value
274
275           The current line number.
276
277   "Warn()"
278       ·   Purpose
279
280       ·   Arguments
281
282       ·   Return Value
283
284   "blurt()"
285       ·   Purpose
286
287       ·   Arguments
288
289       ·   Return Value
290
291   "death()"
292       ·   Purpose
293
294       ·   Arguments
295
296       ·   Return Value
297
298   "check_conditional_preprocessor_statements()"
299       ·   Purpose
300
301       ·   Arguments
302
303       ·   Return Value
304
305   "escape_file_for_line_directive()"
306       ·   Purpose
307
308           Escapes a given code source name (typically a file name but can
309           also be a command that was read from) so that double-quotes and
310           backslashes are escaped.
311
312       ·   Arguments
313
314           A string.
315
316       ·   Return Value
317
318           A string with escapes for double-quotes and backslashes.
319
320   "report_typemap_failure"
321       ·   Purpose
322
323           Do error reporting for missing typemaps.
324
325       ·   Arguments
326
327           The "ExtUtils::ParseXS" object.
328
329           An "ExtUtils::Typemaps" object.
330
331           The string that represents the C type that was not found in the
332           typemap.
333
334           Optionally, the string "death" or "blurt" to choose whether the
335           error is immediately fatal or not. Default: "blurt"
336
337       ·   Return Value
338
339           Returns nothing. Depending on the arguments, this may call "death"
340           or "blurt", the former of which is fatal.
341
342
343
344perl v5.16.3                      2017-08-02   ExtUtils::ParseXS::Utilities(3)