local-lib5/man/man3/Context::Preserve.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Context::Preserve 3"
 127 .TH Context::Preserve 3 "2008-01-15" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Context::Preserve \- run code after a subroutine call, preserving the context the subroutine would have seen if it were the last statement in the caller
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 Have you ever written this?
 137 .PP
 138 .Vb 1
 139 \&    my ($result, @result);
 140 \&
 141 \&    # run a sub in the correct context
 142 \&    if(!defined wantarray){
 143 \&        some::code();
 144 \&    }
 145 \&    elsif(wantarray){
 146 \&        @result = some::code();
 147 \&    }
 148 \&    else {
 149 \&        $result = some::code();
 150 \&    }
 151 \&
 152 \&    # do something after some::code
 153 \&    $_ += 42 for (@result, $result);
 154 \&
 155 \&    # finally return the correct value
 156 \&    if(!defined wantarray){
 157 \&        return;
 158 \&    }
 159 \&    elsif(wantarray){
 160 \&        return @result;
 161 \&    }
 162 \&    else {
 163 \&        return $result;
 164 \&    }
 165 .Ve
 166 .PP
 167 Now you can just write this instead:
 168 .PP
 169 .Vb 1
 170 \&  use Context::Preserve;
 171 \&
 172 \&  return preserve_context { some::code() }
 173 \&             after => sub { $_ += 42 for @_ };
 174 .Ve
 175 .SH "DESCRIPTION"
 176 .IX Header "DESCRIPTION"
 177 Sometimes you need to call a function, get the results, act on the
 178 results, then return the result of the function.  This is painful
 179 because of contexts; the original function can behave different if
 180 it's called in void, scalar, or list context.  You can ignore the
 181 various cases and just pick one, but that's fragile.  To do things
 182 right, you need to see which case you're being called in, and then
 183 call the function in that context.  This results in 3 code paths,
 184 which is a pain to type in (and maintain).
 185 .PP
 186 This module automates the process.  You provide a coderef that is the
 187 \&\*(L"original function\*(R", and another coderef to run after the original
 188 runs.  You can modify the return value (aliased to \f(CW@_\fR) here, and do
 189 whatever else you need to do.  \f(CW\*(C`wantarray\*(C'\fR is correct inside both
 190 coderefs; in \*(L"after\*(R", though, the return value is ignored and the
 191 value \f(CW\*(C`wantarray\*(C'\fR returns is related to the context that the original
 192 function was called in.
 193 .SH "EXPORT"
 194 .IX Header "EXPORT"
 195 \&\f(CW\*(C`preserve_context\*(C'\fR
 196 .SH "FUNCTIONS"
 197 .IX Header "FUNCTIONS"
 198 .SS "preserve_context { original } [after|replace] => sub { after }"
 199 .IX Subsection "preserve_context { original } [after|replace] => sub { after }"
 200 Invokes \f(CW\*(C`original\*(C'\fR in the same context as \f(CW\*(C`preserve_context\*(C'\fR was
 201 called in, save the results, runs \f(CW\*(C`after\*(C'\fR in the same context, then
 202 returns the result of \f(CW\*(C`original\*(C'\fR (or \f(CW\*(C`after\*(C'\fR if \f(CW\*(C`replace\*(C'\fR is used).
 203 .PP
 204 If the second argument is \f(CW\*(C`after\*(C'\fR, then you can modify \f(CW@_\fR to
 205 affect the return value.  \f(CW\*(C`after\*(C'\fR's return value is ignored.
 206 .PP
 207 If the second argument is \f(CW\*(C`replace\*(C'\fR, then modifying \f(CW@_\fR doesn't do
 208 anything.  The return value of \f(CW\*(C`after\*(C'\fR is returned from
 209 \&\f(CW\*(C`preserve_context\*(C'\fR instead.
 210 .PP
 211 Run \f(CW\*(C`preserve_context\*(C'\fR like this:
 212 .PP
 213 .Vb 5
 214 \&  sub whatever {
 215 \&      ...
 216 \&      return preserve_context { orginal_function() }
 217 \&                 after => sub { modify @_          };
 218 \&  }
 219 \&
 220 \&  or
 221 \&
 222 \&  sub whatever {
 223 \&      ...
 224 \&      return preserve_context   { orginal_function() }
 225 \&                 replace => sub { return @new_return };
 226 \&  }
 227 .Ve
 228 .PP
 229 Note that there's no comma between the first block and the \f(CW\*(C`after
 230 =>\*(C'\fR part.  This is how perl parses functions with the \f(CW\*(C`(&@)\*(C'\fR
 231 prototype.  The alternative is to say:
 232 .PP
 233 .Vb 1
 234 \&      preserve_context(sub { original }, after => sub { after });
 235 .Ve
 236 .PP
 237 You can pick the one you like, but I think the first version is much
 238 prettier.
 239 .SH "AUTHOR AND COPYRIGHT"
 240 .IX Header "AUTHOR AND COPYRIGHT"
 241 Jonathan Rockway \f(CW\*(C`<jrockway@cpan.org>\*(C'\fR
 242 .PP
 243 Copyright (c) 2008 Infinity Interactive.  You may redistribute this
 244 module under the same terms as Perl itself.