Initial Commit

database/perl/vendor/lib/Scope/Guard.pm

@@ -0,0 +1,183 @@
+package Scope::Guard;
+
+use strict;
+use warnings;
+
+use Carp qw(confess);
+use Exporter ();
+
+our @ISA = qw(Exporter);
+our @EXPORT_OK = qw(guard scope_guard);
+our $VERSION = '0.21';
+
+sub new {
+    confess "Can't create a Scope::Guard in void context" unless (defined wantarray);
+
+    my $class = shift;
+    my $handler = shift() || die 'Scope::Guard::new: no handler supplied';
+    my $ref = ref $handler || '';
+
+    die "Scope::Guard::new: invalid handler - expected CODE ref, got: '$ref'"
+        unless ref($handler) eq 'CODE';
+
+    bless [ 0, $handler ], ref $class || $class;
+}
+
+sub dismiss {
+    my $self = shift;
+    my $dismiss = @_ ? shift : 1;
+
+    $self->[0] = $dismiss;
+}
+
+sub guard(&) { __PACKAGE__->new(shift) }
+sub scope_guard($) { __PACKAGE__->new(shift) }
+
+sub DESTROY {
+    my $self = shift;
+    my ($dismiss, $handler) = @$self;
+
+    $handler->() unless ($dismiss);
+}
+
+1;
+
+__END__
+
+=pod
+
+=head1 NAME
+
+Scope::Guard - lexically-scoped resource management
+
+=head1 SYNOPSIS
+
+    my $guard = guard { ... };
+
+      # or
+
+    my $guard = scope_guard \&handler;
+
+      # or
+
+    my $guard = Scope::Guard->new(sub { ... });
+
+    $guard->dismiss(); # disable the handler
+
+=head1 DESCRIPTION
+
+This module provides a convenient way to perform cleanup or other forms of resource
+management at the end of a scope. It is particularly useful when dealing with exceptions:
+the C<Scope::Guard> constructor takes a reference to a subroutine that is guaranteed to
+be called even if the thread of execution is aborted prematurely. This effectively allows
+lexically-scoped "promises" to be made that are automatically honoured by perl's garbage
+collector.
+
+For more information, see: L<http://www.drdobbs.com/cpp/184403758>
+
+=head1 METHODS
+
+=head2 new
+
+    my $guard = Scope::Guard->new(sub { ... });
+
+      # or
+
+    my $guard = Scope::Guard->new(\&handler);
+
+The C<new> method creates a new C<Scope::Guard> object which calls the supplied handler when its C<DESTROY> method is
+called, typically at the end of the scope.
+
+=head2 dismiss
+
+    $guard->dismiss();
+
+      # or
+
+    $guard->dismiss(1);
+
+C<dismiss> detaches the handler from the C<Scope::Guard> object. This revokes the "promise" to call the
+handler when the object is destroyed.
+
+The handler can be re-enabled by calling:
+
+    $guard->dismiss(0);
+
+=head1 EXPORTS
+
+=head2 guard
+
+C<guard> takes a block and returns a new C<Scope::Guard> object. It can be used
+as a shorthand for:
+
+    Scope::Guard->new(...)
+
+e.g.
+
+    my $guard = guard { ... };
+
+Note: calling C<guard> anonymously, i.e. in void context, will raise an exception.
+This is because anonymous guards are destroyed B<immediately>
+(rather than at the end of the scope), which is unlikely to be the desired behaviour.
+
+=head2 scope_guard
+
+C<scope_guard> is the same as C<guard>, but it takes a code ref rather than a block.
+e.g.
+
+    my $guard = scope_guard \&handler;
+
+or:
+
+    my $guard = scope_guard sub { ... };
+
+or:
+
+    my $guard = scope_guard $handler;
+
+As with C<guard>, calling C<scope_guard> in void context will raise an exception.
+
+=head1 VERSION
+
+0.21
+
+=head1 SEE ALSO
+
+=over
+
+=item * L<B::Hooks::EndOfScope|B::Hooks::EndOfScope>
+
+=item * L<End|End>
+
+=item * L<Guard|Guard>
+
+=item * L<Hook::Scope|Hook::Scope>
+
+=item * L<Object::Destroyer|Object::Destroyer>
+
+=item * L<Perl::AtEndOfScope|Perl::AtEndOfScope>
+
+=item * L<ReleaseAction|ReleaseAction>
+
+=item * L<Scope::local_OnExit|Scope::local_OnExit>
+
+=item * L<Scope::OnExit|Scope::OnExit>
+
+=item * L<Sub::ScopeFinalizer|Sub::ScopeFinalizer>
+
+=item * L<Value::Canary|Value::Canary>
+
+=back
+
+=head1 AUTHOR
+
+chocolateboy <chocolate@cpan.org>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2005-2015, chocolateboy.
+
+This module is free software. It may be used, redistributed and/or modified under the same terms
+as Perl itself.
+
+=cut