blib/lib/Optree/Generate.pm

filter: Statementstmt 97.9% 48 / 49 Branchbran 100% 8 / 8 Conditioncond 71.4% 5 / 7 MC/DCmcdc 50.0% 2 / 4 Subroutinesub 91.6% 11 / 12 Podpod 100% 1 / 1 totaltotal 92.5% 75 / 81 CC 9 SCAR 11.4
CC
9
Cov
95%
make_entersub_op
6.0
import
4.0
__ANON__
1.1
CRAP 3.1
↑ Summary blib/lib/XS/Parse/Keyword/FromPerl.pm »
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 Optree::Generate 0.10;
7  
8 12 ▶use v5.26; # XS code needs op_class() and the OPclass_* constants
Subroutine BEGIN: called CC=1 SCAR=0.0
9 12 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 12 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
12 12 require XSLoader;
13 12 XSLoader::load( __PACKAGE__, our $VERSION );
14 }
15  
16 12 ▶use builtin qw( blessed reftype );
Subroutine BEGIN: called CC=1 SCAR=0.0
17 12 ▶no warnings 'experimental::builtin';
Subroutine BEGIN: called CC=1 SCAR=0.0
18  
19 12 ▶use meta 0.003_002;
Subroutine BEGIN: called CC=1 SCAR=0.0
20 12 ▶no warnings 'meta::experimental';
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 12 require B; # for the B::OP classes
23  
24 12 ▶use Exporter ();
Subroutine BEGIN: called CC=1 SCAR=0.0
25 12 push our @EXPORT_OK, qw(
26 opcode
27 op_contextualize
28 op_scope
29 newOP
30 newASSIGNOP
31 newBINOP
32 newCONDOP
33 newFOROP
34 newGVOP
35 newLISTOP
36 newLOGOP
37 newPADxVOP
38 newSVOP
39 newUNOP
40 make_entersub_op
41 );
42  
43 =head1 NAME
44  
45 C<Optree::Generate> - helper functions for creating optree fragments from Perl
46  
47 =head1 DESCRIPTION
48  
49 This module provides helper functions to allow Perl code to get access to
50 various parts of the C-level API that would be useful when building optrees,
51 such as when parsing and implementing code behind custom keywords. It is
52 mostly intended for use with L<XS::Parse::Keyword::FromPerl> and
53 L<XS::Parse::Infix::FromPerl>.
54  
55 =cut
56  
57 =head1 FUNCTIONS
58  
59 =head2 opcode
60  
61 $type = opcode( $opname );
62  
63 Returns an opcode integer corresponding to the given op name, which should be
64 lowercase and without the leading C<OP_...> prefix. As this involves a linear
65 search across the entire C<PL_op_name> array you may wish to perform this just
66 once and store the result, perhaps using C<use constant> for convenience.
67  
68 use constant OP_CONST => opcode("const");
69  
70 I<Since version 0.08> as an extra convenience for users, requesting to import
71 any symbol named C<OP_...> will dynamically create the required constant
72 functions with this mechanism.
73  
74 use Optree::Generate qw( OP_CONST );
75  
76 =head2 op_contextualize
77  
78 $op = op_contextualize( $op, $context );
79  
80 Applies a syntactic context to an optree representing an expression.
81 C<$context> must be one of the exported constants C<G_VOID>, C<G_SCALAR>, or
82 C<G_LIST>.
83  
84 =head2 op_scope
85  
86 $op = op_scope( $op );
87  
88 Wraps an optree with some additional ops so that a runtime dynamic scope will
89 created.
90  
91 =head2 new*OP
92  
93 This family of functions return a new OP of the given class, for the type,
94 flags, and other arguments specified.
95  
96 A suitable C<$type> can be obtained by using the L</opcode> function.
97  
98 C<$flags> contains the opflags; a bitmask of the following constants.
99  
100 OPf_WANT OPf_WANT_VOID OPf_WANT_SCALAR OPf_WANT_LIST
101 OPf_KIDS
102 OPf_PARENS
103 OPf_REF
104 OPf_MOD
105 OPf_STACKED
106 OPf_SPECIAL
107  
108 The op is returned as a C<B::OP> instance or a subclass thereof.
109  
110 These functions can only be called during the compilation time of a perl
111 subroutine. This is unlikely to be happening most of the time, except during
112 the C<build> phase of a keyword registered using C<XS::Parse::Keyword> or the
113 C<new_op> phase of an infix operator registered using C<XS::Parse::Infix>.
114  
115 =head3 newOP
116  
117 $op = newOP( $type, $flags );
118  
119 Returns a new base OP for the given type and flags.
120  
121 =head3 newASSIGNOP
122  
123 $op = newASSIGNOP( $flags, $left, $optype, $right );
124  
125 Returns a new op representing an assignment operation from the right to the
126 left OP child of the given type. Note the odd order of arguments.
127  
128 =head3 newBINOP
129  
130 $op = newBINOP( $type, $flags, $first, $last );
131  
132 Returns a new BINOP for the given type, flags, and first and last OP child.
133  
134 =head3 newCONDOP
135  
136 $op = newCONDOP( $flags, $first, $trueop, $falseop );
137  
138 Returns a new conditional expression op for the given condition expression and
139 true and false alternatives, all as OP instances.
140  
141 =head3 newFOROP
142  
143 $op = newFOROP( $flags, $svop, $expr, $block, $cont );
144  
145 Returns a new optree representing a heavyweight C<for> loop, given the
146 optional iterator SV op, the list expression, the block, and the optional
147 continue block, all as OP instances.
148  
149 =head3 newGVOP
150  
151 $op = newGVOP( $type, $flags, $gvref );
152  
153 Returns a new SVOP for the given type, flags, and GV given by a GLOB
154 reference. The referred-to GLOB will be stored in the SVOP itself.
155  
156 =head3 newLISTOP
157  
158 $op = newLISTOP( $type, $flags, @children );
159  
160 Returns a new LISTOP for the given type, flags, and child SVs.
161  
162 Note that an arbitrary number of child SVs can be passed here. This wrapper
163 function will automatically perform the C<op_convert_list> conversion from a
164 plain C<OP_LIST> if required.
165  
166 =head3 newLOGOP
167  
168 $op = newLOGOP( $type, $flags, $first, $other );
169  
170 Returns a new LOGOP for the given type, flags, and first and other OP child.
171  
172 =head3 newPADxVOP
173  
174 $op = newPADxVOP( $type, $flags, $padoffset );
175  
176 Returns a new op for the given type, flags, and pad offset. C<$type> must be
177 one of C<OP_PADSV>, C<OP_PADAV>, C<OP_PADHV> or C<OP_PADCV>.
178  
179 =head3 newSVOP
180  
181 $op = newSVOP( $type, $flags, $sv );
182  
183 Returns a new SVOP for the given type, flags, and SV. A copy of the given
184 scalar will be stored in the SVOP itself.
185  
186 =head3 newUNOP
187  
188 $op = newUNOP( $type, $flags, $first );
189  
190 Returns a new UNOP for the given type, flags, and first OP child.
191  
192 =cut
193  
194 =head2 make_entersub_op
195  
196 $op = make_entersub_op( $cv, $argops, ... );
197  
198 A handy wrapper function around calling C<newLISTOP> to create an
199 C<OP_ENTERSUB> op that will invoke a code reference (which may be known at
200 compiletime), with a given list of argument-generating optree framents. This
201 in effect creates a function call.
202  
203 I<$cv> must be one of:
204  
205 =over 2
206  
207 =item *
208  
209 An optree fragment as a C<B::OP> instance, which will be invoked directly to
210 yield the required CV
211  
212 =item *
213  
214 A CODE reference, which will be stored in a C<OP_CONST>
215  
216 =item *
217  
218 A plain string, which will be used to look up a GLOB in the symbol table and
219 stored as a C<OP_GV> + C<OP_RV2CV> pair.
220  
221 =back
222  
223 I<$argops> should be an ARRAY reference containing optree fragments that
224 generate the arguments to the function.
225  
226 Takes the following additional optional named arguments:
227  
228 =over 4
229  
230 =item flags => INT
231  
232 Additional flags to set on the returned C<OP_ENTERSUB>. The C<OPf_STACKED>
233 flag will always be set.
234  
235 =back
236  
237 =cut
238  
239 sub import
240 280 ▶{
Subroutine import: called CC=4 SCAR=13.9
241 280 my $self = shift;
242 280 my @opcodes;
243 280 ▶ @_ = grep { m/^OP_/ ? ( (push @opcodes, $_), 0 ) : 1 } @_;
Branch: 1 branch
BranchTrueFalseTotal
/^OP_/u ? : 22 299 321
244  
245 280 ▶ if( @opcodes ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@opcodes) 8 272 280
246 8 my $callerpkg = meta::package->get( scalar caller );
247 8 foreach my $name ( @opcodes ) {
248 22 my $val = opcode( lc +( $name =~ m/^OP_(.*)$/ )[0] );
249 0 ▶ $callerpkg->add_symbol( '&'.$name => sub () { $val } );
Subroutine __ANON__: not called CC=1 SCAR=1.2
250 }
251 }
252  
253 280 unshift @_, $self;
254 280 goto &Exporter::import;
255 }
256  
257 12 ▶use constant {
Subroutine BEGIN: called CC=1 SCAR=0.0
258 12 OP_CONST => opcode("const"),
259 OP_ENTERSUB => opcode("entersub"),
260 OP_GV => opcode("gv"),
261 OP_RV2CV => opcode("rv2cv"),
262 12 };
263  
264 sub make_entersub_op
265 5 ▶{
Subroutine make_entersub_op: called CC=6 SCAR=18.0
Pod documented
266 5 my ( $cv, $argops, %args ) = @_;
267  
268 5 my $cvop;
269 5 ▶ if( blessed $cv and $cv->isa( "B::OP" ) ) {
Branch: 2 branches
BranchTrueFalseTotal
if (builtin::blessed($cv) and $cv->isa('B::OP')) { } 1 4 5
elsif ((builtin::reftype($cv) // '') eq 'CODE') { } 2 2 4
Condition66%2/3
builtin::blessed($cv) and $cv->isa("B::OP")
!ll&&!rl&&r
401
MC/DC50%1/2
builtin::blessed($cv) and $cv->isa("B::OP")
builtin::blessed($cv) $cv->isa("B::OP")
Truth table66%2/3
A and B
A= builtin::blessed($cv)B= $cv->isa("B::OP")
ABresult
0X0
100
111
270 1 $cvop = $cv;
271 }
272 ▶ elsif( ( reftype $cv // "" ) eq "CODE" ) {
Condition100%2/2
builtin::reftype($cv) // ""
l!l
22
MC/DC100%1/1
builtin::reftype($cv) // ""
builtin::reftype($cv)
Truth table100%2/2
A
A= builtin::reftype($cv)
Aresult
11
00
273 2 $cvop = newSVOP(OP_CONST, 0, $cv);
274 }
275 else {
276 2 my $gv = meta::glob->get( $cv )->reference;
277 2 $cvop = newUNOP(OP_RV2CV, 0, newGVOP(OP_GV, 0, $gv));
278 }
279  
280 5 ▶ my $flags = $args{flags} // 0;
Condition50%1/2
$args{"flags"} // 0
l!l
05
MC/DC0%0/1
$args{"flags"} // 0
$args{"flags"}
Truth table50%1/2
A
A= $args{"flags"}
Aresult
11
00
281 5 return newLISTOP(OP_ENTERSUB, $flags | OPf_STACKED, @$argops, $cvop);
282 }
283  
284 =head1 TODO
285  
286 =over 4
287  
288 =item *
289  
290 More C<new*OP()> wrapper functions.
291  
292 =item *
293  
294 More optree-mangling functions. At least, some way to set the TARG might be
295 handy.
296  
297 =back
298  
299 =cut
300  
301 =head1 AUTHOR
302  
303 Paul Evans <leonerd@leonerd.org.uk>
304  
305 =cut
306  
307 12 0x55AA;
↑ Summary blib/lib/XS/Parse/Keyword/FromPerl.pm »