1Sub::Quote(3) User Contributed Perl Documentation Sub::Quote(3)
2
6 Sub::Quote - Efficient generation of subroutines via string eval
7
9 package Silly;
10 use Sub::Quote qw(quote_sub unquote_sub quoted_from_sub);
12 quote_sub 'Silly::kitty', q{ print "meow" };
14 quote_sub 'Silly::doggy', q{ print "woof" };
16 my $sound = 0;
18 quote_sub 'Silly::dagron',
20 q{ print ++$sound % 2 ? 'burninate' : 'roar' },
21 { '$sound' => \$sound };
22 And elsewhere:
24 Silly->kitty; # meow
26 Silly->doggy; # woof
27 Silly->dagron; # burninate
28 Silly->dagron; # roar
29 Silly->dagron; # burninate
30
32 This package provides performant ways to generate subroutines from
33 strings.
34
36 quote_sub
37 my $coderef = quote_sub 'Foo::bar', q{ print $x++ . "\n" }, { '$x' => \0 };
38 Arguments: ?$name, $code, ?\%captures, ?\%options
40 $name is the subroutine where the coderef will be installed.
42 $code is a string that will be turned into code.
44 "\%captures" is a hashref of variables that will be made available to
46 the code. The keys should be the full name of the variable to be made
47 available, including the sigil. The values should be references to the
48 values. The variables will contain copies of the values. See the
49 "SYNOPSIS"'s "Silly::dagron" for an example using captures.
50 Exported by default.
52 options
54 "no_install"
56 Boolean. Set this option to not install the generated coderef into
57 the passed subroutine name on undefer.
58 "no_defer"
60 Boolean. Prevents a Sub::Defer wrapper from being generated for the
61 quoted sub. If the sub will most likely be called at some point,
62 setting this is a good idea. For a sub that will most likely be
63 inlined, it is not recommended.
64 "package"
66 The package that the quoted sub will be evaluated in. If not
67 specified, the package from sub calling "quote_sub" will be used.
68 "hints"
70 The value of $^H to use for the code being evaluated. This captures
71 the settings of the strict pragma. If not specified, the value from
72 the calling code will be used.
73 "warning_bits"
75 The value of "${^WARNING_BITS}" to use for the code being evaluated.
76 This captures the warnings set. If not specified, the warnings from
77 the calling code will be used.
78 "%^H"
80 The value of "%^H" to use for the code being evaluated. This
81 captures additional pragma settings. If not specified, the value
82 from the calling code will be used if possible (on perl 5.10+).
83 "attributes"
85 The "Subroutine Attributes" in perlsub to apply to the sub generated.
86 Should be specified as an array reference. The attributes will be
87 applied to both the generated sub and the deferred wrapper, if one is
88 used.
89 "file"
91 The apparent filename to use for the code being evaluated.
92 "line"
94 The apparent line number to use for the code being evaluated.
95 unquote_sub
97 my $coderef = unquote_sub $sub;
98 Forcibly replace subroutine with actual code.
100 If $sub is not a quoted sub, this is a no-op.
102 Exported by default.
104 quoted_from_sub
106 my $data = quoted_from_sub $sub;
107 my ($name, $code, $captures, $compiled_sub) = @$data;
109 Returns original arguments to quote_sub, plus the compiled version if
111 this sub has already been unquoted.
112 Note that $sub can be either the original quoted version or the
114 compiled version for convenience.
115 Exported by default.
117 inlinify
119 my $prelude = capture_unroll '$captures', {
120 '$x' => 1,
121 '$y' => 2,
122 }, 4;
123 my $inlined_code = inlinify q{
125 my ($x, $y) = @_;
126 print $x + $y . "\n";
128 }, '$x, $y', $prelude;
129 Takes a string of code, a string of arguments, a string of code which
131 acts as a "prelude", and a Boolean representing whether or not to
132 localize the arguments.
133 quotify
135 my $quoted_value = quotify $value;
136 Quotes a single (non-reference) scalar value for use in a code string.
138 Numbers aren't treated specially and will be quoted as strings, but
139 undef will quoted as "undef()".
140 capture_unroll
142 my $prelude = capture_unroll '$captures', {
143 '$x' => 1,
144 '$y' => 2,
145 }, 4;
146 Arguments: $from, \%captures, $indent
148 Generates a snippet of code which is suitable to be used as a prelude
150 for "inlinify". $from is a string will be used as a hashref in the
151 resulting code. The keys of %captures are the names of the variables
152 and the values are ignored. $indent is the number of spaces to indent
153 the result by.
154 qsub
156 my $hash = {
157 coderef => qsub q{ print "hello"; },
158 other => 5,
159 };
160 Arguments: $code
162 Works exactly like "quote_sub", but includes a prototype to only accept
164 a single parameter. This makes it easier to include in hash structures
165 or lists.
166 Exported by default.
168 sanitize_identifier
170 my $var_name = '$variable_for_' . sanitize_identifier('@name');
171 quote_sub qq{ print \$${var_name} }, { $var_name => \$value };
172 Arguments: $identifier
174 Sanitizes a value so that it can be used in an identifier.
176
178 SUB_QUOTE_DEBUG
179 Causes code to be output to "STDERR" before being evaled. Several
180 forms are supported:
181 1 All subs will be output.
183 "/foo/"
185 Subs will be output if their code matches the given regular
186 expression.
187 "simple_identifier"
189 Any sub with the given name will be output.
190 "Full::identifier"
192 A sub matching the full name will be output.
193 "Package::Name::"
195 Any sub in the given package (including anonymous subs) will be
196 output.
197
199 Much of this is just string-based code-generation, and as a result, a
200 few caveats apply.
201 return
203 Calling "return" from a quote_sub'ed sub will not likely do what you
204 intend. Instead of returning from the code you defined in "quote_sub",
205 it will return from the overall function it is composited into.
206 So when you pass in:
208 quote_sub q{ return 1 if $condition; $morecode }
210 It might turn up in the intended context as follows:
212 sub foo {
214 <important code a>
216 do {
217 return 1 if $condition;
218 $morecode
219 };
220 <important code b>
221 }
223 Which will obviously return from foo, when all you meant to do was
225 return from the code context in quote_sub and proceed with running
226 important code b.
227 pragmas
229 "Sub::Quote" preserves the environment of the code creating the quoted
230 subs. This includes the package, strict, warnings, and any other
231 lexical pragmas. This is done by prefixing the code with a block that
232 sets up a matching environment. When inlining "Sub::Quote" subs, care
233 should be taken that user pragmas won't effect the rest of the code.
234
236 Users' IRC: #moose on irc.perl.org
237 Development and contribution IRC: #web-simple on irc.perl.org
239 Bugtracker:
241 <https://rt.cpan.org/Public/Dist/Display.html?Name=Sub-Quote>
242 Git repository: <git://github.com/moose/Sub-Quote.git>
244 Git browser: <https://github.com/moose/Sub-Quote>
246
248 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
249
251 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
252 ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
254 Mithaldu - Christian Walde (cpan:MITHALDU)
256 <walde.christian@googlemail.com>
257 tobyink - Toby Inkster (cpan:TOBYINK) <tobyink@cpan.org>
259 haarg - Graham Knop (cpan:HAARG) <haarg@cpan.org>
261 bluefeet - Aran Deltac (cpan:BLUEFEET) <bluefeet@gmail.com>
263 ether - Karen Etheridge (cpan:ETHER) <ether@cpan.org>
265 dolmen - Olivier Mengué (cpan:DOLMEN) <dolmen@cpan.org>
267 alexbio - Alessandro Ghedini (cpan:ALEXBIO) <alexbio@cpan.org>
269 getty - Torsten Raudssus (cpan:GETTY) <torsten@raudss.us>
271 arcanez - Justin Hunter (cpan:ARCANEZ) <justin.d.hunter@gmail.com>
273 kanashiro - Lucas Kanashiro (cpan:KANASHIRO)
275 <kanashiro.duarte@gmail.com>
276 djerius - Diab Jerius (cpan:DJERIUS) <djerius@cfa.harvard.edu>
278
280 Copyright (c) 2010-2016 the Sub::Quote "AUTHOR" and "CONTRIBUTORS" as
281 listed above.
282
284 This library is free software and may be distributed under the same
285 terms as perl itself. See <http://dev.perl.org/licenses/>.
286perl v5.28.1 2019-03-10 Sub::Quote(3)