NAME

DB::Object::Placeholder - Placeholder Object

SYNOPSIS

    my $p = $dbh->P( type => 'inet', value => '127.0.0.1' );
    my $q = "SELECT * FROM ip_registry WHERE ip_addr = inet($p) OR inet($p) << ip_addr";
    my $types = $p->replace( \$q );
    # or, since the object here is just an accessor for this method
    # my $types = DB::Object::Placeholder->replace( \$q );
    # Got a Module::Generic::Array in response
    # $types->first -> inet
    # $types->second -> inet

For example:

        my $P = $dbh->placeholder( type => 'inet' );
    $orders_tbl->where( $dbh->OR( $orders_tbl->fo->ip_addr == "inet $P", "inet $P" << $orders_tbl->fo->ip_addr ) );
    my $order_ip_sth = $orders_tbl->select( 'id' ) || fail( "An error has occurred while trying to create a select by ip query for table orders: " . $orders_tbl->error );
    # SELECT id FROM orders WHERE ip_addr = inet ? OR inet ? << ip_addr

DESCRIPTION

This is a placeholder representation class, because sometime, putting a placeholder in complex or even simple sql expression makes it impossible for this API to detect it.

Using this class, you can place placeholder in your query, specify what data type they represent and allow this api to recognise them and benefit from them even.

METHODS

new

Takes a list of values that are saved in the newly created object returned. Those name-value arguments pairs are the same as the methods described below

as_string

Returns the placeholder object as a string, which would look something like __PLACEHOLDER_1234567__

has

Provided with a query as a string or as a scalar reference and this will check if it contains any placeholder objects. It returns true if it does or false otherwise.

replace

Provided with a scalar (string) or scalar reference and this will replace any placeholder objects with actual SQL placeholders, i.e. ?, and return an array object of those placeholder datatypes, which may be blank. This is ok, it will be passed to the database driver upon binding and let it guess the best type. In list context, it also returns the modified query. This is useful if you only passed a string and not a scalar reference.

    my $types = $p->replace( \$query );
    # or
    my( $types, $query ) = $p->replace( $query );

type

Sets or gets the sql data type for this placeholder. It is not the constant, but the data type string itself. For example, for PG_JSONB in PostgreSQL, ir would simply be jsonb

value

The value of the placeholder, if any. This method is actually not used for now. It is reserved here for the future.

SEE ALSO

DBI, Apache::DBI

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

Copyright (c) 2021 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.