File Coverage

blib/lib/XS/Parse/Keyword/FromPerl.pm
Criterion Covered Total %
statement 20 20 100.0
branch n/a
condition n/a
subroutine 9 9 100.0
pod n/a
total 29 29 100.0


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