=pod

=for comment
DO NOT EDIT. This Pod was generated by Swim.
See http://github.com/ingydotnet/swim-pm#readme

=encoding utf8

=head1 NAME

boolean - Boolean support for Perl

=for html
<a href="https://travis-ci.org/ingydotnet/boolean-pm"><img src="https://travis-ci.org/ingydotnet/boolean-pm.png" alt="boolean-pm"></a>
<a href="https://coveralls.io/r/ingydotnet/boolean-pm?branch=master"><img src="https://coveralls.io/repos/ingydotnet/boolean-pm/badge.png" alt="boolean-pm"></a>

=head1 SYNOPSIS

    use boolean;

    do &always if true;
    do &never if false;

    do &maybe if boolean($value)->isTrue;

and:

    use boolean ':all';

    $guess = int(rand(2)) % 2 ? true : false;

    do &something if isTrue($guess);
    do &something_else if isFalse($guess);

and:

    use boolean -truth;

    die unless ref(42 == 42) eq 'boolean';
    die unless ("foo" =~ /bar/) eq '0';

=head1 DESCRIPTION

Most programming languages have a native C<Boolean> data type. Perl does not.

Perl has a simple and well known Truth System. The following scalar values
are false:

    $false1 = undef;
    $false2 = 0;
    $false3 = 0.0;
    $false4 = '';
    $false5 = '0';

Every other scalar value is true.

This module provides basic Boolean support, by defining two special objects:
C<true> and C<false>.

=head1 RATIONALE

When sharing data between programming languages, it is important to support
the same group of basic types. In Perlish programming languages, these types
include: Hash, Array, String, Number, Null and Boolean. Perl lacks native
Boolean support.

Data interchange modules like YAML and JSON can now C<use boolean> to
encodeI<decode>roundtrip Boolean values.

=head1 FUNCTIONS

This module defines the following functions:

=over

=item C<true>

This function returns a scalar value which will evaluate to true. The value is
a singleton object, meaning there is only one "true" value in a Perl process
at any time. You can check to see whether the value is the "true" object with
the isTrue function described below.

=item C<false>

This function returns a scalar value which will evaluate to false. The value
is a singleton object, meaning there is only one "false" value in a Perl
process at any time. You can check to see whether the value is the "false"
object with the isFalse function described below.

=item C<boolean($scalar)>

Casts the scalar value to a boolean value. If C<$scalar> is true, it returns
C<boolean::true>, otherwise it returns C<boolean::false>.

=item C<isTrue($scalar)>

Returns C<boolean::true> if the scalar passed to it is the C<boolean::true>
object. Returns C<boolean::false> otherwise.

=item C<isFalse($scalar)>

Returns C<boolean::true> if the scalar passed to it is the C<boolean::false>
object. Returns C<boolean::false> otherwise.

=item C<isBoolean($scalar)>

Returns C<boolean::true> if the scalar passed to it is the C<boolean::true> or
C<boolean::false> object. Returns C<boolean::false> otherwise.

=back

=head1 METHODS

Since true and false return objects, you can call methods on them.

=over

=item C<< $boolean->isTrue >>

Same as isTrue($boolean).

=item C<< $boolean->isFalse >>

Same as isFalse($boolean).

=back

=head1 USE OPTIONS

By default this module exports the C<true>, C<false> and C<boolean> functions.

The module also defines these export tags:

=over

=item C<:all>

Exports C<true>, C<false>, C<boolean>, C<isTrue>, C<isFalse>, C<isBoolean>

=item C<-truth>

You can specify the C<-truth> option to override truth operators to return
C<boolean> values.

    use boolean -truth;
    print ref("hello" eq "world"), "\n";

Prints:

    boolean

C<-truth> can be used with the other import options.

=back

=head1 JSON SUPPORT

JSON::MaybeXS (or less preferably JSON.pm ) will encode Perl data with
boolean.pm values correctly if you use the C<convert_blessed> option:

    use JSON::MaybeXS;
    use boolean -truth;
    my $json = JSON::MaybeXS->new->convert_blessed;
    say $json->encode({false => (0 == 1)});     # Says: '{"false":false}',

=head1 AUTHOR

Ingy döt Net <ingy@cpan.org>

=head1 COPYRIGHT

Copyright 2007-2014. Ingy döt Net

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

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut