NAME

DBIx::Class::InflateColumn::Boolean - Auto-create boolean objects from columns.

VERSION

Version 0.001001

SYNOPSIS

Load this component and declare columns as boolean values.

    package Table;
    __PACKAGE__->load_components(qw/InflateColumn::Boolean Core/);
    __PACKAGE__->table('table');
    __PACKAGE__->true_is('Y');
    __PACKAGE__->add_columns(
        foo => {
            data_type => 'varchar',
            is_boolean  => 1,
        },
        bar => {
            data_type => 'varchar',
            is_boolean  => 1,
            true_is     => qr/^(?:yes|ja|oui|si)$/i,
        },
        baz => {
            data_type => 'int',
            is_boolean  => 1,
            false_is    => ['0', '-1'],
        },
    );

Then you can treat the specified column as a boolean:

    print 'table.foo is ', $table->foo ? 'true' : 'false', "\n";
    print 'table.bar is ', $table->bar ? 'true' : 'false', "\n";

The boolean object still stringifies to the actual field value:

    print $table->foo;  # prints "Y" if it is true

DESCRIPTION

Perl does not have a native boolean data type by itself, it takes certain several scalar values as false (like '', 0, 0.0) as well as empty lists and undef, and everything else is true. It is also possible to set the boolean value of an object instance.

As in most program code you have boolean data in nearly every database. But for a database it is up to the designer to decide what is true and what is false.

This module maps such "database booleans" into "Perl booleans" and back by inflating designated columns into some sort of boolean objects, that happen to be instances of Contextual::Return::Value. Objects of this class can store the original value and a boolean meaning at the same time. Therefore - if Yes in the database means true and No means false in the application the following two lines can virtually mean the same:

  if ($table->field eq "No") { ... }
  if (not $table->field) { ... }

That means that $table->field has the scalar value "No", but is taken as false in a boolean context, whereas without the little magic from Contextual::Return Perl would regard the string "No" as true.

When writing to the database, of course $table->field would be deflated to the original value "No" and not some Perlish form of a boolean.

Important Notice

It is strongly discouraged to assign a Contextual::Return object to a boolean field when creating a fresh row, because:

KISS (http://en.wikipedia.org/wiki/KISS_principle)

Just say "No" when you mean it. It does not buy you anything to say SCALAR {"No"} BOOL { 0 }.

Don't rely on the current boolean class

Take the underlying boolean class as a black box. It might be replaced by something other in future versions of this module.

Simply assign the appropriate scalars to boolean fields ("Yes" or "No" for the above example).

Another Important Notice

A database NULL value is mapped to Perl's undef and is never inflated. Therefore NULL is false and this can not be altered.

METHODS

true_is

  __PACKAGE__->true_is('Y');
  __PACKAGE__->true_is(['Y', 'y']);
  __PACKAGE__->true_is(qr/^(y|yes|true|1)$/i);

Gets/sets the possible values for true data in this table. Can be either a scalar, a reference to an array of scalars or a regular expression (qr/.../).

The last line in the above example shows this package's default for what is true when neither true_is nor "false_is" are set.

false_is

  __PACKAGE__->false_is('N');
  __PACKAGE__->false_is(['N', 'n']);
  __PACKAGE__->false_is(qr/^(n|no|false|0)$/i);

Gets/sets the possible values for false data in this table. Can be either a scalar, a reference to an array of scalars or a regular expression (qr/.../).

register_column

Chains with "register_column" in DBIx::Class::Row, and sets up boolean columns appropriately. This would not normally be called directly by end users.

SEE ALSO

Contextual::Return, DBIx::Class, DBIx::Class::InflateColumn

AUTHOR

Bernhard Graf <graf at cpan.org>

BUGS

Please report any bugs or feature requests to bug-dbix-class-inflatecolumn-bool at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DBIx-Class-InflateColumn-Boolean. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

Copyright 2008 Bernhard Graf, all rights reserved.

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

cpanm DBIx::Class::InflateColumn::Boolean

perl -MCPAN -e shell
install DBIx::Class::InflateColumn::Boolean