.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Sub::Quote 3pm"
.TH Sub::Quote 3pm "2012-06-26" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Sub::Quote \- efficient generation of subroutines via string eval
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& package Silly;
\&
\& use Sub::Quote qw(quote_sub unquote_sub quoted_from_sub);
\&
\& quote_sub \*(AqSilly::kitty\*(Aq, q{ print "meow" };
\&
\& quote_sub \*(AqSilly::doggy\*(Aq, q{ print "woof" };
\&
\& my $sound = 0;
\&
\& quote_sub \*(AqSilly::dagron\*(Aq,
\&   q{ print ++$sound % 2 ? \*(Aqburninate\*(Aq : \*(Aqroar\*(Aq },
\&   { \*(Aq$sound\*(Aq => \e$sound };
.Ve
.PP
And elsewhere:
.PP
.Vb 5
\& Silly\->kitty;  # meow
\& Silly\->doggy;  # woof
\& Silly\->dagron; # burninate
\& Silly\->dagron; # roar
\& Silly\->dagron; # burninate
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package provides performant ways to generate subroutines from strings.
.SH "SUBROUTINES"
.IX Header "SUBROUTINES"
.SS "quote_sub"
.IX Subsection "quote_sub"
.Vb 1
\& my $coderef = quote_sub \*(AqFoo::bar\*(Aq, q{ print $x++ . "\en" }, { \*(Aq$x\*(Aq => \e0 };
.Ve
.PP
Arguments: ?$name, \f(CW$code\fR, ?\e%captures, ?\e%options
.PP
\&\f(CW$name\fR is the subroutine where the coderef will be installed.
.PP
\&\f(CW$code\fR is a string that will be turned into code.
.PP
\&\f(CW\*(C`\e%captures\*(C'\fR is a hashref of variables that will be made available to the
code.  See the \*(L"\s-1SYNOPSIS\s0\*(R"'s \f(CW\*(C`Silly::dagron\*(C'\fR for an example using captures.
.PP
\fIoptions\fR
.IX Subsection "options"
.IP "\(bu" 2
no_install
.Sp
\&\fBBoolean\fR.  Set this option to not install the generated coderef into the
passed subroutine name on undefer.
.SS "unquote_sub"
.IX Subsection "unquote_sub"
.Vb 1
\& my $coderef = unquote_sub $sub;
.Ve
.PP
Forcibly replace subroutine with actual code.  Note that for performance
reasons all quoted subs declared so far will be globally unquoted/parsed in
a single eval. This means that if you have a syntax error in one of your
quoted subs you may find out when some other sub is unquoted.
.PP
If \f(CW$sub\fR is not a quoted sub, this is a no-op.
.SS "quoted_from_sub"
.IX Subsection "quoted_from_sub"
.Vb 1
\& my $data = quoted_from_sub $sub;
\&
\& my ($name, $code, $captures, $compiled_sub) = @$data;
.Ve
.PP
Returns original arguments to quote_sub, plus the compiled version if this
sub has already been unquoted.
.PP
Note that \f(CW$sub\fR can be either the original quoted version or the compiled
version for convenience.
.SS "inlinify"
.IX Subsection "inlinify"
.Vb 4
\& my $prelude = capture_unroll {
\&   \*(Aq$x\*(Aq => 1,
\&   \*(Aq$y\*(Aq => 2,
\& };
\&
\& my $inlined_code = inlinify q{
\&   my ($x, $y) = @_;
\&
\&   print $x + $y . "\en";
\& }, \*(Aq$x, $y\*(Aq, $prelude;
.Ve
.PP
Takes a string of code, a string of arguments, a string of code which acts as a
\&\*(L"prelude\*(R", and a \fBBoolean\fR representing whether or not to localize the
arguments.
.SS "capture_unroll"
.IX Subsection "capture_unroll"
.Vb 4
\& my $prelude = capture_unroll {
\&   \*(Aq$x\*(Aq => 1,
\&   \*(Aq$y\*(Aq => 2,
\& };
.Ve
.PP
Generates a snippet of code which is suitable to be used as a prelude for
\&\*(L"inlinify\*(R".  The keys are the names of the variables and the values are (duh)
the values.  Note that references work as values.
.SH "CAVEATS"
.IX Header "CAVEATS"
Much of this is just string-based code-generation, and as a result, a few caveats
apply.
.SS "return"
.IX Subsection "return"
Calling \f(CW\*(C`return\*(C'\fR from a quote_sub'ed sub will not likely do what you intend.
Instead of returning from the code you defined in \f(CW\*(C`quote_sub\*(C'\fR, it will return
from the overall function it is composited into.
.PP
So when you pass in:
.PP
.Vb 1
\&   quote_sub q{  return 1 if $condition; $morecode }
.Ve
.PP
It might turn up in the intended context as follows:
.PP
.Vb 1
\&  sub foo {
\&
\&    <important code a>
\&    do {
\&      return 1 if $condition;
\&      $morecode
\&    };
\&    <important code b>
\&
\&  }
.Ve
.PP
Which will obviously return from foo, when all you meant to do was return from
the code context in quote_sub and proceed with running important code b.