-----------------------------------------------------------------------------
| Want v0.04    - Robin Houston, 2001-08-04
-----------------------------------------------------------------------------

Changes since v0.03:
	- 'want' is now exported by default
	- BOOL is a euphemism for BOOLEAN (Perl 6 compatibility)
	- ARGUMENTS section added to documentation
	- excised C++-style comments from the source
	- fixed the expectation count issue from the BUGS section of 0.03
	- ASSIGN context. Yeah, baby!
	- don't throw an error if RVALUE/LVALUE are used from a non-lvalue sub
	- specifiers can also now be space-separated, e.g.:
		want('LVALUE ASSIGN');

Changes since v0.02:
	- Fix documentation snafus
	- add want('COUNT') as a synonym for C<howmany>
	  and want('REF') for C<wantref>
	- BOOLEAN context
	- now compiles & passes tests under ithreads
	- SCALARREF and OBJECT reference contexts
	  (want('REF') eq 'SCALAR' || want('REF') eq 'OBJECT')
	- Reorganised test suite
	

Changes since v0.01:
        - Give correct expectation count for constructs like
                my ($x, $y, $z) = (23, foo());   # foo's expectation count is 2
        - want(2) should be true in C<@x = foo()> etc;
          i.e. infinity > N for any finite N  :-)
        - Support '!' negative requests
        - correct expectation count for slices


For full documentation, see the POD included with the module.
Below is a brief extract of the documentation, to give you an
idea of what this module does. It requires Perl version 5.6 or
later.


NAME
       Want - Implement the `want' command

SYNOPSIS
         use Want;
         sub foo :lvalue {
             if    (want(qw'LVALUE ASSIGN')) {
               print "We have been assigned ", want('ASSIGN');
               return undef;
             }
             elsif (want('LIST')) {
               return (1, 2, 3);
             }
             elsif (want('BOOL')) {
               return 0;
             }
             elsif (want(qw'SCALAR !REF')) {
               return 23;
             }
             elsif (want('HASH')) {
               return { foo => 17, bar => 23 };
             }
             else {
               return;
             }
         }

DESCRIPTION
       This module generalises the mechanism of the wantarray
       function, allowing a function to determine in some detail
       how its return value is going to be immediately used.

       ...

EXAMPLES

    use Carp 'croak';
    use Want 'howmany';
    sub numbers {
        my $count = howmany();
        croak("Can't make an infinite list") if !defined($count);
        return (1..$count);
    }
    my ($one, $two, $three) = numbers();


    use Want 'want';
    sub pi () {
        if    (want('ARRAY')) {
            return [3, 1, 4, 1, 5, 9];
        }
        elsif (want('LIST')) {
            return (3, 1, 4, 1, 5, 9);
        }
        else {
            return 3;
        }
    }
    print pi->[2];      # prints 4
    print ((pi)[3]);    # prints 1


    sub backstr :lvalue {
        if (want(qw'LVALUE ASSIGN')) {
            my ($a) = want('ASSIGN');
            $_[0] = reverse $a;
            return undef;
        }
        elsif (want('RVALUE')) {
            my $t = scalar reverse $_[0];
        }
        else {
            carp("Not in ASSIGN context");
        }
    }
 
    print "foo -> ", backstr("foo"), "\n";	# foo -> oof
    backstr(my $robin) = "nibor";
    print "\$robin is now $robin\n";		# $robin is now robin


AUTHOR
       Robin Houston, <robin@cpan.org>
       
       Thanks to Damian Conway for encouragement and good
       suggestions.

SEE ALSO
       o   the wantarray entry in the perlfunc manpage

       o   Perl6 RFC 21, by Damian Conway.
           http://dev.perl.org/rfc/21.html

COPYRIGHT
       Copyright (c) 2001, Robin Houston. All Rights Reserved.
       This module is free software. It may be used,
       redistributed and/or modified under the same terms as Perl
       itself.