Sub::QuoteX::Utils Sub::QuoteX::Utils provides a simplified interface to the process of combining Sub::Quote compatible code references with new code. Sub::Quote provides a number of routines to make code more performant by inlining syntactically complete chunks of code into a single compiled subroutine. When a chunk of code is compiled into a subroutine by "Sub::Quote::quote_sub()", Sub::Quote keeps track of the code and any captured variables used to construct that subroutine, so that new code can be added to the original code and the results compiled into a new subroutine. Sub::QuoteX::Utils makes that latter process a little easier. Usage Typically, "quote_subs" is used rather than the lower level "inlinify_*" routines. "quote_subs" is passed a list of chunk specifications or snippets of code, and generates code which is isolated in a Perl block. Each code chunk is additionally isolated in its own block, while code snippets are in the main block. This permits manipulation of the code chunk values. This is schematically equivalent to { do { }; do { }; do { }; } The values of each chunk may be stored (see "Storing Chunk Values") and manipulated by the code snippets. Storing Chunk Values A code chunk may have it's value stored in a lexical variable by adding the "store" option to the chunk's options. For example, quote_subs( [ q{ sqrt(2); }, { store => '$x' } ], [ q{ log(2); }, { store => '$y' } ], [ q{ ( 0..10 ); }, { store => '@z' } ], \q{print $x + $y, "\n";}, ); would result in code equivalent to: { my ( $x, $y, @z ); $x = do { sqrt(2) }; $y = do { log(2) }; @z = do { ( 0.. 10 ) }; print $x + $y, "\n"; } If the variable passed to "store" has no sigil, e.g. "x", then the calling context is taken into account. In list context, the value is stored in @x, in scalar context it is stored in $x and in void context it is not stored at all. Automatic declaration of the variables occurs only when "quote_subs" is used to generate the code. Captures Sub::Quote keeps track of captured variables in hashes, *copying* the values. For example, use Sub::Quote; my $sound = 'woof'; my $emit = quote_sub( q{ print "$sound\n" }, { '$sound' => \$sound } ); &$emit; # woof $sound = 'meow'; &$emit; # woof When combining chunks of inlined code, each chunk has it's own set of captured values which must be kept distinct. "quote_subs" manages this for the caller, but when using the low level routines ( "inlinify_coderef", "inlinify_method", "inlinify_code" ) the caller must manage the captures. These routines store per-chunk captures in their "\%global_capture" argument. The calling routine optionally may provide a mnemonic (but unique!) string which will be part of the key for the chunk. The %global_capture hash should be passed to "quote_sub" in Sub::Quote, when the final subroutine is compiled. For example, my %global_capture; my $code = inlinify_coderef( \%global_capture, $coderef, %options ); # add more code to $code [...] $new_coderef = Sub::Quote::quote_sub( $code, \%global_capture ); INSTALLATION This is a Perl module distribution. It should be installed with whichever tool you use to manage your installation of Perl, e.g. any of cpanm . cpan . cpanp -i . Consult http://www.cpan.org/modules/INSTALL.html for further instruction. Should you wish to install this module manually, the procedure is perl Makefile.PL make make test make install COPYRIGHT AND LICENSE This software is Copyright (c) 2016 by Smithsonian Astrophysical Observatory. This is free software, licensed under: The GNU General Public License, Version 3, June 2007