argra****@users*****
argra****@users*****
2011年 9月 7日 (水) 03:05:06 JST
Index: docs/modules/autodie-2.06_01/autodie/exception.pod
diff -u /dev/null docs/modules/autodie-2.06_01/autodie/exception.pod:1.1
--- /dev/null Wed Sep 7 03:05:06 2011
+++ docs/modules/autodie-2.06_01/autodie/exception.pod Wed Sep 7 03:05:06 2011
@@ -0,0 +1,529 @@
+
+=encoding euc-jp
+
+=head1 NAME
+
+=begin original
+
+autodie::exception - Exceptions from autodying functions.
+
+=end original
+
+autodie::exception - autodie した関数の例外
+
+=head1 SYNOPSIS
+
+ eval {
+ use autodie;
+
+ open(my $fh, '<', 'some_file.txt');
+
+ ...
+ };
+
+ if (my $E = $@) {
+ say "Ooops! ",$E->caller," had problems: $@";
+ }
+
+=head1 DESCRIPTION
+
+=begin original
+
+When an L<autodie> enabled function fails, it generates an
+C<autodie::exception> object. This can be interrogated to
+determine further information about the error that occurred.
+
+=end original
+
+When an L<autodie> enabled function fails, it generates an
+C<autodie::exception> object. This can be interrogated to
+determine further information about the error that occurred.
+(TBT)
+
+=begin original
+
+This document is broken into two sections; those methods that
+are most useful to the end-developer, and those methods for
+anyone wishing to subclass or get very familiar with
+C<autodie::exception>.
+
+=end original
+
+This document is broken into two sections; those methods that
+are most useful to the end-developer, and those methods for
+anyone wishing to subclass or get very familiar with
+C<autodie::exception>.
+(TBT)
+
+=head2 Common Methods
+
+=begin original
+
+These methods are intended to be used in the everyday dealing
+of exceptions.
+
+=end original
+
+These methods are intended to be used in the everyday dealing
+of exceptions.
+(TBT)
+
+=begin original
+
+The following assume that the error has been copied into
+a separate scalar:
+
+=end original
+
+The following assume that the error has been copied into
+a separate scalar:
+(TBT)
+
+ if ($E = $@) {
+ ...
+ }
+
+=begin original
+
+This is not required, but is recommended in case any code
+is called which may reset or alter C<$@>.
+
+=end original
+
+This is not required, but is recommended in case any code
+is called which may reset or alter C<$@>.
+(TBT)
+
+=head3 args
+
+ my $array_ref = $E->args;
+
+=begin original
+
+Provides a reference to the arguments passed to the subroutine
+that died.
+
+=end original
+
+Provides a reference to the arguments passed to the subroutine
+that died.
+(TBT)
+
+=head3 function
+
+ my $sub = $E->function;
+
+=begin original
+
+The subroutine (including package) that threw the exception.
+
+=end original
+
+The subroutine (including package) that threw the exception.
+(TBT)
+
+=head3 file
+
+ my $file = $E->file;
+
+=begin original
+
+The file in which the error occurred (eg, C<myscript.pl> or
+C<MyTest.pm>).
+
+=end original
+
+The file in which the error occurred (eg, C<myscript.pl> or
+C<MyTest.pm>).
+(TBT)
+
+=head3 package
+
+ my $package = $E->package;
+
+=begin original
+
+The package from which the exceptional subroutine was called.
+
+=end original
+
+The package from which the exceptional subroutine was called.
+(TBT)
+
+=head3 caller
+
+ my $caller = $E->caller;
+
+=begin original
+
+The subroutine that I<called> the exceptional code.
+
+=end original
+
+The subroutine that I<called> the exceptional code.
+(TBT)
+
+=head3 line
+
+ my $line = $E->line;
+
+=begin original
+
+The line in C<< $E->file >> where the exceptional code was called.
+
+=end original
+
+The line in C<< $E->file >> where the exceptional code was called.
+(TBT)
+
+=head3 context
+
+ my $context = $E->context;
+
+=begin original
+
+The context in which the subroutine was called. This can be
+'list', 'scalar', or undefined (unknown). It will never be 'void', as
+C<autodie> always captures the return value in one way or another.
+
+=end original
+
+The context in which the subroutine was called. This can be
+'list', 'scalar', or undefined (unknown). It will never be 'void', as
+C<autodie> always captures the return value in one way or another.
+(TBT)
+
+=head3 return
+
+ my $return_value = $E->return;
+
+=begin original
+
+The value(s) returned by the failed subroutine. When the subroutine
+was called in a list context, this will always be a reference to an
+array containing the results. When the subroutine was called in
+a scalar context, this will be the actual scalar returned.
+
+=end original
+
+The value(s) returned by the failed subroutine. When the subroutine
+was called in a list context, this will always be a reference to an
+array containing the results. When the subroutine was called in
+a scalar context, this will be the actual scalar returned.
+(TBT)
+
+=head3 errno
+
+ my $errno = $E->errno;
+
+=begin original
+
+The value of C<$!> at the time when the exception occurred.
+
+=end original
+
+The value of C<$!> at the time when the exception occurred.
+(TBT)
+
+=begin original
+
+B<NOTE>: This method will leave the main C<autodie::exception> class
+and become part of a role in the future. You should only call
+C<errno> for exceptions where C<$!> would reasonably have been
+set on failure.
+
+=end original
+
+B<NOTE>: This method will leave the main C<autodie::exception> class
+and become part of a role in the future. You should only call
+C<errno> for exceptions where C<$!> would reasonably have been
+set on failure.
+(TBT)
+
+=head3 eval_error
+
+ my $old_eval_error = $E->eval_error;
+
+=begin original
+
+The contents of C<$@> immediately after autodie triggered an
+exception. This may be useful when dealing with modules such
+as L<Text::Balanced> that set (but do not throw) C<$@> on error.
+
+=end original
+
+The contents of C<$@> immediately after autodie triggered an
+exception. This may be useful when dealing with modules such
+as L<Text::Balanced> that set (but do not throw) C<$@> on error.
+(TBT)
+
+=head3 matches
+
+ if ( $e->matches('open') ) { ... }
+
+ if ( $e ~~ 'open' ) { ... }
+
+=begin original
+
+C<matches> is used to determine whether a
+given exception matches a particular role. On Perl 5.10,
+using smart-match (C<~~>) with an C<autodie::exception> object
+will use C<matches> underneath.
+
+=end original
+
+C<matches> is used to determine whether a
+given exception matches a particular role. On Perl 5.10,
+using smart-match (C<~~>) with an C<autodie::exception> object
+will use C<matches> underneath.
+(TBT)
+
+=begin original
+
+An exception is considered to match a string if:
+
+=end original
+
+An exception is considered to match a string if:
+(TBT)
+
+=over 4
+
+=item *
+
+=begin original
+
+For a string not starting with a colon, the string exactly matches the
+package and subroutine that threw the exception. For example,
+C<MyModule::log>. If the string does not contain a package name,
+C<CORE::> is assumed.
+
+=end original
+
+For a string not starting with a colon, the string exactly matches the
+package and subroutine that threw the exception. For example,
+C<MyModule::log>. If the string does not contain a package name,
+C<CORE::> is assumed.
+(TBT)
+
+=item *
+
+=begin original
+
+For a string that does start with a colon, if the subroutine
+throwing the exception I<does> that behaviour. For example, the
+C<CORE::open> subroutine does C<:file>, C<:io> and C<:all>.
+
+=end original
+
+For a string that does start with a colon, if the subroutine
+throwing the exception I<does> that behaviour. For example, the
+C<CORE::open> subroutine does C<:file>, C<:io> and C<:all>.
+(TBT)
+
+=begin original
+
+See L<autodie/CATEGORIES> for futher information.
+
+=end original
+
+See L<autodie/CATEGORIES> for futher information.
+(TBT)
+
+=back
+
+=head2 Advanced methods
+
+=begin original
+
+The following methods, while usable from anywhere, are primarily
+intended for developers wishing to subclass C<autodie::exception>,
+write code that registers custom error messages, or otherwise
+work closely with the C<autodie::exception> model.
+
+=end original
+
+The following methods, while usable from anywhere, are primarily
+intended for developers wishing to subclass C<autodie::exception>,
+write code that registers custom error messages, or otherwise
+work closely with the C<autodie::exception> model.
+(TBT)
+
+=head3 register
+
+ autodie::exception->register( 'CORE::open' => \&mysub );
+
+=begin original
+
+The C<register> method allows for the registration of a message
+handler for a given subroutine. The full subroutine name including
+the package should be used.
+
+=end original
+
+The C<register> method allows for the registration of a message
+handler for a given subroutine. The full subroutine name including
+the package should be used.
+(TBT)
+
+=begin original
+
+Registered message handlers will receive the C<autodie::exception>
+object as the first parameter.
+
+=end original
+
+Registered message handlers will receive the C<autodie::exception>
+object as the first parameter.
+(TBT)
+
+=head3 add_file_and_line
+
+ say "Problem occurred",$@->add_file_and_line;
+
+=begin original
+
+Returns the string C< at %s line %d>, where C<%s> is replaced with
+the filename, and C<%d> is replaced with the line number.
+
+=end original
+
+Returns the string C< at %s line %d>, where C<%s> is replaced with
+the filename, and C<%d> is replaced with the line number.
+(TBT)
+
+=begin original
+
+Primarily intended for use by format handlers.
+
+=end original
+
+Primarily intended for use by format handlers.
+(TBT)
+
+=head3 stringify
+
+ say "The error was: ",$@->stringify;
+
+=begin original
+
+Formats the error as a human readable string. Usually there's no
+reason to call this directly, as it is used automatically if an
+C<autodie::exception> object is ever used as a string.
+
+=end original
+
+Formats the error as a human readable string. Usually there's no
+reason to call this directly, as it is used automatically if an
+C<autodie::exception> object is ever used as a string.
+(TBT)
+
+=begin original
+
+Child classes can override this method to change how they're
+stringified.
+
+=end original
+
+Child classes can override this method to change how they're
+stringified.
+(TBT)
+
+=head3 format_default
+
+ my $error_string = $E->format_default;
+
+=begin original
+
+This produces the default error string for the given exception,
+I<without using any registered message handlers>. It is primarily
+intended to be called from a message handler when they have
+been passed an exception they don't want to format.
+
+=end original
+
+This produces the default error string for the given exception,
+I<without using any registered message handlers>. It is primarily
+intended to be called from a message handler when they have
+been passed an exception they don't want to format.
+(TBT)
+
+=begin original
+
+Child classes can override this method to change how default
+messages are formatted.
+
+=end original
+
+Child classes can override this method to change how default
+messages are formatted.
+(TBT)
+
+=head3 new
+
+ my $error = autodie::exception->new(
+ args => \@_,
+ function => "CORE::open",
+ errno => $!,
+ context => 'scalar',
+ return => undef,
+ );
+
+
+=begin original
+
+Creates a new C<autodie::exception> object. Normally called
+directly from an autodying function. The C<function> argument
+is required, its the function we were trying to call that
+generated the exception. The C<args> parameter is optional.
+
+=end original
+
+Creates a new C<autodie::exception> object. Normally called
+directly from an autodying function. The C<function> argument
+is required, its the function we were trying to call that
+generated the exception. The C<args> parameter is optional.
+(TBT)
+
+=begin original
+
+The C<errno> value is optional. In versions of C<autodie::exception>
+1.99 and earlier the code would try to automatically use the
+current value of C<$!>, but this was unreliable and is no longer
+supported.
+
+=end original
+
+The C<errno> value is optional. In versions of C<autodie::exception>
+1.99 and earlier the code would try to automatically use the
+current value of C<$!>, but this was unreliable and is no longer
+supported.
+(TBT)
+
+=begin original
+
+Atrributes such as package, file, and caller are determined
+automatically, and cannot be specified.
+
+=end original
+
+Atrributes such as package, file, and caller are determined
+automatically, and cannot be specified.
+(TBT)
+
+=head1 SEE ALSO
+
+L<autodie>, L<autodie::exception::system>
+
+=head1 LICENSE
+
+Copyright (C)2008 Paul Fenwick
+
+This is free software. You may modify and/or redistribute this
+code under the same terms as Perl 5.10 itself, or, at your option,
+any later version of Perl 5.
+
+=head1 AUTHOR
+
+Paul Fenwick E<lt>pjf****@perlt*****<gt>
+
Index: docs/modules/autodie-2.06_01/autodie/hints.pod
diff -u /dev/null docs/modules/autodie-2.06_01/autodie/hints.pod:1.1
--- /dev/null Wed Sep 7 03:05:06 2011
+++ docs/modules/autodie-2.06_01/autodie/hints.pod Wed Sep 7 03:05:06 2011
@@ -0,0 +1,679 @@
+
+=encoding euc-jp
+
+=head1 NAME
+
+=begin original
+
+autodie::hints - Provide hints about user subroutines to autodie
+
+=end original
+
+autodie::hints - ユーザーのサブルーチンを autodie させるヒントを提供する
+
+=head1 SYNOPSIS
+
+ package Your::Module;
+
+ our %DOES = ( 'autodie::hints::provider' => 1 );
+
+ sub AUTODIE_HINTS {
+ return {
+ foo => { scalar => HINTS, list => SOME_HINTS },
+ bar => { scalar => HINTS, list => MORE_HINTS },
+ }
+ }
+
+ # Later, in your main program...
+
+ use Your::Module qw(foo bar);
+ use autodie qw(:default foo bar);
+
+ foo(); # succeeds or dies based on scalar hints
+
+ # Alternatively, hints can be set on subroutines we've
+ # imported.
+
+ use autodie::hints;
+ use Some::Module qw(think_positive);
+
+ BEGIN {
+ autodie::hints->set_hints_for(
+ \&think_positive,
+ {
+ fail => sub { $_[0] <= 0 }
+ }
+ )
+ }
+ use autodie qw(think_positive);
+
+ think_positive(...); # Returns positive or dies.
+
+
+=head1 DESCRIPTION
+
+=head2 Introduction
+
+=begin original
+
+The L<autodie> pragma is very smart when it comes to working with
+Perl's built-in functions. The behaviour for these functions are
+fixed, and C<autodie> knows exactly how they try to signal failure.
+
+=end original
+
+L<autodie> プラグマは、Perl の組み込み関数に対する動作はとても
+賢いです。
+これらの関数の振る舞いは固定されていて、C<autodie> はこれらがどのように
+失敗を知らせるかを正確に知っています。
+
+=begin original
+
+But what about user-defined subroutines from modules? If you use
+C<autodie> on a user-defined subroutine then it assumes the following
+behaviour to demonstrate failure:
+
+=end original
+
+But what about user-defined subroutines from modules? If you use
+C<autodie> on a user-defined subroutine then it assumes the following
+behaviour to demonstrate failure:
+(TBT)
+
+=over
+
+=item *
+
+=begin original
+
+A false value, in scalar context
+
+=end original
+
+A false value, in scalar context
+(TBT)
+
+=item *
+
+=begin original
+
+An empty list, in list context
+
+=end original
+
+An empty list, in list context
+(TBT)
+
+=item *
+
+=begin original
+
+A list containing a single undef, in list context
+
+=end original
+
+A list containing a single undef, in list context
+(TBT)
+
+=back
+
+=begin original
+
+All other return values (including the list of the single zero, and the
+list containing a single empty string) are considered successful. However,
+real-world code isn't always that easy. Perhaps the code you're working
+with returns a string containing the word "FAIL" upon failure, or a
+two element list containing C<(undef, "human error message")>. To make
+autodie work with these sorts of subroutines, we have
+the I<hinting interface>.
+
+=end original
+
+All other return values (including the list of the single zero, and the
+list containing a single empty string) are considered successful. However,
+real-world code isn't always that easy. Perhaps the code you're working
+with returns a string containing the word "FAIL" upon failure, or a
+two element list containing C<(undef, "human error message")>. To make
+autodie work with these sorts of subroutines, we have
+the I<hinting interface>.
+(TBT)
+
+=begin original
+
+The hinting interface allows I<hints> to be provided to C<autodie>
+on how it should detect failure from user-defined subroutines. While
+these I<can> be provided by the end-user of C<autodie>, they are ideally
+written into the module itself, or into a helper module or sub-class
+of C<autodie> itself.
+
+=end original
+
+The hinting interface allows I<hints> to be provided to C<autodie>
+on how it should detect failure from user-defined subroutines. While
+these I<can> be provided by the end-user of C<autodie>, they are ideally
+written into the module itself, or into a helper module or sub-class
+of C<autodie> itself.
+(TBT)
+
+=head2 What are hints?
+
+=begin original
+
+A I<hint> is a subroutine or value that is checked against the
+return value of an autodying subroutine. If the match returns true,
+C<autodie> considers the subroutine to have failed.
+
+=end original
+
+A I<hint> is a subroutine or value that is checked against the
+return value of an autodying subroutine. If the match returns true,
+C<autodie> considers the subroutine to have failed.
+(TBT)
+
+=begin original
+
+If the hint provided is a subroutine, then C<autodie> will pass
+the complete return value to that subroutine. If the hint is
+any other value, then C<autodie> will smart-match against the
+value provided. In Perl 5.8.x there is no smart-match operator, and as such
+only subroutine hints are supported in these versions.
+
+=end original
+
+If the hint provided is a subroutine, then C<autodie> will pass
+the complete return value to that subroutine. If the hint is
+any other value, then C<autodie> will smart-match against the
+value provided. In Perl 5.8.x there is no smart-match operator, and as such
+only subroutine hints are supported in these versions.
+(TBT)
+
+=begin original
+
+Hints can be provided for both scalar and list contexts. Note
+that an autodying subroutine will never see a void context, as
+C<autodie> always needs to capture the return value for examination.
+Autodying subroutines called in void context act as if they're called
+in a scalar context, but their return value is discarded after it
+has been checked.
+
+=end original
+
+Hints can be provided for both scalar and list contexts. Note
+that an autodying subroutine will never see a void context, as
+C<autodie> always needs to capture the return value for examination.
+Autodying subroutines called in void context act as if they're called
+in a scalar context, but their return value is discarded after it
+has been checked.
+(TBT)
+
+=head2 Example hints
+
+=begin original
+
+Hints may consist of scalars, array references, regular expressions and
+subroutine references. You can specify different hints for how
+failure should be identified in scalar and list contexts.
+
+=end original
+
+Hints may consist of scalars, array references, regular expressions and
+subroutine references. You can specify different hints for how
+failure should be identified in scalar and list contexts.
+(TBT)
+
+=begin original
+
+These examples apply for use in the C<AUTODIE_HINTS> subroutine and when
+calling C<autodie::hints->set_hints_for()>.
+
+=end original
+
+These examples apply for use in the C<AUTODIE_HINTS> subroutine and when
+calling C<autodie::hints->set_hints_for()>.
+(TBT)
+
+=begin original
+
+The most common context-specific hints are:
+
+=end original
+
+The most common context-specific hints are:
+(TBT)
+
+ # Scalar failures always return undef:
+ { scalar => undef }
+
+ # Scalar failures return any false value [default expectation]:
+ { scalar => sub { ! $_[0] } }
+
+ # Scalar failures always return zero explicitly:
+ { scalar => '0' }
+
+ # List failures always return an empty list:
+ { list => [] }
+
+ # List failures return () or (undef) [default expectation]:
+ { list => sub { ! @_ || @_ == 1 && !defined $_[0] } }
+
+ # List failures return () or a single false value:
+ { list => sub { ! @_ || @_ == 1 && !$_[0] } }
+
+ # List failures return (undef, "some string")
+ { list => sub { @_ == 2 && !defined $_[0] } }
+
+ # Unsuccessful foo() returns 'FAIL' or '_FAIL' in scalar context,
+ # returns (-1) in list context...
+ autodie::hints->set_hints_for(
+ \&foo,
+ {
+ scalar => qr/^ _? FAIL $/xms,
+ list => [-1],
+ }
+ );
+
+ # Unsuccessful foo() returns 0 in all contexts...
+ autodie::hints->set_hints_for(
+ \&foo,
+ {
+ scalar => 0,
+ list => [0],
+ }
+ );
+
+=begin original
+
+This "in all contexts" construction is very common, and can be
+abbreviated, using the 'fail' key. This sets both the C<scalar>
+and C<list> hints to the same value:
+
+=end original
+
+This "in all contexts" construction is very common, and can be
+abbreviated, using the 'fail' key. This sets both the C<scalar>
+and C<list> hints to the same value:
+(TBT)
+
+ # Unsuccessful foo() returns 0 in all contexts...
+ autodie::hints->set_hints_for(
+ \&foo,
+ {
+ fail => sub { @_ == 1 and defined $_[0] and $_[0] == 0 }
+ }
+ );
+
+ # Unsuccessful think_positive() returns negative number on failure...
+ autodie::hints->set_hints_for(
+ \&think_positive,
+ {
+ fail => sub { $_[0] < 0 }
+ }
+ );
+
+ # Unsuccessful my_system() returns non-zero on failure...
+ autodie::hints->set_hints_for(
+ \&my_system,
+ {
+ fail => sub { $_[0] != 0 }
+ }
+ );
+
+=head1 Manually setting hints from within your program
+
+=begin original
+
+If you are using a module which returns something special on failure, then
+you can manually create hints for each of the desired subroutines. Once
+the hints are specified, they are available for all files and modules loaded
+thereafter, thus you can move this work into a module and it will still
+work.
+
+=end original
+
+If you are using a module which returns something special on failure, then
+you can manually create hints for each of the desired subroutines. Once
+the hints are specified, they are available for all files and modules loaded
+thereafter, thus you can move this work into a module and it will still
+work.
+(TBT)
+
+ use Some::Module qw(foo bar);
+ use autodie::hints;
+
+ autodie::hints->set_hints_for(
+ \&foo,
+ {
+ scalar => SCALAR_HINT,
+ list => LIST_HINT,
+ }
+ );
+ autodie::hints->set_hints_for(
+ \&bar,
+ { fail => SOME_HINT, }
+ );
+
+=begin original
+
+It is possible to pass either a subroutine reference (recommended) or a fully
+qualified subroutine name as the first argument. This means you can set hints
+on modules that I<might> get loaded:
+
+=end original
+
+It is possible to pass either a subroutine reference (recommended) or a fully
+qualified subroutine name as the first argument. This means you can set hints
+on modules that I<might> get loaded:
+(TBT)
+
+ use autodie::hints;
+ autodie::hints->set_hints_for(
+ 'Some::Module:bar', { fail => SCALAR_HINT, }
+ );
+
+=begin original
+
+This technique is most useful when you have a project that uses a
+lot of third-party modules. You can define all your possible hints
+in one-place. This can even be in a sub-class of autodie. For
+example:
+
+=end original
+
+This technique is most useful when you have a project that uses a
+lot of third-party modules. You can define all your possible hints
+in one-place. This can even be in a sub-class of autodie. For
+example:
+(TBT)
+
+ package my::autodie;
+
+ use parent qw(autodie);
+ use autodie::hints;
+
+ autodie::hints->set_hints_for(...);
+
+ 1;
+
+=begin original
+
+You can now C<use my::autodie>, which will work just like the standard
+C<autodie>, but is now aware of any hints that you've set.
+
+=end original
+
+You can now C<use my::autodie>, which will work just like the standard
+C<autodie>, but is now aware of any hints that you've set.
+(TBT)
+
+=head1 Adding hints to your module
+
+=begin original
+
+C<autodie> provides a passive interface to allow you to declare hints for
+your module. These hints will be found and used by C<autodie> if it
+is loaded, but otherwise have no effect (or dependencies) without autodie.
+To set these, your module needs to declare that it I<does> the
+C<autodie::hints::provider> role. This can be done by writing your
+own C<DOES> method, using a system such as C<Class::DOES> to handle
+the heavy-lifting for you, or declaring a C<%DOES> package variable
+with a C<autodie::hints::provider> key and a corresponding true value.
+
+=end original
+
+C<autodie> provides a passive interface to allow you to declare hints for
+your module. These hints will be found and used by C<autodie> if it
+is loaded, but otherwise have no effect (or dependencies) without autodie.
+To set these, your module needs to declare that it I<does> the
+C<autodie::hints::provider> role. This can be done by writing your
+own C<DOES> method, using a system such as C<Class::DOES> to handle
+the heavy-lifting for you, or declaring a C<%DOES> package variable
+with a C<autodie::hints::provider> key and a corresponding true value.
+(TBT)
+
+=begin original
+
+Note that checking for a C<%DOES> hash is an C<autodie>-only
+short-cut. Other modules do not use this mechanism for checking
+roles, although you can use the C<Class::DOES> module from the
+CPAN to allow it.
+
+=end original
+
+Note that checking for a C<%DOES> hash is an C<autodie>-only
+short-cut. Other modules do not use this mechanism for checking
+roles, although you can use the C<Class::DOES> module from the
+CPAN to allow it.
+(TBT)
+
+=begin original
+
+In addition, you must define a C<AUTODIE_HINTS> subroutine that returns
+a hash-reference containing the hints for your subroutines:
+
+=end original
+
+In addition, you must define a C<AUTODIE_HINTS> subroutine that returns
+a hash-reference containing the hints for your subroutines:
+(TBT)
+
+ package Your::Module;
+
+ # We can use the Class::DOES from the CPAN to declare adherence
+ # to a role.
+
+ use Class::DOES 'autodie::hints::provider' => 1;
+
+ # Alternatively, we can declare the role in %DOES. Note that
+ # this is an autodie specific optimisation, although Class::DOES
+ # can be used to promote this to a true role declaration.
+
+ our %DOES = ( 'autodie::hints::provider' => 1 );
+
+ # Finally, we must define the hints themselves.
+
+ sub AUTODIE_HINTS {
+ return {
+ foo => { scalar => HINTS, list => SOME_HINTS },
+ bar => { scalar => HINTS, list => MORE_HINTS },
+ baz => { fail => HINTS },
+ }
+ }
+
+=begin original
+
+This allows your code to set hints without relying on C<autodie> and
+C<autodie::hints> being loaded, or even installed. In this way your
+code can do the right thing when C<autodie> is installed, but does not
+need to depend upon it to function.
+
+=end original
+
+This allows your code to set hints without relying on C<autodie> and
+C<autodie::hints> being loaded, or even installed. In this way your
+code can do the right thing when C<autodie> is installed, but does not
+need to depend upon it to function.
+(TBT)
+
+=head1 Insisting on hints
+
+=begin original
+
+When a user-defined subroutine is wrapped by C<autodie>, it will
+use hints if they are available, and otherwise reverts to the
+I<default behaviour> described in the introduction of this document.
+This can be problematic if we expect a hint to exist, but (for
+whatever reason) it has not been loaded.
+
+=end original
+
+When a user-defined subroutine is wrapped by C<autodie>, it will
+use hints if they are available, and otherwise reverts to the
+I<default behaviour> described in the introduction of this document.
+This can be problematic if we expect a hint to exist, but (for
+whatever reason) it has not been loaded.
+(TBT)
+
+=begin original
+
+We can ask autodie to I<insist> that a hint be used by prefixing
+an exclamation mark to the start of the subroutine name. A lone
+exclamation mark indicates that I<all> subroutines after it must
+have hints declared.
+
+=end original
+
+We can ask autodie to I<insist> that a hint be used by prefixing
+an exclamation mark to the start of the subroutine name. A lone
+exclamation mark indicates that I<all> subroutines after it must
+have hints declared.
+(TBT)
+
+ # foo() and bar() must have their hints defined
+ use autodie qw( !foo !bar baz );
+
+ # Everything must have hints (recommended).
+ use autodie qw( ! foo bar baz );
+
+ # bar() and baz() must have their hints defined
+ use autodie qw( foo ! bar baz );
+
+ # Enable autodie for all of Perl's supported built-ins,
+ # as well as for foo(), bar() and baz(). Everything must
+ # have hints.
+ use autodie qw( ! :all foo bar baz );
+
+=begin original
+
+If hints are not available for the specified subroutines, this will cause a
+compile-time error. Insisting on hints for Perl's built-in functions
+(eg, C<open> and C<close>) is always successful.
+
+=end original
+
+If hints are not available for the specified subroutines, this will cause a
+compile-time error. Insisting on hints for Perl's built-in functions
+(eg, C<open> and C<close>) is always successful.
+(TBT)
+
+=begin original
+
+Insisting on hints is I<strongly> recommended.
+
+=end original
+
+Insisting on hints is I<strongly> recommended.
+(TBT)
+
+=head1 Diagnostics
+
+=over 4
+
+=item Attempts to set_hints_for unidentifiable subroutine
+
+=begin original
+
+You've called C<< autodie::hints->set_hints_for() >> using a subroutine
+reference, but that reference could not be resolved back to a
+subroutine name. It may be an anonymous subroutine (which can't
+be made autodying), or may lack a name for other reasons.
+
+=end original
+
+You've called C<< autodie::hints->set_hints_for() >> using a subroutine
+reference, but that reference could not be resolved back to a
+subroutine name. It may be an anonymous subroutine (which can't
+be made autodying), or may lack a name for other reasons.
+(TBT)
+
+=begin original
+
+If you receive this error with a subroutine that has a real name,
+then you may have found a bug in autodie. See L<autodie/BUGS>
+for how to report this.
+
+=end original
+
+If you receive this error with a subroutine that has a real name,
+then you may have found a bug in autodie. See L<autodie/BUGS>
+for how to report this.
+(TBT)
+
+=item fail hints cannot be provided with either scalar or list hints for %s
+
+=begin original
+
+When defining hints, you can either supply both C<list> and
+C<scalar> keywords, I<or> you can provide a single C<fail> keyword.
+You can't mix and match them.
+
+=end original
+
+When defining hints, you can either supply both C<list> and
+C<scalar> keywords, I<or> you can provide a single C<fail> keyword.
+You can't mix and match them.
+(TBT)
+
+=item %s hint missing for %s
+
+=begin original
+
+You've provided either a C<scalar> hint without supplying
+a C<list> hint, or vice-versa. You I<must> supply both C<scalar>
+and C<list> hints, I<or> a single C<fail> hint.
+
+=end original
+
+You've provided either a C<scalar> hint without supplying
+a C<list> hint, or vice-versa. You I<must> supply both C<scalar>
+and C<list> hints, I<or> a single C<fail> hint.
+(TBT)
+
+=back
+
+=head1 ACKNOWLEDGEMENTS
+
+=over
+
+=item *
+
+=begin original
+
+Dr Damian Conway for suggesting the hinting interface and providing the
+example usage.
+
+=end original
+
+Dr Damian Conway for suggesting the hinting interface and providing the
+example usage.
+(TBT)
+
+=item *
+
+=begin original
+
+Jacinta Richardson for translating much of my ideas into this
+documentation.
+
+=end original
+
+Jacinta Richardson for translating much of my ideas into this
+documentation.
+(TBT)
+
+=back
+
+=head1 AUTHOR
+
+Copyright 2009, Paul Fenwick E<lt>pjf****@perlt*****<gt>
+
+=head1 LICENSE
+
+This module is free software. You may distribute it under the
+same terms as Perl itself.
+
+=head1 SEE ALSO
+
+L<autodie>, L<Class::DOES>
+
+=cut
+