root/lang/perl/Boolean-Verbose/trunk/lib/Boolean/Verbose.pm @ 14193

package Boolean::Verbose;

use strict;
use warnings;
use base qw/Exporter/;
use overload (map {$_ => \&_bool} qw/"" nomethod/);

our @EXPORT = qw/false true/;

sub _bool  { return shift()->{bool} }
sub new    { shift; bless {@_} }
sub true   { __PACKAGE__->new( bool => 1, message => shift) }
sub false  { __PACKAGE__->new( bool => 0, message => shift) }
sub message{ return shift()->{message} }

=head1 NAME

Boolean::Verbose - return true or false with verbose message

=head1 VERSION

Version 0.01

=cut

our $VERSION = '0.01';

=head1 SYNOPSIS

  use Boolean::Verbose;

  if(my $r = check()){
    # OK, you can see why you are OK.
    print $r->message;
  }else{
    # NG, you can see why you are NG.
    print $r->message;
  }

  sub check{
    return false('you are not 20.')  unless is_age_20();
    return false('you are not male') unless is_male();
    return true('you are 20 and male');
  }

=head1 DESCRIPTION

Boolean::Verbose returns 1 or 0 with verbose message.

What for it is used? It is for bad code.

for example;

 sub check{
   ....
   return 0 if not is_over_18(...);
   ....
   return 0 if not is_male(...);
   ....
   return 1;
 }
 
 unless(check()){
   print "error."
 }

You maintain this code and your boss order following to you;
"Change behavior by the result of check function.
If not is_over_18, call for_child function.
If not is_male, call for_female function."


You can change return value, but this check function is used other places.
So, if you chenage this value, you have to change other places. It is hard and not interesting task.
You wouldn't change return value, but You need some additional information.
You can do it with Boolean::Verbose.
 
 use Boolean::Verbose;
 
 sub check{
   ....
   return false("not_over_18.") if not is_over_18(...);
   ....
   return false("not_male.") if not is_male(...);;
   ....
   return true("all_ok");
 }
 
 unless(my $bool = check()){
   my $msg = $bool->message;
   if($msg eq 'not_over_18'){
     for_child(...);
   }elsif($msg eq 'not_male'){
     for_female(...);
   }
 }

=head1 EXPORT

=over

=item true

 true('you are right');

It returns 1, but it is object. When you use 'message' method.
You can see 'you are right'.

=item false

 true('you are wrong');

It returns 0, but it is object. When you use 'message' method.
You can see 'you are wrong'.

=back

=head1 METHOD

=over 4

=item new

 Boolean::Verbose->new(bool => 1, message => 'message');

This constructor is used internaly. So, you don't need to call this.

=item message

 $obj->message;

You can see verbose message used as true or false argument.

=back

=head1 AUTHOR

Ktat, C<< <ktat at cpan.org> >>

=head1 BUGS

Please report any bugs or feature requests to
C<bug-boolean-verbose at rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Boolean-Verbose>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Boolean::Verbose

You can also look for information at:

=over 4

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Boolean-Verbose>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Boolean-Verbose>

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Boolean-Verbose>

=item * Search CPAN

L<http://search.cpan.org/dist/Boolean-Verbose>

=back

=head1 ACKNOWLEDGEMENTS

=head1 COPYRIGHT & LICENSE

Copyright 2006 Ktat, all rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut

1; # End of Boolean::Verbose