package Acme::Don::t;

$VERSION = '1.01';

sub don't (&) {}

1;
__END__

=head1 NAME

Acme::Don't - The opposite of C<do>

=head1 VERSION

This document describes version 1.01 of Acme::Don::t,
released May  3, 2002.

=head1 SYNOPSIS

    use Acme::Don't;

    don't { print "This won't be printed\n" };    # NO-OP

=head1 DESCRIPTION

The Acme::Don't module provides a C<don't> command, which is the 
opposite of Perl's built-in C<do>.

It is used exactly like the C<do BLOCK> function except that,
instead of executing the block it controls, it...well...doesn't.

Regardless of the contents of the block, C<don't> returns C<undef>.

You can even write:

    don't {
        # code here
    } while condition();

And, yes, in strict analogy to the semantics of Perl's magical
C<do...while>, the C<don't...while> block is I<unconditionally>
not done once before the test. ;-)

Note that the code in the C<don't> block must be syntactically valid
Perl.  This is an important feature: you get the accelerated
performance of not actually executing the code, without sacrificing
the security of compile-time syntax checking.

=head1 LIMITATIONS

=over

=item *

Doesn't (yet) implement the opposite of C<do STRING>. 
The current workaround is to use:

    don't {"filename"};

=item *

The construct:

    don't { don't { ... } }

isn't (yet) equivalent to:

    do { ... }

because the outer C<don't> prevents the inner C<don't> from being executed,
before the inner C<don't> gets the chance to discover that it actually
I<should> execute.

This is an issue of semantics. C<don't...> doesn't mean C<do the opposite of...>; it means C<do nothing with...>.

In other words, doin nothing about doing nothing does...nothing.

=item * 

You can't (yet) use a:

    don't { ... } unless condition();

as a substitute for:

    do { ... } if condition();

Again, it's an issue of semantics. C<don't...unless...> doesn't mean C<do the opposite of...if...>; it means C<do nothing with...if not...>.

=back

=head1 AUTHOR

Damian Conway (damian@conway.org)

=head1 BLAME

Luke Palmer really should be I<far> more careful what he idly wishes for.

=head1 BUGS

Unlikely, since it doesn't actually do anything.
However, bug reports and other feedback are most welcome.

=head1 COPYRIGHT

Copyright (c) 2002, Damian Conway. All Rights Reserved.
This module is free software. It may be used, redistributed
and/or modified under the terms of the Perl Artistic License
  (see http://www.perl.com/perl/misc/Artistic.html)