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