/ 
Class-ReluctantORM-0.52_0
River stage zero No dependents
/ Class::ReluctantORM::SQL::Expression::Literal

NAME

Class::ReluctantORM::SQL::Where::Literal - Represent literals in WHEREs

SYNOPSIS

# Save yourself some typing
use Class::ReluctantORM::SQL::Aliases;

# Make a literal for some reason.
my $lit_num       = Literal->new(1);
my $lit_str       = Literal->new('foo');
my $lit_empty_str = Literal->new('');
my $lit_null      = Literal->new(undef);
my $clone         = $other_lit->clone();

# These are shortcut constructors
$null  = Literal->NULL();
$true  = Literal->TRUE();
$false = Literal->FALSE();
$blip  = Literal->EMPTY_STRING();

# This throws an exception - to force proper use of NULL semantics
eval { Literal->new();  };

# Criterion provides auto-boxing
my $crit = Criterion->new('=', 1, 1);

# Same thing
my $crit = Criterion->new('=', Literal->new(1), Literal->new(1));

DESCRIPTION

It's not likely you'll need to interact directly with this module. It is used to simply provide a consistent interface for literal arguments in WHERE clauses.

DATA TYPE SUPPORT

There is very rudimentary support for data types. Since perl is very loosely typed, and so is the DBI placeholder system, there's not much sense in building a strongly typed SQL object model.

Its current purpose is to simply distinguish Boolean values from string or numeric values.

Data types are represented by an all-caps string. Literal will use BOOLEAN, NULL, STRING, and NUMBER by default, but if you pass in other values, it won't complain.

PREFAB CONSTRUCTORS

These constructors represent Literals that are common or awkward to specify. Their value should be obvious.

$lit = Literal->FALSE()
$lit = Literal->TRUE()
$lit = Literal->NULL()
$lit = Literal->EMPTY_STRING()

GENERIC CONSTRUCTOR

my $lit = Literal->new($value);

my $lit = Literal->new($value, $data_type);

Creates a new Literal with the given value. $value is required. Pass a literal undef to get a Literal that represents NULL.

The optional second parameter is an all-caps string representing the data type. You may send any value here. If not provided, it will be guessed as one of NULL, STRING, or NUMERIC (using Scalar::Util::looks_like_number()).

ACCESSORS AND MUTATORS

@empty = $crit->child_expressions();

Always returns an empty list. Required by the Argument interface.

$bool = $arg->is_literal();

All objects of this class return true. The class add this method to Expression, making all other subclasses of it return false.

$bool = $crit->is_leaf_expression();

Always returns true for this class. Required by the Argument interface.

$str = $col->pretty_print();

Renders a human-readable representation of the Literal.

$clone = $lit->clone();

Makes a new Literal with the same boxed value as the original.

$val = $lit->value();

Returns the enclosed value. Keep in mind that undef represents NULL.

You may need to check the data type to confirm that you have the right thing. For example, a Literal->FALSE->value() will return 0.

$str = $lit->data_type();

Returns an all-caps string representing the datatype.

$bool = $lit->is_equivalent($expr);

Returns true if $expr is a Literal, with matching data_type and value.

AUTHOR

Clinton Wolfe January 2009