=head1 NOTES

PJF in this document refers to Paul Fenwick E<lt>pjf@cpan.orgE<gt>,
the author of the C<autodie> pragma.

=head1 DECIDED BEHAVIOUR

=head2 Name

C<autodie> is the name of the pragma.  Thanks to Jured for the
suggestion.  This won out over the very many other names suggested
on p5p (March 2008).

=head2 Perl Version

Currently C<autodie> works in Perl 5.10.  I'd like it to work in
Perl 5.8, but I haven't yet wrapped my head around how to have
lexical pragamata in 5.8 work as intended, although L<autobox>
is a good example.  Patches welcome.

=head2 :lexical switch to Fatal

The C<:lexical> switch is used internally, but should not be
used by the end-user.  This restriction is not currently
enforced.

=head2 :void switch and autodie

C<:void> retains its existing behaviour in C<Fatal>.  C<:void>
is not allowed with C<autodie>.  Even though we could trivially
support it, p5p decided it would be very confusing.

=head2 Interactions between Fatal and autodie

The following conditions are considered errors (and are
enforced by the code):

=over 4

=item C<no Fatal>

=item C<no autodie> when C<use Fatal> is in effect for the same sub

=back

=head2 no autodie

A plain:

    no autodie;

turns off all C<autodie> behaviour with the current lexical
scope.  It is not allowed if any form of C<Fatal> is in
effect.

=head1 OPEN QUESTIONS

=head2 Errors from Fatal

The current implementation makes the error messages from Fatal
look really nice.  However it also opens the possibility of those
nice messages breaking backwards compatibility.

It's been mostly decided that Fatal will retain its existing
yet rather awful looking messages, in case people are testing
them with $@ =~ /..../ and looking for some really odd patterns.

If you want nice looking messages, one is encouraged to s/Fatal/autodie/;

=head2 Vanilla autodie

The vanilla form:

    use autodie;

is presently (June 2008) open for discussion.  PJF's opinion
is that it should be the same as:

    use autodie qw(:default);

enabling the pragma for all built-ins for which it makes sense
to do so.  It should be noted that this list may increase in
later versions of the module.  The C<:default> list may also
contain user-defined subroutines which wish to register themselves
with that behaviour (although these should be rare).

=head2 Overriding system

The in-built C<system> function does not have a prototype.
It's been proposed we ignore the fact that it can't be
overridden in the traditional sense, and do it anyway.  This
would make the exotic form of C<system> a syntax error
within the package that C<Fatal> or C<autodie> was used:

    system { $cmd } @list;

It can still be invoked with:

    CORE::system { $cmd } @list;

Although this form is not checked for failure.

The proposed method for determining "what is an error" for
C<system> is the same as that used by L<IPC::System::Simple>,
namely that the following are considered errors:

=over 4

=item Failing to start (eg, command not found)

=item Returning a non-zero exit status

=item Being killed by a signal (which may result in a coredump)

=back

PJF would like to use the existing L<IPC::System::Simple> module
(of which he is the author) to implement the handling of
C<autodie>'s interaction with C<system>, since it already does
all the hard work, and works on all platforms on which it's
been tested (including Win32 and Unix flavours, but not exotic
systems like VMS).

L<IPC::System::Simple> has no dependencies outside the core,
but there's the question that if we want C<autodie> to be
a core candidate, do we also wish to include L<IPC::System::Simple>?

=head2 Dependencies

PJF would like to make C<autodie> a candidate for Perl 5.10.1
core, as it squashes some bad behaviour in C<Fatal>, provides
nicer error messages, and provides a well-defined lexical
way of having built-ins throw excpetions.  He would like to
use some non-core modules in its creation, but if C<autodie>
is going to be included in the core, this will contribute
towards core bloat.

PJF would like to have the option of using L<IPC::System::Simple>
and L<Exception::Class> as part of the implementation of
C<autodie>.  L<IPC::System::Simple> has only core dependencies,
but L<Exception::Class> depends upon L<Devel::StackTrace>
and L<Class::Data::Inheritable>.

C<autodie> can be implemented without these modules, and
already provides simple object-based exceptions with inspiration
from the L<Exception::Class> design.  Implementing the proposed
C<system> changes becomes trivial using L<IPC::System::Simple>,
since its C<run> command already works in the same way as
the proposed C<system> changes.

=head1 BUGS

=over 4

=item Package and lexical interaction

Due to the way the code operates, C<autodie> only changes the
bavhiour of subroutines within the same lexical scope
I<provided they are in the same package>.  This means that
the second open is not checked in the following code:

    {
        package Foo;

        use autodie qw(open);

        open(my $fh1, '<', $some_file);     # autodying

        package Bar;

        open(my $fh2, '<', $some_file);     # not autodying

    }

=back
