NAME
    boolean - Boolean support for Perl

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';

DESCRIPTION
    Most programming languages have a native "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: "true" and "false".

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 "use boolean" to
    encode*decode*roundtrip Boolean values.

FUNCTIONS
    This module defines the following functions:

    "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.

    "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.

    "boolean($scalar)"
        Casts the scalar value to a boolean value. If $scalar is true, it
        returns "boolean::true", otherwise it returns "boolean::false".

    "isTrue($scalar)"
        Returns "boolean::true" if the scalar passed to it is the
        "boolean::true" object. Returns "boolean::false" otherwise.

    "isFalse($scalar)"
        Returns "boolean::true" if the scalar passed to it is the
        "boolean::false" object. Returns "boolean::false" otherwise.

    "isBoolean($scalar)"
        Returns "boolean::true" if the scalar passed to it is the
        "boolean::true" or "boolean::false" object. Returns "boolean::false"
        otherwise.

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

    "$boolean->isTrue"
        Same as isTrue($boolean).

    "$boolean->isFalse"
        Same as isFalse($boolean).

USE OPTIONS
    By default this module exports the "true", "false" and "boolean"
    functions.

    The module also defines these export tags:

    ":all"
        Exports "true", "false", "boolean", "isTrue", "isFalse", "isBoolean"

    "-truth"
        You can specify the "-truth" option to override truth operators to
        return "boolean" values.

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

        Prints:

            boolean

        "-truth" can be used with the other import options.

JSON SUPPORT
    JSON::MaybeXS (or less preferably JSON.pm ) will encode Perl data with
    boolean.pm values correctly if you use the "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}',

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

COPYRIGHT AND LICENSE
    Copyright 2007-2015. 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 <http://www.perl.com/perl/misc/Artistic.html>