From: Matt S Trout Date: Sun, 8 Apr 2012 17:06:36 +0000 (+0000) Subject: first two (very boring) tests from Role::Basic X-Git-Tag: v1.000_900~14 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=8e50c419f75a6f8fac819d79c64a8abe17c8e1f1;p=gitmo%2FRole-Tiny.git first two (very boring) tests from Role::Basic --- diff --git a/Changes b/Changes index a107a71..7fd33b1 100644 --- a/Changes +++ b/Changes @@ -1,3 +1,4 @@ +1.000001 - 2012-04-03 - Document that Class::Method::Modifiers must be depended on separately - Update tests so that they skip correctly without C::M::M - Add a SEE ALSO section diff --git a/t/role-basic/00-load.t b/t/role-basic/00-load.t new file mode 100644 index 0000000..a93a7cf --- /dev/null +++ b/t/role-basic/00-load.t @@ -0,0 +1,7 @@ +use Test::More tests => 1; + +BEGIN { + use_ok( 'Role::Tiny::Restricted' ) || BAIL_OUT "Could not load Role::Tiny::Restricted: $!"; +} + +diag( "Testing Role::Tiny::Restricted $Role::Tiny::Restricted::VERSION, Perl $], $^X" ); diff --git a/t/role-basic/basic.t b/t/role-basic/basic.t new file mode 100644 index 0000000..9230841 --- /dev/null +++ b/t/role-basic/basic.t @@ -0,0 +1,9 @@ +#!/usr/bin/env perl + +use Test::More tests => 3; +use lib 'lib', 't/role-basic/lib'; + +use_ok 'My::Example' or BAIL_OUT 'Could not load test module My::Example'; +can_ok 'My::Example', 'no_conflict'; +is +My::Example->no_conflict, 'My::Does::Basic::no_conflict', + '... and it should return the correct value'; diff --git a/t/role-basic/lib/My/Does/Basic.pm b/t/role-basic/lib/My/Does/Basic.pm new file mode 100644 index 0000000..f3d12de --- /dev/null +++ b/t/role-basic/lib/My/Does/Basic.pm @@ -0,0 +1,11 @@ +package My::Does::Basic; + +use Role::Tiny::Restricted; + +requires 'turbo_charger'; + +sub no_conflict { + return "My::Does::Basic::no_conflict"; +} + +1; diff --git a/t/role-basic/lib/My/Example.pm b/t/role-basic/lib/My/Example.pm new file mode 100644 index 0000000..e6668e1 --- /dev/null +++ b/t/role-basic/lib/My/Example.pm @@ -0,0 +1,13 @@ +package My::Example; + +use Role::Tiny::Restricted 'with'; + +with 'My::Does::Basic'; + +sub new { bless {} => shift } + +sub turbo_charger {} +$My::Example::foo = 1; +sub foo() {} + +1; diff --git a/t/role-basic/lib/MyTests.pm b/t/role-basic/lib/MyTests.pm new file mode 100644 index 0000000..3f95440 --- /dev/null +++ b/t/role-basic/lib/MyTests.pm @@ -0,0 +1,42 @@ +package MyTests; + +use strict; +use warnings; + +use Test::More (); +use Try::Tiny; + +sub import { + my $class = shift; + my $caller = caller; + + no strict 'refs'; + *{"${caller}::exception"} = \&exception; + local $" = ", "; + use Data::Dumper; + $Data::Dumper::Terse = 1; + @_ = Dumper(@_); + eval <<" END"; + package $caller; + no strict; + use Test::More @_; + END + die $@ if $@; +} + +sub exception (&) { + my ($code) = @_; + + return try { + $code->(); + return undef; + } + catch { + return $_ if $_; + + my $problem = defined $_ ? 'false' : 'undef'; + Carp::confess("$problem exception caught by Test::Fatal::exception"); + }; +} + +1; diff --git a/t/role-basic/lib/TestMethods.pm b/t/role-basic/lib/TestMethods.pm new file mode 100644 index 0000000..e932be3 --- /dev/null +++ b/t/role-basic/lib/TestMethods.pm @@ -0,0 +1,23 @@ +package TestMethods; + +use strict; +use warnings; + +sub import { + my ( $class, @methods ) = @_; + my $target = caller; + + foreach my $method (@methods) { + my $fq_method = $target . "::$method"; + no strict 'refs'; + *$fq_method = sub { + local *__ANON__ = "__ANON__$fq_method"; + my $self = shift; + return $self->{$method} unless @_; + $self->{$method} = shift; + return $self; + }; + } +} + +1; diff --git a/t/role-basic/lib/Try/Tiny.pm b/t/role-basic/lib/Try/Tiny.pm new file mode 100644 index 0000000..67c30f3 --- /dev/null +++ b/t/role-basic/lib/Try/Tiny.pm @@ -0,0 +1,575 @@ +# PAUSE doesn't seem to case about this in t/role-basic/lib, but just in case ... +package # Hide from PAUSE + Try::Tiny; + +use strict; +#use warnings; + +use vars qw(@EXPORT @EXPORT_OK $VERSION @ISA); + +BEGIN { + require Exporter; + @ISA = qw(Exporter); +} + +$VERSION = "0.09"; + +$VERSION = eval $VERSION; + +@EXPORT = @EXPORT_OK = qw(try catch finally); + +$Carp::Internal{+__PACKAGE__}++; + +# Need to prototype as @ not $$ because of the way Perl evaluates the prototype. +# Keeping it at $$ means you only ever get 1 sub because we need to eval in a list +# context & not a scalar one + +sub try (&;@) { + my ( $try, @code_refs ) = @_; + + # we need to save this here, the eval block will be in scalar context due + # to $failed + my $wantarray = wantarray; + + my ( $catch, @finally ); + + # find labeled blocks in the argument list. + # catch and finally tag the blocks by blessing a scalar reference to them. + foreach my $code_ref (@code_refs) { + next unless $code_ref; + + my $ref = ref($code_ref); + + if ( $ref eq 'Try::Tiny::Catch' ) { + $catch = ${$code_ref}; + } elsif ( $ref eq 'Try::Tiny::Finally' ) { + push @finally, ${$code_ref}; + } else { + use Carp; + confess("Unknown code ref type given '${ref}'. Check your usage & try again"); + } + } + + # save the value of $@ so we can set $@ back to it in the beginning of the eval + my $prev_error = $@; + + my ( @ret, $error, $failed ); + + # FIXME consider using local $SIG{__DIE__} to accumulate all errors. It's + # not perfect, but we could provide a list of additional errors for + # $catch->(); + + { + # localize $@ to prevent clobbering of previous value by a successful + # eval. + local $@; + + # failed will be true if the eval dies, because 1 will not be returned + # from the eval body + $failed = not eval { + $@ = $prev_error; + + # evaluate the try block in the correct context + if ( $wantarray ) { + @ret = $try->(); + } elsif ( defined $wantarray ) { + $ret[0] = $try->(); + } else { + $try->(); + }; + + return 1; # properly set $fail to false + }; + + # copy $@ to $error; when we leave this scope, local $@ will revert $@ + # back to its previous value + $error = $@; + } + + # set up a scope guard to invoke the finally block at the end + my @guards = + map { Try::Tiny::ScopeGuard->_new($_, $failed ? $error : ()) } + @finally; + + # at this point $failed contains a true value if the eval died, even if some + # destructor overwrote $@ as the eval was unwinding. + if ( $failed ) { + # if we got an error, invoke the catch block. + if ( $catch ) { + # This works like given($error), but is backwards compatible and + # sets $_ in the dynamic scope for the body of C<$catch> + for ($error) { + return $catch->($error); + } + + # in case when() was used without an explicit return, the C + # loop will be aborted and there's no useful return value + } + + return; + } else { + # no failure, $@ is back to what it was, everything is fine + return $wantarray ? @ret : $ret[0]; + } +} + +sub catch (&;@) { + my ( $block, @rest ) = @_; + + return ( + bless(\$block, 'Try::Tiny::Catch'), + @rest, + ); +} + +sub finally (&;@) { + my ( $block, @rest ) = @_; + + return ( + bless(\$block, 'Try::Tiny::Finally'), + @rest, + ); +} + +{ + package # hide from PAUSE + Try::Tiny::ScopeGuard; + + sub _new { + shift; + bless [ @_ ]; + } + + sub DESTROY { + my @guts = @{ shift() }; + my $code = shift @guts; + $code->(@guts); + } +} + +__PACKAGE__ + +__END__ + +=pod + +=head1 NAME + +Try::Tiny - minimal try/catch with proper localization of $@ + +=head1 SYNOPSIS + + # handle errors with a catch handler + try { + die "foo"; + } catch { + warn "caught error: $_"; # not $@ + }; + + # just silence errors + try { + die "foo"; + }; + +=head1 DESCRIPTION + +This module provides bare bones C/C/C statements that are designed to +minimize common mistakes with eval blocks, and NOTHING else. + +This is unlike L which provides a nice syntax and avoids adding +another call stack layer, and supports calling C from the try block to +return from the parent subroutine. These extra features come at a cost of a few +dependencies, namely L and L which are +occasionally problematic, and the additional catch filtering uses L +type constraints which may not be desirable either. + +The main focus of this module is to provide simple and reliable error handling +for those having a hard time installing L, but who still want to +write correct C blocks without 5 lines of boilerplate each time. + +It's designed to work as correctly as possible in light of the various +pathological edge cases (see L) and to be compatible with any style +of error values (simple strings, references, objects, overloaded objects, etc). + +If the try block dies, it returns the value of the last statement executed in +the catch block, if there is one. Otherwise, it returns C in scalar +context or the empty list in list context. The following two examples both +assign C<"bar"> to C<$x>. + + my $x = try { die "foo" } catch { "bar" }; + + my $x = eval { die "foo" } || "bar"; + +You can add finally blocks making the following true. + + my $x; + try { die 'foo' } finally { $x = 'bar' }; + try { die 'foo' } catch { warn "Got a die: $_" } finally { $x = 'bar' }; + +Finally blocks are always executed making them suitable for cleanup code +which cannot be handled using local. You can add as many finally blocks to a +given try block as you like. + +=head1 EXPORTS + +All functions are exported by default using L. + +If you need to rename the C, C or C keyword consider using +L to get L's flexibility. + +=over 4 + +=item try (&;@) + +Takes one mandatory try subroutine, an optional catch subroutine & finally +subroutine. + +The mandatory subroutine is evaluated in the context of an C block. + +If no error occurred the value from the first block is returned, preserving +list/scalar context. + +If there was an error and the second subroutine was given it will be invoked +with the error in C<$_> (localized) and as that block's first and only +argument. + +C<$@> does B contain the error. Inside the C block it has the same +value it had before the C block was executed. + +Note that the error may be false, but if that happens the C block will +still be invoked. + +Once all execution is finished then the finally block if given will execute. + +=item catch (&;$) + +Intended to be used in the second argument position of C. + +Returns a reference to the subroutine it was given but blessed as +C which allows try to decode correctly what to do +with this code reference. + + catch { ... } + +Inside the catch block the caught error is stored in C<$_>, while previous +value of C<$@> is still available for use. This value may or may not be +meaningful depending on what happened before the C, but it might be a good +idea to preserve it in an error stack. + +For code that captures C<$@> when throwing new errors (i.e. +L), you'll need to do: + + local $@ = $_; + +=item finally (&;$) + + try { ... } + catch { ... } + finally { ... }; + +Or + + try { ... } + finally { ... }; + +Or even + + try { ... } + finally { ... } + catch { ... }; + +Intended to be the second or third element of C. Finally blocks are always +executed in the event of a successful C or if C is run. This allows +you to locate cleanup code which cannot be done via C e.g. closing a file +handle. + +When invoked, the finally block is passed the error that was caught. If no +error was caught, it is passed nothing. In other words, the following code +does just what you would expect: + + try { + die_sometimes(); + } catch { + # ...code run in case of error + } finally { + if (@_) { + print "The try block died with: @_\n"; + } else { + print "The try block ran without error.\n"; + } + }; + +B. C will +not do anything about handling possible errors coming from code located in these +blocks. + +In the same way C blesses the code reference this subroutine does the same +except it bless them as C. + +=back + +=head1 BACKGROUND + +There are a number of issues with C. + +=head2 Clobbering $@ + +When you run an eval block and it succeeds, C<$@> will be cleared, potentially +clobbering an error that is currently being caught. + +This causes action at a distance, clearing previous errors your caller may have +not yet handled. + +C<$@> must be properly localized before invoking C in order to avoid this +issue. + +More specifically, C<$@> is clobbered at the beginning of the C, which +also makes it impossible to capture the previous error before you die (for +instance when making exception objects with error stacks). + +For this reason C will actually set C<$@> to its previous value (before +the localization) in the beginning of the C block. + +=head2 Localizing $@ silently masks errors + +Inside an eval block C behaves sort of like: + + sub die { + $@ = $_[0]; + return_undef_from_eval(); + } + +This means that if you were polite and localized C<$@> you can't die in that +scope, or your error will be discarded (printing "Something's wrong" instead). + +The workaround is very ugly: + + my $error = do { + local $@; + eval { ... }; + $@; + }; + + ... + die $error; + +=head2 $@ might not be a true value + +This code is wrong: + + if ( $@ ) { + ... + } + +because due to the previous caveats it may have been unset. + +C<$@> could also be an overloaded error object that evaluates to false, but +that's asking for trouble anyway. + +The classic failure mode is: + + sub Object::DESTROY { + eval { ... } + } + + eval { + my $obj = Object->new; + + die "foo"; + }; + + if ( $@ ) { + + } + +In this case since C is not localizing C<$@> but still uses +C, it will set C<$@> to C<"">. + +The destructor is called when the stack is unwound, after C sets C<$@> to +C<"foo at Foo.pm line 42\n">, so by the time C is evaluated it has +been cleared by C in the destructor. + +The workaround for this is even uglier than the previous ones. Even though we +can't save the value of C<$@> from code that doesn't localize, we can at least +be sure the eval was aborted due to an error: + + my $failed = not eval { + ... + + return 1; + }; + +This is because an C that caught a C will always return a false +value. + +=head1 SHINY SYNTAX + +Using Perl 5.10 you can use L. + +The C block is invoked in a topicalizer context (like a C block), +but note that you can't return a useful value from C using the C +blocks without an explicit C. + +This is somewhat similar to Perl 6's C blocks. You can use it to +concisely match errors: + + try { + require Foo; + } catch { + when (/^Can't locate .*?\.pm in \@INC/) { } # ignore + default { die $_ } + }; + +=head1 CAVEATS + +=over 4 + +=item * + +C<@_> is not available within the C block, so you need to copy your +arglist. In case you want to work with argument values directly via C<@_> +aliasing (i.e. allow C<$_[1] = "foo">), you need to pass C<@_> by reference: + + sub foo { + my ( $self, @args ) = @_; + try { $self->bar(@args) } + } + +or + + sub bar_in_place { + my $self = shift; + my $args = \@_; + try { $_ = $self->bar($_) for @$args } + } + +=item * + +C returns from the C block, not from the parent sub (note that +this is also how C works, but not how L works): + + sub bar { + try { return "foo" }; + return "baz"; + } + + say bar(); # "baz" + +=item * + +C introduces another caller stack frame. L is not used. L +will not report this when using full stack traces, though, because +C<%Carp::Internal> is used. This lack of magic is considered a feature. + +=item * + +The value of C<$_> in the C block is not guaranteed to be the value of +the exception thrown (C<$@>) in the C block. There is no safe way to +ensure this, since C may be used unhygenically in destructors. The only +guarantee is that the C will be called if an exception is thrown. + +=item * + +The return value of the C block is not ignored, so if testing the result +of the expression for truth on success, be sure to return a false value from +the C block: + + my $obj = try { + MightFail->new; + } catch { + ... + + return; # avoid returning a true value; + }; + + return unless $obj; + +=item * + +C<$SIG{__DIE__}> is still in effect. + +Though it can be argued that C<$SIG{__DIE__}> should be disabled inside of +C blocks, since it isn't people have grown to rely on it. Therefore in +the interests of compatibility, C does not disable C<$SIG{__DIE__}> for +the scope of the error throwing code. + +=item * + +Lexical C<$_> may override the one set by C. + +For example Perl 5.10's C form uses a lexical C<$_>, creating some +confusing behavior: + + given ($foo) { + when (...) { + try { + ... + } catch { + warn $_; # will print $foo, not the error + warn $_[0]; # instead, get the error like this + } + } + } + +=back + +=head1 SEE ALSO + +=over 4 + +=item L + +Much more feature complete, more convenient semantics, but at the cost of +implementation complexity. + +=item L + +Automatic error throwing for builtin functions and more. Also designed to +work well with C/C. + +=item L + +A lightweight role for rolling your own exception classes. + +=item L + +Exception object implementation with a C statement. Does not localize +C<$@>. + +=item L + +Provides a C statement, but properly calling C is your +responsibility. + +The C keyword pushes C<$@> onto an error stack, avoiding some of the +issues with C<$@>, but you still need to localize to prevent clobbering. + +=back + +=head1 LIGHTNING TALK + +I gave a lightning talk about this module, you can see the slides (Firefox +only): + +L + +Or read the source: + +L + +=head1 VERSION CONTROL + +L + +=head1 AUTHOR + +Yuval Kogman Enothingmuch@woobling.orgE + +=head1 COPYRIGHT + + Copyright (c) 2009 Yuval Kogman. All rights reserved. + This program is free software; you can redistribute + it and/or modify it under the terms of the MIT license. + +=cut +