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 =cut
  59
  60 sub temp (\$) :lvalue {
  61  my $var  = $_[0];
  62  my $save = $$var;
  63  &Scope::Upper::reap(sub { $$var = $save } => Scope::Upper::UP);
  64  $$var;
  65 }
  66
  67 =head1 EXPORT
  68
  69 The function L</temp> is only exported on request by passing C<'temp'> to the module import list.
  70
  71 =cut
  72
  73 use base 'Exporter';
  74
  75 our @EXPORT      = ();
  76 our %EXPORT_TAGS = ();
  77 our @EXPORT_OK   = 'temp';
  78
  79 =head1 CAVEATS
  80
  81 Currently only applies to scalar variables.
  82
  83 =head1 DEPENDENCIES
  84
  85 L<perl> 5.6.
  86
  87 L<Scope::Upper>.
  88
  89 L<Exporter> (core since perl 5).
  90
  91 =head1 SEE ALSO
  92
  93 L<Scope::Upper>.
  94
  95 L<perlfunc/local>.
  96
  97 =head1 AUTHOR
  98
  99 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 100
 101 You can contact me by mail or on C<irc.perl.org> (vincent).
 102
 103 =head1 BUGS
 104
 105 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>.
 106 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
 107
 108 =head1 SUPPORT
 109
 110 You can find documentation for this module with the perldoc command.
 111
 112     perldoc Variable::Temp
 113
 114 =head1 COPYRIGHT & LICENSE
 115
 116 Copyright 2015 Vincent Pit, all rights reserved.
 117
 118 This program is free software; you can redistribute it and/or modify it
 119 under the same terms as Perl itself.
 120
 121 =cut
 122
 123 1; # End of Variable::Temp