lib/Variable/Temp.pm

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