NAME

DB::Object::Query::Element - Database Object Interface

SYNOPSIS

    use DB::Object::Query::Element;
    my $this = DB::Object::Query::Element->new(
        # a scalar, or an DB::Object::Fields::Field object
        field => $some_sql_field,
        # designed to be used for insert statements
        format => $some_format,
        # The position, if any, of this new object
        # This is used for numbered placeholders only, 
        # such as $1, $2, or ?1, ?2 depending on the driver
        index => $integer,
        # Could also be $1, $2, ?1, ?2 depending on the driver
        placeholder => '?',
        # a DB::Object::Query object
        query_object => $object,
        type => $sql_type,
        value => $some_value,
    ) || die( DB::Object::Query::Element->error, "\n" );

VERSION

    v0.2.0

DESCRIPTION

This class represent a query element as used throughout this API. It can represent the formatting of some part of an insert query, or some placeholder and its type and field, or just a field and its value, or a combination of those.

It makes it more efficient to build query with their associated binded values and types in the proper order, possibly using numbered placeholder, if the SQL driver (such as PostgreSQL or SQLite) support them.

CONSTRUCTOR

new

Takes an hash or hash reference of key-value pairs matching any of the methods below.

Returns a newly instantiated object upon success, or sets an error and return undef or an empty list, depending on the caller's context.

METHODS

as_is

Sets or gets the boolean value. If true, then the format specified will be used as-is during execution. This is aimed for value representing SQL functions or other values passed through that the user wants no optimisation.

For example:

    my $tbl = $dbh->some_table || die( "No table found" );
    $tbl->where( user_id => '?' );
    my $sth = $tbl->update( updated => \'NOW()' ) || die( $tbl->error );
    my $rv = $sth->exec( $user_id ) || die( $sth->error );

In the example above, when NOW() was specified as a scalar reference, it indicates we want the value to be used as-is. This would translate to something like:

    UPDATE some_table SET updated = NOW() WHERE user_id = 'b9c01f91-8094-462c-9f49-a0340dc9fcec'

elements

Sets or gets an DB::Object::Query::Elements object. By default this is undef and is used when this element represent a sub-query.

field

Sets or gets the element SQL field (or column) name. It can also be set to a DB::Object::Fields::Field object.

fo

    my $field_object = $el->fo;
    $el->fo( $field_object );

Sets or gets a table field object.

If no field is set, then in accessor mode, this will retrieve the table field object for the field value currently set by calling fields and passing it the field name set in "field", if any.

If the value set in "field" is already a table field object, then this is used instead of course.

If nothing was found, it returns undef, but if this method is called in object context, such as chaining, then a null object will be returned instead to prevent a hard perl error.

For example, assuming no field object could be found, the call below would normally return an error that name cannot be called on an undefined value, but here it detects the call is in an object context and returns null object allowing a fake name method to be called and that will return undef

    $el->fo->name;

Once found the value is cached, so if called many times, there is no performance penalty.

format

Sets or gets the element formatting. This is used for insert statements.

It returns a scalar object

generic

Returns a string representing the element with placeholder. This does not mean this element is using a placeholder, but rather provides a generic representation to be used when binding data to it.

The string returned is an object of Module::Generic::Scalar

index

Sets or gets the placeholder index position.

This is used if this element represents a placeholder and it is a numbered one, such as $1, $2, or ?1, ?2 depending on what the driver supports.

Returns the current value, which is by default undef, or a Module::Generic::Number object.

is_numbered

Read-only. Returns true (1) if the element represent a placeholder and it is a numbered one, such as $1, $2, or ?1, ?2 depending on what the driver supports, or false (0) otherwise.

placeholder

Sets or gets the element placeholder, such as ?, or $1, $2, or ?1, ?2 depending on what the driver supports.

When a value is set, it will check if this is a numbered placeholder and set the value for "index" accordingly.

query_object

Sets or gets the DB::Object::Query object set for this object.

type

Sets or gets the field SQL type.

Returns a scalar object object.

value

Sets or gets the element value.

Returns a scalar object object.

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

perl

COPYRIGHT & LICENSE

Copyright(c) 2023 DEGUEST Pte. Ltd.

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

cpanm DB::Object

perl -MCPAN -e shell
install DB::Object