
=encoding utf8

=head1 NAME

Types::Bool - Booleans as objects for Perl

=head1 VERSION

version 2.98009

=head1 SYNOPSIS

    use Types::Bool qw(true false is_bool to_bool);

    $true  = true;
    $false = false;

    is_bool(true);     # true
    is_bool('xxx');    # false

    to_bool(1);        # Types::Bool::true()
    to_bool('');       # Types::Bool::false()

=head1 DESCRIPTION

I<This is meant as a standard interface to boolean objects for Perl.>

Perl has no native representation for booleans.
Most of the time the Perl concept of truth is enough.
But when dealing with serialization of formats
which support booleans, it is desirable to keep the
booleans intact on round trips, eg. when writing after loading.
And there are other good reasons for that,
like strict validation via various mechanisms, like schemas,
OpenAPI, type hierarchies, etc.

A solution for that was adopted for JSON modules
around 2012 by using references to C<1> or C<0>
blessed into L<JSON::PP::Boolean> which was the
chosen canonical package for these objects.

The problem with that was the coupling with L<JSON::PP>
for no apparent good reason. Booleans are independent
of JSON and this association makes little sense
when loading documents in formats like YAML, MessagePack, BSON, etc.
However, the integration of the concept of boolean
for all these applications is quite convenient.

Marc Lehmann's L<Types::Serialiser> approached this problem
by creating a common interface used by L<JSON::XS> and L<CBOR::XS>
modules. This module lifts this core concept (including
idea, implementation and documentation) into an isolated treatment
for booleans only – so this can be proposed as the common
ground for interoperability on booleans as objects for Perl modules.

The implementation keeps the compatibility
with the previous agreement on C<JSON::PP::Boolean>
by making the C<Types::Bool> stash an alias for C<JSON::PP::Boolean>.
That means

    Types::Bool::true->isa('JSON::PP::Boolean');

but also

    Types::Bool::true->isa('Types::Bool');

This also allows an optimization to an isa test
by direct comparison of stash pointers.

=head2 INTERFACE

L<Types::Bool> has two ready-to-use instances for true and false.

    Types::Bool::true()

    Types::Bool::false()

L<Types::Bool> true values are represented as a reference
to a scalar containing C<1> – implementations are allowed
to directly test for this. For example, one can tell
if a value is a L<Types::Bool> true by using this:

    Types::Bool::is_bool($value) && $$value

L<Types::Bool> false values are represented as a reference
to a scalar containing C<0> – implementations are allowed
to directly test for this.

One can test if a value is a L<Types::Bool> with

    Types::Bool::is_bool($value);

Converting from a Perl true or false value into L<Types::Bool> can
be done with

    Types::Bool::to_bool($value);

Also part of this interface is a few overloaded
operators for L<Type::Bool> objects.

    # bool
    true  ? 'yes' : 'no';    # 'yes'
    false ? 'yes' : 'no';    # 'no'

    # 0+
    0+ true;     # 1
    0+ false;    # 0

    # ""
    true . '';     # 1
    false . '';    # 0

This minimum set of functionality allows for easy and efficient
implementation of other operations, like negating booleans:

    Types::Bool::to_bool( !$value );

=head2 CORE CODE

The code of this module would look as below, if not
for the efforts to play nice with L<JSON::PP>, L<Types::Serialiser>
and L<Cpanel::JSON::XS> modules.

    package Types::Bool;

    use 5.006;
    use Exporter 1.57 'import';
    use Scalar::Util ();

    use overload (
        '0+' => sub { ${ $_[0] } },
        '++' => sub { $_[0] = ${ $_[0] } + 1 },
        '--' => sub { $_[0] = ${ $_[0] } - 1 },
        fallback => 1,
    );

    our @EXPORT_OK = qw(true false is_bool to_bool);

    use constant true  => do { bless \( my $dummy = 1 ), 'Types::Bool' };
    use constant false => do { bless \( my $dummy = 0 ), 'Types::Bool' };

    sub is_bool ($) { Scalar::Util::blessed( $_[0] ) and $_[0]->isa('Types::Bool') }

    sub to_bool ($) { $_[0] ? true : false }

=head1 COMPATIBILITY

Besides the agreement on using C<JSON::PP::Boolean>
as the canonical package for booleans, as of May 2018,
the main JSON modules all step on each others' toes
with varying degrees of intensity when it comes
to decide what is implemented.

What we consider here the "main JSON modules" are:
L<JSON::PP>, L<Types::Serialiser>, and L<Cpanel::JSON::XS>.
These are the original sources of ideas,
implementations, and package names related to boolean
support and the most relevant
CPAN modules on the dependency chain.

For example,

=over 4

=item *

L<JSON::PP::Boolean> defines C<VERSION> and overloads
C<0+>, C<++> and C<--> operators.

=item *

L<Types::Serialiser> establishes an C<ISA> relationship
with a base class overloading the same operators above.

=item *

L<Cpanel::JSON::XS> in turn overloads these operators
and a few more.

=back

As these modules are loaded by a Perl program,
these actions are all replayed over the C<JSON::PP::Boolean>
package. (The last one loaded is basically who wins
on the final code at runtime.) This is almost harmless,
because their implementations mostly agree with each other.
But it is not hard to see this getting out of hand
if they start to diverge.

The additional interface for boolean support provided by these
modules, whether functions, variables and methods, live on their own packages:

=over 4

=item *

L<JSON::PP>: C<true>, C<false>, C<is_bool> under C<JSON::PP>

=item *

L<Types::Serialiser>: C<true>, C<$true>, C<false>, C<$false>, C<is_bool>,
C<is_true>, C<is_false> under C<Types::Serialiser>

=item *

L<Cpanel::JSON::XS>: C<true>, C<$true>, C<false>, C<$false>,
C<is_bool> under C<Cpanel::JSON::XS>.

=back

They all have subtle differences related to prototypes, enabled pragmas,
and stricter or more lenient behavior. Since those don't dwell
in the same base package, C<JSON::PP::Boolean>, they are safe
from the point of view of other consumers of booleans and relevant
to the back-compatibility history of each of these modules.
But they all contribute to the lack of consistency on the interface
to deal with booleans.

Those issues mainly stem from the lack
of a consensus on ownership of C<JSON::PP::Boolean>.
With the advent of L<Types::Bool>, this may or
may not be mitigated depending on the adoption
of a unified treatment of sorts.

When L<Types::Bool> gets added to this list as yet another
module playing with C<JSON::PP::Boolean>,
it takes the most conservative approach: it does not touch a function
or overloaded method which is already there.
That means it will still provide all of the interface described
before, because it will implement anything that is missing.
But it may suboptimally accept what has been defined before
by a previous module. And it does not fight with modules which
get loaded after either.

Ideally, the best scenario will be if / when the main JSON modules
start depending on L<Types::Bool>. Even if that does not happen,
this module still stands as a compatible alternative to
support booleans as objects for Perl.

=head1 FUNCTIONS

L<Types::Bool> implements the following functions, which can be imported individually.

=head2 false

    $false = Types::Bool::false;

Return the canonical "false" value.

This function has a C<()> prototype and works as a constant
(suitable for inlining by the Perl interpreter).

=head2 is_bool

    $is_bool = Types::Bool::is_bool($value);

Return true if given a C<Types::Bool> object.
Return false otherwise.

This function has a C<($)> prototype.

=head2 to_bool

    $bool = Types::Bool::to_bool($value);

Turns a true or false Perl value into
C<Types::Bool::true> or C<Types::Bool::false>.

This function has a C<($)> prototype.

=head2 true

    $true = Types::Bool::true;

Return the canonical "true" value.

This function has a C<()> prototype and works as a constant
(suitable for inlining by the Perl interpreter).

=head1 BUGS

The use of L<overload> makes this module heavier.
See L<Types::Serializer/"BUGS">.

=head1 ACKNOWLEDGMENTS

Original idea and code came from L<JSON::XS::Boolean> written by Marc Lehmann.

Tina Müller inspired me to create this distribution after reading her
L<PTS 2018 report|http://blogs.perl.org/users/tinita/2018/05/my-report-of-the-perl-toolchain-summit-2018-in-oslo.html>.

=head1 SEE ALSO

L<Types::Serialiser>

L<JSON::PP>

L<JSON::XS>

L<Cpanel::JSON::XS>

=head1 AUTHOR

Adriano Ferreira <ferreira@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Adriano Ferreira.

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

=cut
