1Sub::Quote(3)         User Contributed Perl Documentation        Sub::Quote(3)
2
3
4

NAME

6       Sub::Quote - Efficient generation of subroutines via string eval
7

SYNOPSIS

9        package Silly;
10
11        use Sub::Quote qw(quote_sub unquote_sub quoted_from_sub);
12
13        quote_sub 'Silly::kitty', q{ print "meow" };
14
15        quote_sub 'Silly::doggy', q{ print "woof" };
16
17        my $sound = 0;
18
19        quote_sub 'Silly::dagron',
20          q{ print ++$sound % 2 ? 'burninate' : 'roar' },
21          { '$sound' => \$sound };
22
23       And elsewhere:
24
25        Silly->kitty;  # meow
26        Silly->doggy;  # woof
27        Silly->dagron; # burninate
28        Silly->dagron; # roar
29        Silly->dagron; # burninate
30

DESCRIPTION

32       This package provides performant ways to generate subroutines from
33       strings.
34

SUBROUTINES

36   quote_sub
37        my $coderef = quote_sub 'Foo::bar', q{ print $x++ . "\n" }, { '$x' => \0 };
38
39       Arguments: ?$name, $code, ?\%captures, ?\%options
40
41       $name is the subroutine where the coderef will be installed.
42
43       $code is a string that will be turned into code.
44
45       "\%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
51       Exported by default.
52
53       options
54
55       "no_install"
56         Boolean.  Set this option to not install the generated coderef into
57         the passed subroutine name on undefer.
58
59       "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
65       "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
69       "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
74       "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
79       "%^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
84       "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
90       "file"
91         The apparent filename to use for the code being evaluated.
92
93       "line"
94         The apparent line number to use for the code being evaluated.
95
96   unquote_sub
97        my $coderef = unquote_sub $sub;
98
99       Forcibly replace subroutine with actual code.
100
101       If $sub is not a quoted sub, this is a no-op.
102
103       Exported by default.
104
105   quoted_from_sub
106        my $data = quoted_from_sub $sub;
107
108        my ($name, $code, $captures, $compiled_sub) = @$data;
109
110       Returns original arguments to quote_sub, plus the compiled version if
111       this sub has already been unquoted.
112
113       Note that $sub can be either the original quoted version or the
114       compiled version for convenience.
115
116       Exported by default.
117
118   inlinify
119        my $prelude = capture_unroll '$captures', {
120          '$x' => 1,
121          '$y' => 2,
122        }, 4;
123
124        my $inlined_code = inlinify q{
125          my ($x, $y) = @_;
126
127          print $x + $y . "\n";
128        }, '$x, $y', $prelude;
129
130       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
134   quotify
135        my $quoted_value = quotify $value;
136
137       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
145   capture_unroll
146        my $prelude = capture_unroll '$captures', {
147          '$x' => 1,
148          '$y' => 2,
149        }, 4;
150
151       Arguments: $from, \%captures, $indent
152
153       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
159   qsub
160        my $hash = {
161         coderef => qsub q{ print "hello"; },
162         other   => 5,
163        };
164
165       Arguments: $code
166
167       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
171       Exported by default.
172
173   sanitize_identifier
174        my $var_name = '$variable_for_' . sanitize_identifier('@name');
175        quote_sub qq{ print \$${var_name} }, { $var_name => \$value };
176
177       Arguments: $identifier
178
179       Sanitizes a value so that it can be used in an identifier.
180

ENVIRONMENT

182   SUB_QUOTE_DEBUG
183       Causes code to be output to "STDERR" before being evaled.  Several
184       forms are supported:
185
186       1   All subs will be output.
187
188       "/foo/"
189           Subs will be output if their code matches the given regular
190           expression.
191
192       "simple_identifier"
193           Any sub with the given name will be output.
194
195       "Full::identifier"
196           A sub matching the full name will be output.
197
198       "Package::Name::"
199           Any sub in the given package (including anonymous subs) will be
200           output.
201

CAVEATS

203       Much of this is just string-based code-generation, and as a result, a
204       few caveats apply.
205
206   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
211       So when you pass in:
212
213          quote_sub q{  return 1 if $condition; $morecode }
214
215       It might turn up in the intended context as follows:
216
217         sub foo {
218
219           <important code a>
220           do {
221             return 1 if $condition;
222             $morecode
223           };
224           <important code b>
225
226         }
227
228       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
232   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

SUPPORT

240       Users' IRC: #moose on irc.perl.org
241
242       Development and contribution IRC: #web-simple on irc.perl.org
243
244       Bugtracker:
245       <https://rt.cpan.org/Public/Dist/Display.html?Name=Sub-Quote>
246
247       Git repository: <git://github.com/moose/Sub-Quote.git>
248
249       Git browser: <https://github.com/moose/Sub-Quote>
250

AUTHOR

252       mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
253

CONTRIBUTORS

255       frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com>
256
257       ribasushi - Peter Rabbitson (cpan:RIBASUSHI) <ribasushi@cpan.org>
258
259       Mithaldu - Christian Walde (cpan:MITHALDU)
260       <walde.christian@googlemail.com>
261
262       tobyink - Toby Inkster (cpan:TOBYINK) <tobyink@cpan.org>
263
264       haarg - Graham Knop (cpan:HAARG) <haarg@cpan.org>
265
266       bluefeet - Aran Deltac (cpan:BLUEFEET) <bluefeet@gmail.com>
267
268       ether - Karen Etheridge (cpan:ETHER) <ether@cpan.org>
269
270       dolmen - Olivier Mengué (cpan:DOLMEN) <dolmen@cpan.org>
271
272       alexbio - Alessandro Ghedini (cpan:ALEXBIO) <alexbio@cpan.org>
273
274       getty - Torsten Raudssus (cpan:GETTY) <torsten@raudss.us>
275
276       arcanez - Justin Hunter (cpan:ARCANEZ) <justin.d.hunter@gmail.com>
277
278       kanashiro - Lucas Kanashiro (cpan:KANASHIRO)
279       <kanashiro.duarte@gmail.com>
280
281       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

LICENSE

288       This library is free software and may be distributed under the same
289       terms as perl itself. See <http://dev.perl.org/licenses/>.
290
291
292
293perl v5.30.1                      2020-01-30                     Sub::Quote(3)
Impressum