--- Guard/Guard.pm	2008/12/13 17:49:12	1.2
+++ Guard/Guard.pm	2008/12/13 18:42:45	1.5
@@ -6,6 +6,15 @@
 
  use Guard;
 
+ # temporarily chdir to "/etc" directory, but make sure
+ # to go back to "/" no matter how myfun exits:
+ sub dosomething {
+    scope_guard { chdir "/" };
+    chdir "/etc";
+
+    call_function_that_might_die_or_other_fun_stuff;
+ }
+
 =head1 DESCRIPTION
 
 This module implements so-called "guards". A guard is something (usually
@@ -28,9 +37,9 @@
 package Guard;
 
 BEGIN {
-   $VERSION = '0.01';
+   $VERSION = '0.1';
    @ISA = qw(Exporter);
-   @EXPORT = qw(guard scope_guard cancel);
+   @EXPORT = qw(guard scope_guard);
 
    require Exporter;
 
@@ -62,17 +71,29 @@
 Except it is much faster, and the whole thing gets executed even when the
 BLOCK calls C<exit>, C<goto>, C<last> or escapes via other means.
 
+If multiple BLOCKs are registered to the same scope, they will be executed
+in reverse order. Stuff like C<local> is managed via the same mechanism,
+so variables C<local>ised after calling C<scope_guard> will be restored
+when the guard runs.
+
 See B<EXCEPTIONS>, below, for an explanation of exception handling
 (C<die>) within guard blocks.
 
-Example: Temporarily change the directory to F</etc> and make sure it's
-set back to F</> when the function returns:
+Example: temporarily change the timezone for the current process,
+ensuring it will be reset when the C<if> scope is exited:
+
+   use Guard;
+   use POSIX ();
+
+   if ($need_to_switch_tz) {
+      # make sure we call tzset after $ENV{TZ} has been restored
+      scope_guard { POSIX::tzset };
 
-   sub dosomething {
-      scope_guard { chdir "/" };
-      chdir "/etc";
+      # localise after the scope_guard, so it gets undone in time
+      local $ENV{TZ} = "Europe/London";
+      POSIX::tzset;
 
-      ...
+      # do something with the new timezone
    }
 
 =item my $guard = guard BLOCK
@@ -130,7 +151,7 @@
 
 =head1 EXCEPTIONS
 
-Guard blocks should not normally throw exceptions (e.g. C<die>), after
+Guard blocks should not normally throw exceptions (that is, C<die>). After
 all, they are usually used to clean up after such exceptions. However, if
 something truly exceptional is happening, a guard block should be allowed
 to die. Also, programming errors are a large source of exceptions, and the