README

   1 NAME
   2     Variable::Temp - Temporarily change the value of a variable.
   3
   4 VERSION
   5     Version 0.02
   6
   7 SYNOPSIS
   8         use Variable::Temp 'temp';
   9
  10         my $x = 1;
  11         say $x; # 1
  12         {
  13          temp $x = 2;
  14          say $x; # 2
  15         }
  16         say $x; # 1
  17
  18 DESCRIPTION
  19     This module provides an utility routine that can be used to temporarily
  20     change the value of a scalar, array or hash variable, until the end of
  21     the current scope is reached where the original value of the variable is
  22     restored. It is similar to "local", except that it can be applied onto
  23     lexicals as well as globals, and that it replaces values by copying the
  24     new value into the container variable instead of by aliasing.
  25
  26 FUNCTIONS
  27   "temp"
  28         temp $var;
  29         temp $var = $value;
  30
  31         temp @var;
  32         temp @var = \@value;
  33
  34         temp %var;
  35         temp %var = \%value;
  36
  37     Temporarily replaces the value of the lexical or global variable $var by
  38     $value (respectively @var by @value, %var by %value), or by "undef" if
  39     $value is omitted (respectively empties @var and %var if the second
  40     argument is omitted), until the end of the current scope. Any subsequent
  41     assignments to this variable in the current (or any inferior) scope will
  42     not affect the original value which will be restored into the variable
  43     at scope end. Several "temp" calls can be made onto the same variable,
  44     and the restore are processed in reverse order.
  45
  46     Note that destructors associated with the variable will not be called
  47     when "temp" sets the temporary value, but only at the natural end of
  48     life of the variable. They will trigger after any destructor associated
  49     with the replacement value.
  50
  51     Due to a shortcoming in the handling of the "\$" prototype, which was
  52     addressed in "perl" 5.14, the pseudo-statement "temp $var = $value" will
  53     cause compilation errors on "perl" 5.12.x and below. If you want your
  54     code to run on these versions of "perl", you are encouraged to use
  55     "set_temp" instead.
  56
  57   "set_temp"
  58         set_temp $var;
  59         set_temp $var => $value;
  60
  61         set_temp @var;
  62         set_temp @var => \@value;
  63
  64         set_temp %var;
  65         set_temp %var => \%value;
  66
  67     A non-lvalue variant of "temp" that can be used with any version of
  68     "perl".
  69
  70 EXPORT
  71     The functions "temp" and "set_temp" are only exported on request by
  72     specifying their names in the module import list.
  73
  74 DEPENDENCIES
  75     perl 5.6.
  76
  77     Exporter (core since perl 5).
  78
  79     Scope::Upper.
  80
  81     Variable::Magic 0.51.
  82
  83 SEE ALSO
  84     Scope::Upper.
  85
  86     "local" in perlfunc.
  87
  88 AUTHOR
  89     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
  90
  91     You can contact me by mail or on "irc.perl.org" (vincent).
  92
  93 BUGS
  94     Please report any bugs or feature requests to "bug-variable-temp at
  95     rt.cpan.org", or through the web interface at
  96     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Variable-Temp>. I will
  97     be notified, and then you'll automatically be notified of progress on
  98     your bug as I make changes.
  99
 100 SUPPORT
 101     You can find documentation for this module with the perldoc command.
 102
 103         perldoc Variable::Temp
 104
 105 COPYRIGHT & LICENSE
 106     Copyright 2015 Vincent Pit, all rights reserved.
 107
 108     This program is free software; you can redistribute it and/or modify it
 109     under the same terms as Perl itself.
 110