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>

cpanm XS::Parse::Keyword::FromPerl

perl -MCPAN -e shell
install XS::Parse::Keyword::FromPerl