blib/lib/XS/Parse/Keyword/FromPerl.pm

filter: Statementstmt 95.5% 43 / 45 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 88.8% 8 / 9 Podpod n/a totaltotal 94.4% 51 / 54 CC 1 SCAR 1.1
CC
1
Cov
96%
__ANON__
2.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.1
« blib/lib/Optree/Generate.pm ↑ Summary hax/perl-additions.c.inc »
1 # You may distribute under the terms of either the GNU General Public License
2 # or the Artistic License (the same terms as Perl itself)
3 #
4 # (C) Paul Evans, 2023-2024 -- leonerd@leonerd.org.uk
5  
6 package XS::Parse::Keyword::FromPerl 0.10;
7  
8 10 ▶use v5.26; # XS code needs op_class() and the OPclass_* constants
Subroutine BEGIN: called CC=1 SCAR=0.0
9 10 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 10 ▶use meta 0.003_002;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 10 ▶no warnings 'meta::experimental';
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 10 require XSLoader;
15 10 XSLoader::load( __PACKAGE__, our $VERSION );
16  
17 =head1 NAME
18  
19 C<XS::Parse::Keyword::FromPerl> - drive C<XS::Parse::Keyword> directly from Perl
20  
21 =head1 DESCRIPTION
22  
23 This module provides a Perl-visible API wrapping (some of) the functionality
24 provided by L<XS::Parse::Keyword>, allowing extension keywords to be added to
25 the Perl language by writing code in Perl itself.
26  
27 It provides a thin wrapping layer over the XS functions provided by XPK
28 itself. No real attempt is made here to provide further abstractions on top of
29 the API already provided by Perl and XPK, so users will have to be familiar
30 with the overall concepts there as well.
31  
32 This module is currently experimental, on top of the already-experimental
33 nature of C<XS::Parse::Keyword> itself.
34  
35 =cut
36  
37 10 ▶use Exporter 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
38 10 push our @EXPORT_OK, qw(
39 register_xs_parse_keyword
40 );
41  
42 # Most of the optree stuff is imported from Optree::Generate
43 10 require Optree::Generate;
44 10 foreach my $sym (qw(
45 opcode
46 op_contextualize
47 op_scope
48 newOP
49 newASSIGNOP
50 newBINOP
51 newCONDOP
52 newFOROP
53 newGVOP
54 newLISTOP
55 newLOGOP
56 newPADxVOP
57 newSVOP
58 newUNOP
59 G_VOID G_SCALAR G_LIST
60 OPf_WANT OPf_WANT_VOID OPf_WANT_SCALAR OPf_WANT_LIST
61 OPf_KIDS
62 OPf_PARENS
63 OPf_REF
64 OPf_MOD
65 OPf_STACKED
66 OPf_SPECIAL
67 )) {
68 270 Optree::Generate->import( $sym );
69 270 push @EXPORT_OK, $sym;
70 }
71  
72 =head1 OPTREE FUNCTIONS
73  
74 The L<Optree::Generate> module contains a selection of helper functions to
75 allow Perl code to get access to various parts of the C-level API that would
76 be useful when building optrees for keywords. They used to be part of this
77 module, and so are currently re-exported for convenience, but a later version
78 of this module may start emitting warnings when they are used this way, and
79 eventually that may stop being provided at all.
80  
81 Code needing these should import them directly:
82  
83 use Optree::Generate qw( opcode newUNOP ... );
84  
85 =head1 XPK FUNCTIONS
86  
87 =head2 register_xs_parse_keyword
88  
89 register_xs_parse_keyword "name" => %args;
90  
91 Registers a new extension keyword into the C<XS::Parse::Keyword> registry,
92 defined using the given name and arguments.
93  
94 Takes the following named arguments:
95  
96 =over 4
97  
98 =item flags => INT
99  
100 Optional. If present, a bitmask of the following flag constants:
101  
102 =over 4
103  
104 =item XPK_FLAG_EXPR
105  
106 The build phase is expected to return C<KEYWORD_PLUGIN_EXPR>.
107  
108 =item XPK_FLAG_STMT
109  
110 The build phase is expected to return C<KEYWORD_PLUGIN_STMT>.
111  
112 =item XPK_FLAG_AUTOSEMI
113  
114 The syntax forms a complete statement, which should be followed by C<;>.
115  
116 =back
117  
118 =item pieces => ARRAY
119  
120 Optional. If present, contains definitions for the syntax pieces to be parsed
121 for the syntax of this keyword. This must be composed of a list of calls to
122 the various C<XPK_...> piece-generating functions; documented below.
123  
124 =item permit_hintkey => STRING
125  
126 Optional. A string value to use for the "permit_hintkey".
127  
128 =item permit => CODE
129  
130 Optional. Callback function for the "permit" phase of keyword parsing.
131  
132 $ok = $permit->( $hookdata );
133  
134 When invoked, it is passed a single arugment containing the (optional)
135 hookdata value, and its result should be a boolean scalar.
136  
137 At least one of C<permit_hintkey> or C<permit> must be provided.
138  
139 =item check => CODE
140  
141 Optional. Callback function for the "check" phase of keyword parsing.
142  
143 $check->( $hookdata );
144  
145 When invoked, it is passsed a single argument containing the (optional)
146 bookdata value.
147  
148 =item build => CODE
149  
150 Callback function for the "build" phase of keyword parsing.
151  
152 $ret = $build->( \$out, \@args, $hookdata );
153  
154 When invoked, it is passed a SCALAR ref to store the output optree into, an
155 ARRAY reference containing the parsed arguments, and the (optional) hookdata
156 value.
157  
158 The C<@args> array will contain object references referring to the individual
159 arguments parsed by the parser pieces. See L</Parser Arguments>.
160  
161 The callback function should be build an optree as a C<B::OP> fragment,
162 possibly by calling the various C<new*OP()> functions defined above, and store
163 the eventual result into the scalar referred to by the first argument.
164  
165 The callback should return one of C<KEYWORD_PLUGIN_EXPR> or
166 C<KEYWORD_PLUGIN_STMT> to indicate how its syntax should be interpreted by the
167 perl parser.
168  
169 =item hookdata => SCALAR
170  
171 Optional. If present, this scalar value is stored by the keyword definition
172 and passed into each of the phase callbacks when invoked. If not present then
173 C<undef> will be passed to the callbacks instead.
174  
175 =back
176  
177 =cut
178  
179 =head2 Piece Type Functions
180  
181 The following functions can be used to generate parsing pieces.
182  
183 Many simple piece types have an variant which is optional; if the input source
184 does not look like the expected syntax for the piece type then it will emit
185 C<undef> rather than raise an error. These piece types have their names
186 suffixed by C<_OPT>.
187  
188 =head3 XPK_BLOCK
189  
190 A block of code, returned in the I<op> field.
191  
192 =head3 XPK_ANONSUB
193  
194 An anonymous subroutine, returned in the I<cv> field.
195  
196 =head3 XPK_ARITHEXPR, XPK_ARITHEXPR_OPT
197  
198 An arithemetic expression, returned in the I<op> field.
199  
200 =head3 XPK_TERMEXPR, XPK_TERMEXPR_OPT
201  
202 A term expression, returned in the I<op> field.
203  
204 =head3 XPK_LISTEXPR, XPK_LISTEXPR_OPT
205  
206 A list expression, returned in the I<op> field.
207  
208 =head3 XPK_IDENT, XPK_IDENT_OPT
209  
210 An identifier, returned as a string in the I<sv> field.
211  
212 =head3 XPK_PACKAGENAME, XPK_PACKAGENAME_OPT
213  
214 A package name, returned as a string in the I<sv> field.
215  
216 =head3 XPK_LEXVARNAME
217  
218 XPK_LEXVARNAME($kind)
219  
220 A lexical variable name, returned as a string in the I<sv> field.
221  
222 The C<$kind> must be a bitmask of C<XPK_LEXVAR_SCALAR>, C<XPK_LEXVAR_ARRAY>,
223 C<XPK_LEXVAR_HASH>; or C<XPK_LEXVAR_ANY> for convenience to set all three.
224  
225 =head3 XPK_VSTRING, XPK_VSTRING_OPT
226  
227 A version string, returned as a L<version> object instance in the I<sv> field.
228  
229 =head3 XPK_LEXVAR
230  
231 XPK_LEXVAR($kind)
232  
233 A lexical variable that already exists in the pad, returned as a pad offset in
234 the I<padix> field.
235  
236 C<$kind> is specified as in C<XPK_LEXVARNAME>.
237  
238 =head3 XPK_LEXVAR_MY
239  
240 XPK_LEXVAR_MY($kind)
241  
242 A lexical variable, parsed as if it appeared in a C<my> expression. It will be
243 added to the pad and returned as a pad offset in the I<padix> field.
244  
245 =head3 XPK_COMMA
246  
247 =head3 XPK_COLON
248  
249 =head3 XPK_EQUALS
250  
251 A literal comma, colon or equals sign. These do not appear in the arguments
252 list.
253  
254 =head3 XPK_LITERAL
255  
256 XPK_LISTEXPR($string)
257  
258 A literal string match. No value is returned.
259  
260 This should be avoided if at all possible, in favour of the character matches
261 above, or C<XPK_KEYWORD>.
262  
263 =head3 XPK_KEYWORD
264  
265 XPK_KEYWORD($string)
266  
267 A literal string match, which requires that the following text does not begin
268 with an identifier character (thus avoiding prefix-match problems). No value
269 is returned.
270  
271 =head3 XPK_INTRO_MY
272  
273 Calls the perl C<intro_my()> function immediately. No input is consumed and no
274 output value is generated.
275  
276 =head3 XPK_WARNING
277  
278 XPK_WARNING($message)
279  
280 Emits a warning by callling the core perl C<warn()> function immediately.
281  
282 =head3 XPK_WARNING_...
283  
284 XPK_WARNING_AMBIGUOUS($message)
285 XPK_WARNING_DEPRECATED($message)
286 XPK_WARNING_EXPERIMENTAL($message)
287 XPK_WARNING_PRECEDENCE($message)
288 XPK_WARNING_SYNTAX($message)
289  
290 Several variants of L</XPK_WARNING> that are conditional on various warning
291 categories being enabled.
292  
293 =head3 XPK_SEQUENCE
294  
295 XPK_SEQUENCE(@pieces)
296  
297 A sub-sequence. Normally this is not necessary, as most of the
298 structure-forming functions already take a sequence of pieces. It is mostly
299 useful as as an option to the C<XPK_CHOICE> function.
300  
301 Nothing extra is returned, beyond the values from the individual pieces.
302  
303 =head3 XPK_OPTIONAL
304  
305 XPK_OPTIONAL(@pieces)
306  
307 An optional sequence of pieces that may or may not be present. Returns an
308 integer value in the I<i> field of 0 if the sequence was not found, or 1
309 followed by its values if the sequence was found.
310  
311 =head3 XPK_REPEATED
312  
313 XPK_REPEATED(@pieces)
314  
315 A repeating sequence of pieces. Returns an integer value in the I<i> field
316 indicating how many times the sequence repeated, followed by all the values
317 returned by each.
318  
319 =head3 XPK_CHOICE
320  
321 XPK_CHOICE(@pieces)
322  
323 The pieces of this function are not interpreted as a sequence, but instead
324 as a list of possible choices. Returns an integer value in the I<i> field
325 indicating which choice was found, followed by all the values returned by
326 that sequence.
327  
328 The first possible choice is numbered C<0>. If no choice matched, it returns
329 C<-1>. To cause an error instead, use L<XPK_FAILURE>.
330  
331 =head3 XPK_FAILURE
332  
333 XPK_FAILURE($message)
334  
335 Attempting to parse this piece type will immediately cause a compile-time
336 failure with the given message. This can be used as the final option in
337 C<XPK_CHOICE> to ensure a valid match.
338  
339 =head3 XPK_PARENS
340  
341 XPK_PARENS(@pieces)
342  
343 Expects to find a sequence of pieces, all surrounded by parentheses (round
344 brackets, C<( ... )>).
345  
346 Nothing extra is returned, beyond the values from the individual contained
347 pieces.
348  
349 =head3 XPK_ARGS
350  
351 XPK_ARGS(@pieces)
352  
353 A container similar to C<XPK_PARENS> except that the parentheses themselves
354 are optional, similar to perl's parsing of calls to known functions.
355  
356 =head3 XPK_BRACKETS
357  
358 XPK_BRACKETS(@pieces)
359  
360 Expects to find a sequence of pieces, all surrounded by square brackets
361 (C<[ ... ]>).
362  
363 Nothing extra is returned, beyond the values from the individual contained
364 pieces.
365  
366 =head3 XPK_BRACES
367  
368 XPK_BRACES(@pieces)
369  
370 Expects to find a sequence of pieces, all surrounded by braces (C<{ ... }>).
371  
372 Nothing extra is returned, beyond the values from the individual contained
373 pieces.
374  
375 =head3 XPK_CHEVRONS
376  
377 XPK_CHEVRONS(@pieces)
378  
379 Expects to find a sequence of pieces, all surrounded by chevrons (angle
380 brackets, C<< < ... > >>).
381  
382 Nothing extra is returned, beyond the values from the individual contained
383 pieces.
384  
385 =cut
386  
387 10 my $thispkg = meta::get_this_package();
388  
389 # Simple pieces
390 10 foreach (qw(
391 BLOCK ANONSUB ARITHEXPR TERMEXPR LISTEXPR IDENT IDENT_OPT
392 PACKAGENAME PACKAGENAME_OPT VSTRING VSTRING_OPT COMMA COLON EQUALS
393 )) {
394 140 my $name = "XPK_$_";
395 140 push @EXPORT_OK, $name;
396 12 ▶ $thispkg->add_symbol( "\&$name" => sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
397 12 bless [$name], "XS::Parse::Keyword::FromPerl::_Piece";
398 140 } );
399 }
400 # Single-SV parametric pieces
401 10 foreach (qw(
402 LEXVARNAME LEXVAR LEXVAR_MY LITERAL KEYWORD FAILURE WARNING
403 )) {
404 70 my $name = "XPK_$_";
405 70 push @EXPORT_OK, $name;
406 4 ▶ $thispkg->add_symbol( "\&$name" => sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
407 4 bless [$name, $_[0]], "XS::Parse::Keyword::FromPerl::_Piece";
408 70 } );
409 }
410 # Structural multiple-value pieces
411 10 foreach (qw(
412 SEQUENCE OPTIONAL REPEATED CHOICE
413 PARENS ARGS BRACKETS BRACES CHEVRONS
414 )) {
415 90 my $name = "XPK_$_";
416 90 push @EXPORT_OK, $name;
417 3 ▶ $thispkg->add_symbol( "\&$name" => sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
418 3 bless [$name, [@_]], "XS::Parse::Keyword::FromPerl::_Piece";
419 90 } );
420 }
421  
422 # Back-compat wrappers for the old names
423 10 foreach (qw( PAREN ARG BRACKET BRACE CHEVRON )) {
424 50 my $macroname = "XPK_${_}S";
425 50 my $funcname = "XPK_${_}SCOPE";
426 50 push @EXPORT_OK, $funcname;
427 0 ▶ $thispkg->add_symbol( "\&$funcname" => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
428 0 warnings::warnif deprecated => "$funcname is now deprecated; use $macroname instead";
429 0 bless [$macroname, [@_]], "XS::Parse::Keyword::FromPerl::_Piece";
430 50 } );
431 }
432  
433 =head2 Parser Arguments
434  
435 Each of the values given in the C<@args> array for the "build" phase callback
436 are given as object references having the following methods
437  
438 =head3 op
439  
440 $op = $arg->op;
441  
442 Returns an optree.
443  
444 =head3 cv
445  
446 $cv = $arg->cv;
447  
448 Returns a CV wrapped in a CODE reference.
449  
450 =head3 sv
451  
452 $sv = $arg->sv;
453  
454 Returns the SV itself, or C<undef> if the optional SV was absent.
455  
456 =head3 has_sv
457  
458 $ok = $arg->has_sv;
459  
460 Returns true if the optional SV was present (even if it was C<undef>), or
461 false if it was absent.
462  
463 =head3 i
464  
465 $i = $arg->i;
466  
467 Returns an integer.
468  
469 =head3 padix
470  
471 $padix = $arg->padix;
472  
473 Returns a pad offset index as an integer.
474  
475 =head3 line
476  
477 $line = $arg->line;
478  
479 Returns the line number of the source text on which the piece was started.
480  
481 =cut
482  
483 =head1 AUTHOR
484  
485 Paul Evans <leonerd@leonerd.org.uk>
486  
487 =cut
488  
489 10 0x55AA;
« blib/lib/Optree/Generate.pm ↑ Summary hax/perl-additions.c.inc »