From Code to Community: Sponsoring The Perl and Raku Conference 2025 Learn more

 / 
XS-Parse-Keyword-FromPerl-0.10
River stage zero No dependents
/ Optree::Generate

NAME

Optree::Generate - helper functions for creating optree fragments from Perl

DESCRIPTION

This module provides helper functions to allow Perl code to get access to various parts of the C-level API that would be useful when building optrees, such as when parsing and implementing code behind custom keywords. It is mostly intended for use with XS::Parse::Keyword::FromPerl and XS::Parse::Infix::FromPerl.

FUNCTIONS

opcode


            

              
              
$type = opcode( $opname );

Returns an opcode integer corresponding to the given op name, which should be lowercase and without the leading OP_... prefix. As this involves a linear search across the entire PL_op_name array you may wish to perform this just once and store the result, perhaps using use constant for convenience.


            

              
              
use constant OP_CONST => opcode("const");

Since version 0.08 as an extra convenience for users, requesting to import any symbol named OP_... will dynamically create the required constant functions with this mechanism.


            

              
              
use Optree::Generate qw( OP_CONST );

op_contextualize


            

              
              
$op = op_contextualize( $op, $context );

Applies a syntactic context to an optree representing an expression. $context must be one of the exported constants G_VOID, G_SCALAR, or G_LIST.

op_scope


            

              
              
$op = op_scope( $op );

Wraps an optree with some additional ops so that a runtime dynamic scope will created.

new*OP

This family of functions return a new OP of the given class, for the type, flags, and other arguments specified.

A suitable $type can be obtained by using the "opcode" function.

$flags contains the opflags; a bitmask of the following constants.


            

              
              
OPf_WANT OPf_WANT_VOID OPf_WANT_SCALAR OPf_WANT_LIST
OPf_KIDS
OPf_PARENS
OPf_REF
OPf_MOD
OPf_STACKED
OPf_SPECIAL

The op is returned as a B::OP instance or a subclass thereof.

These functions can only be called during the compilation time of a perl subroutine. This is unlikely to be happening most of the time, except during the build phase of a keyword registered using XS::Parse::Keyword or the new_op phase of an infix operator registered using XS::Parse::Infix.

newOP


            

              
              
$op = newOP( $type, $flags );

Returns a new base OP for the given type and flags.

newASSIGNOP


            

              
              
$op = newASSIGNOP( $flags, $left, $optype, $right );

Returns a new op representing an assignment operation from the right to the left OP child of the given type. Note the odd order of arguments.

newBINOP


            

              
              
$op = newBINOP( $type, $flags, $first, $last );

Returns a new BINOP for the given type, flags, and first and last OP child.

newCONDOP


            

              
              
$op = newCONDOP( $flags, $first, $trueop, $falseop );

Returns a new conditional expression op for the given condition expression and true and false alternatives, all as OP instances.

newFOROP


            

              
              
$op = newFOROP( $flags, $svop, $expr, $block, $cont );

Returns a new optree representing a heavyweight for loop, given the optional iterator SV op, the list expression, the block, and the optional continue block, all as OP instances.

newGVOP


            

              
              
$op = newGVOP( $type, $flags, $gvref );

Returns a new SVOP for the given type, flags, and GV given by a GLOB reference. The referred-to GLOB will be stored in the SVOP itself.

newLISTOP


            

              
              
$op = newLISTOP( $type, $flags, @children );

Returns a new LISTOP for the given type, flags, and child SVs.

Note that an arbitrary number of child SVs can be passed here. This wrapper function will automatically perform the op_convert_list conversion from a plain OP_LIST if required.

newLOGOP


            

              
              
$op = newLOGOP( $type, $flags, $first, $other );

Returns a new LOGOP for the given type, flags, and first and other OP child.

newPADxVOP


            

              
              
$op = newPADxVOP( $type, $flags, $padoffset );

Returns a new op for the given type, flags, and pad offset. $type must be one of OP_PADSV, OP_PADAV, OP_PADHV or OP_PADCV.

newSVOP


            

              
              
$op = newSVOP( $type, $flags, $sv );

Returns a new SVOP for the given type, flags, and SV. A copy of the given scalar will be stored in the SVOP itself.

newUNOP


            

              
              
$op = newUNOP( $type, $flags, $first );

Returns a new UNOP for the given type, flags, and first OP child.

make_entersub_op


            

              
              
$op = make_entersub_op( $cv, $argops, ... );

A handy wrapper function around calling newLISTOP to create an OP_ENTERSUB op that will invoke a code reference (which may be known at compiletime), with a given list of argument-generating optree framents. This in effect creates a function call.

$cv must be one of:

  • An optree fragment as a B::OP instance, which will be invoked directly to yield the required CV

  • A CODE reference, which will be stored in a OP_CONST

  • A plain string, which will be used to look up a GLOB in the symbol table and stored as a OP_GV + OP_RV2CV pair.

$argops should be an ARRAY reference containing optree fragments that generate the arguments to the function.

Takes the following additional optional named arguments:

flags => INT

Additional flags to set on the returned OP_ENTERSUB. The OPf_STACKED flag will always be set.

TODO

  • More new*OP() wrapper functions.

  • More optree-mangling functions. At least, some way to set the TARG might be handy.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>