This is 0.02

[perl/modules/Variable-Temp.git] / README

diff --git a/README b/README
index 276fff64e1bf5e32e24f521615584c455dd658ad..df6d397b38485d7c224267056910d809cdce36a3 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Variable::Temp - Temporarily change the value of a variable.
 
 VERSION
-    Version 0.01
+    Version 0.02
 
 SYNOPSIS
         use Variable::Temp 'temp';
@@ -17,43 +17,68 @@ SYNOPSIS
 
 DESCRIPTION
     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. It is
-    similar to "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.
+    change the value of a scalar, array or hash variable, until the end of
+    the current scope is reached where the original value of the variable is
+    restored. It is similar to "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.
 
 FUNCTIONS
   "temp"
         temp $var;
         temp $var = $value;
 
-    Temporarily replace the value of the lexical or global variable $var by
-    $value, or by "undef" if $value is omitted, until the end of the current
-    scope. Any subsequent assignments to $var in the current (or any
-    inferior) scope will not affect the original value which will be
-    restored into the variable at scope end. Several "temp" calls can be
-    made onto the same variable, and the restore are processed in reverse
-    order.
+        temp @var;
+        temp @var = \@value;
 
-    Note that destructors associated with $var will not be called when
-    "temp" sets the temporary value, but only at the natural end of life of
-    the variable (i.e. at the end of the scope). They will trigger after any
-    destructor associated with the replacement $var.
+        temp %var;
+        temp %var = \%value;
 
-EXPORT
-    The function "temp" is only exported on request by passing 'temp' to the
-    module import list.
+    Temporarily replaces the value of the lexical or global variable $var by
+    $value (respectively @var by @value, %var by %value), or by "undef" if
+    $value is omitted (respectively empties @var and %var if the second
+    argument is omitted), until the end of the current scope. Any subsequent
+    assignments to this variable in the current (or any inferior) scope will
+    not affect the original value which will be restored into the variable
+    at scope end. Several "temp" calls can be made onto the same variable,
+    and the restore are processed in reverse order.
+
+    Note that destructors associated with the variable will not be called
+    when "temp" sets the temporary value, but only at the natural end of
+    life of the variable. They will trigger after any destructor associated
+    with the replacement value.
+
+    Due to a shortcoming in the handling of the "\$" prototype, which was
+    addressed in "perl" 5.14, the pseudo-statement "temp $var = $value" will
+    cause compilation errors on "perl" 5.12.x and below. If you want your
+    code to run on these versions of "perl", you are encouraged to use
+    "set_temp" instead.
+
+  "set_temp"
+        set_temp $var;
+        set_temp $var => $value;
+
+        set_temp @var;
+        set_temp @var => \@value;
+
+        set_temp %var;
+        set_temp %var => \%value;
 
-CAVEATS
-    Currently only applies to scalar variables.
+    A non-lvalue variant of "temp" that can be used with any version of
+    "perl".
+
+EXPORT
+    The functions "temp" and "set_temp" are only exported on request by
+    specifying their names in the module import list.
 
 DEPENDENCIES
     perl 5.6.
 
+    Exporter (core since perl 5).
+
     Scope::Upper.
 
-    Exporter (core since perl 5).
+    Variable::Magic 0.51.
 
 SEE ALSO
     Scope::Upper.