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 The result should reproduce the original value, including strings,
139 undef, integers, and floating point numbers. The resulting floating
140 point numbers (including infinites and not a number) should be
141 precisely equal to the original, if possible. The exact format of the
142 resulting number should not be relied on, as it may include hex floats
143 or math expressions.
144 capture_unroll
146 my $prelude = capture_unroll '$captures', {
147 '$x' => 1,
148 '$y' => 2,
149 }, 4;
150 Arguments: $from, \%captures, $indent
152 Generates a snippet of code which is suitable to be used as a prelude
154 for "inlinify". $from is a string will be used as a hashref in the
155 resulting code. The keys of %captures are the names of the variables
156 and the values are ignored. $indent is the number of spaces to indent
157 the result by.
158 qsub
160 my $hash = {
161 coderef => qsub q{ print "hello"; },
162 other => 5,
163 };
164 Arguments: $code
166 Works exactly like "quote_sub", but includes a prototype to only accept
168 a single parameter. This makes it easier to include in hash structures
169 or lists.
170 Exported by default.
172 sanitize_identifier
174 my $var_name = '$variable_for_' . sanitize_identifier('@name');
175 quote_sub qq{ print \$${var_name} }, { $var_name => \$value };
176 Arguments: $identifier
178 Sanitizes a value so that it can be used in an identifier.
180
182 SUB_QUOTE_DEBUG
183 Causes code to be output to "STDERR" before being evaled. Several
184 forms are supported:
185 1 All subs will be output.
187 "/foo/"
189 Subs will be output if their code matches the given regular
190 expression.
191 "simple_identifier"
193 Any sub with the given name will be output.
194 "Full::identifier"
196 A sub matching the full name will be output.
197 "Package::Name::"
199 Any sub in the given package (including anonymous subs) will be
200 output.
201
203 Much of this is just string-based code-generation, and as a result, a
204 few caveats apply.
205 return
207 Calling "return" from a quote_sub'ed sub will not likely do what you
208 intend. Instead of returning from the code you defined in "quote_sub",
209 it will return from the overall function it is composited into.
210 So when you pass in:
212 quote_sub q{ return 1 if $condition; $morecode }
214 It might turn up in the intended context as follows:
216 sub foo {
218 <important code a>
220 do {
221 return 1 if $condition;
222 $morecode
223 };
224 <important code b>
225 }
227 Which will obviously return from foo, when all you meant to do was
229 return from the code context in quote_sub and proceed with running
230 important code b.
231 pragmas
233 "Sub::Quote" preserves the environment of the code creating the quoted
234 subs. This includes the package, strict, warnings, and any other
235 lexical pragmas. This is done by prefixing the code with a block that
236 sets up a matching environment. When inlining "Sub::Quote" subs, care
237 should be taken that user pragmas won't effect the rest of the code.
238
240 Users' IRC: #moose on irc.perl.org
241 Development and contribution IRC: #web-simple on irc.perl.org
243 Bugtracker:
245 <https://rt.cpan.org/Public/Dist/Display.html?Name=Sub-Quote>
246 Git repository: <git://github.com/moose/Sub-Quote.git>
248 Git browser: <https://github.com/moose/Sub-Quote>
250
252 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
253
255 frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
256 ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
258 Mithaldu - Christian Walde (cpan:MITHALDU)
260 <walde.christian@googlemail.com>
261 tobyink - Toby Inkster (cpan:TOBYINK) <tobyink@cpan.org>
263 haarg - Graham Knop (cpan:HAARG) <haarg@cpan.org>
265 bluefeet - Aran Deltac (cpan:BLUEFEET) <bluefeet@gmail.com>
267 ether - Karen Etheridge (cpan:ETHER) <ether@cpan.org>
269 dolmen - Olivier Mengué (cpan:DOLMEN) <dolmen@cpan.org>
271 alexbio - Alessandro Ghedini (cpan:ALEXBIO) <alexbio@cpan.org>
273 getty - Torsten Raudssus (cpan:GETTY) <torsten@raudss.us>
275 arcanez - Justin Hunter (cpan:ARCANEZ) <justin.d.hunter@gmail.com>
277 kanashiro - Lucas Kanashiro (cpan:KANASHIRO)
279 <kanashiro.duarte@gmail.com>
280 djerius - Diab Jerius (cpan:DJERIUS) <djerius@cfa.harvard.edu>
282
284 Copyright (c) 2010-2016 the Sub::Quote "AUTHOR" and "CONTRIBUTORS" as
285 listed above.
286
288 This library is free software and may be distributed under the same
289 terms as perl itself. See <http://dev.perl.org/licenses/>.
290perl v5.30.0 2019-10-02 Sub::Quote(3)