NAME

SQL::Builder::Column - Represents a SQL table column

SYNOPSIS

This class inherits from SQL::Builder::Base(3) and generates the following SQL:

        [[... .]schema.]table.]colname

or

        colalias

This module has support for custom field quoting or automatic quoting via DBI's quote_identifier(). Here's how to use it:

        my $col = SQL::Builder::Column->new(
                name => 'colname', # or: col => 'colname'
                alias => 'alias',
                'other->list_push' => [qw(table schema catalog)]
        );

        # alias
        print $col->sql;

        # turn on quoting

        $col->quote(1);

        # "catalog"."schema"."table"."colname"
        print $col->full_name;

        # override the built in quoting mechanism with DBI::quote_identifier()
        $col->dbh($dbh);

METHODS

This class inherits from SQL::Builder::Base(3)

new()

See SQL::Builder::Base::new() and SQL::Builder::Base::set() for documentation on this - it's an inherited method

alias([$alias])

Use this to get/set the alias of the column.

col([$colname])

Use this to get/set the column name. When you set it, the current object is returned

decide_quoter()

This probably doesn't need to be called directly. It is called in sql() or full_name() when the quoting mechanism needs to be determined. When dbh() is set we return a coderef that wraps a call to DBI::quote_identifier($item), unless force_custom_quoting() is set, in which case quoter() is returned.

default_quoter()

This just returns the builtin quoting mechanism so you can use it in the event quoter() has been changed

force_custom_quoting([1|0])

This method is used to get/set the option to force custom quoting (ie, use the quoter set via quoter()) of identifiers. This will ignore the availability of dbh(), but still only works when quote() is turned on. Returns the current object when called with arguments

full_name()

This returns the fully qualified SQL representation of the column. eg,

        [[... .]schema.]table.]colname

SQL::Builder::Base::dosql() is called for all objects returned by col() and other() and joined by a period "." - this means that a BinaryOp objects can be passed and aliased for use in a SELECT statement. Non-objects are quoted if quote() is turned on and decide_quoter() returns a coderef. A quoted SQL serialization might look like:

        "schema"."table"."colname"

Notice that each identifier is quoted individually. Objects are not quoted because their SQL serialization (sql()) is expected to perform any necessary quoting. This allows a table object to be passed to other() and its own quoting mechanisms can be used.

When the value of other() is processed and an item in the list is an object that has an alias() method that returns something defined and with a length, the alias is used instead. Consider the following:

        my $users   = SQL::Builder::Table->new(name => "users", alias => "u");

        my $user_id = SQL::Builder::Column->new(
                        name => "user_id",
                        other => $users
                );

        # u.user_id
        print $user_id->sql

This method throws an error if no column is set

init()

This call's SQL::Builder::Base::init() then sets some defaults. It returns the current object. See SQL::Builder::Base(3) for documentation on this method. This is just an initialization method and probably shouldn't be called directly.

other()

other() returns a SQL::Builder::List(3) object. Its purpose is to store catalog information about the schema/table/whatever to which the column belongs and ultimately turns into "schema.table" upon SQL serialization. The Column object doesn't rely on SQL::Builder::List::sql(), it simply uses List.pm for the list interface which may become useful in the future. It is possible to change the maintained list object and swap it with a SQL::Builder::List(3) subclass without breakage - just pass the object to other().

The maintained list can be infinitely long or empty and no assumptions or constraints will be placed on what is in the list or how it should be used. Upon SQL serialization this list is reversed - this means arguments should be passed in order of magnitude from smallest to largest. For example, tables are defined in schemas which belongs to databases, so we'll build our Column object like so:

        $col->other->list_push(qw(table schema db))

and when serialized, the list will be reversed and turn into something like:

        db.schema.table

For maximum code reuse, it might be wise to pass a SQL::Builder::Table(3) object and have it as the only list item. Any object passed here will be processed as SQL::Builder::Base::dosql($obj) on SQL serialization (sql()); non-objects are subject to quoting (see full_name())

quoter([$quote_coderef])

This is used to get/set the custom quoter. This is a class method, not an object method. If you set it once, it will be used for all Column objects without a dbh() set (see decide_quoter()). When called with an argument, the class/object is returned. Otherwise, the subroutine is returned. By default, the quoting routine is basically:

        return "\"$var\""

The method set here will be called on each element provided by col() and other() if a dbh() isn't available (see decide_quoter()). The quoting routine should accept the current object (think $self) as the first argument, and the item to be quoted as the second argument

quote([1|0])

This is used to turn on and off quoting. If turned off, dbh() and quoter() are ignored

sql()

If use_alias() is on, and the alias is defined and has a length, it is returned. otherwise, full_name() is returned

use_alias([1|0])

When turned on, this option affects the result of sql() and causes it to return the column alias if it is available. It is turned on (1) by default. When turned off, sql() will always return the value returned by full_name(). If use_alias() is called with no arguments, the current value is returned

SEE ALSO

SQL::Builder::Base(3) SQL::Builder::ColumnList(3) SQL::Builder::List(3) DBI(3)

cpanm SQL::Builder

perl -MCPAN -e shell
install SQL::Builder