Author: Nathan Goodman

# NAME

Class::AutoDB::Table - Schema information for one table

# SYNOPSIS

This is a helper class for Class::AutoDB::Registry which represents the schema information for one table.

    use Class::AutoDB::Table;
    my $table=new Class::AutoDB::Table
      (-name=>'Person',
       -keys{name=>'string',dob=>'integer',grade_avg=>'float',friend=>'object'});
    my $name=$table->name;
    my $keys=$table->keys;           # hash of key=>type pairs
    my @sql=$table->schema;          # SQL statements to create table
    my @sql=$table->schema('create');# same as above
    my @sql=$table->schema('drop');  # SQL statements to drop table
    my @sql=$table->schema('alter'); # SQL statements to add columns
                                     #   of this table to another

# DESCRIPTION

This class represents schema information for one table. This class is fed a HASH of key=>type pairs. Each turns into one column of the table. In addition, the table has an 'object' column which is a foreign key pointing to the AutoDB object table and which is the primary key here. Indexes are defined on all keys. This class just creates SQL; it does not talk to the database.

At present, only our special data types ('string', 'integer', 'float', 'object') are supported. These can be abbreviated. These are translated into MySQL types as follows:

AutoDB type | MySQL type
string | longtext
integer | int
float | double
object | int

# BUGS and WISH-LIST

Name | Description | Priority/When
--- | --- | ---
General alter | The 'alter' function generates SQL to add all columns of the table to an empty table of the same name. This is what's needed by the Collection::merge code. Doing it right means comparing two tables and producing SQL to transform one into the other. | Wish-list

# METHODS and FUNCTIONS - Initialization

Title | new
Usage |
    my $table=new Class::AutoDB::Table
      (-name=>'Person',
       -keys=>{name=>'string',dob=>'integer'})
Function | Constructor.
Args | -name | Table name
-keys | Search keys. This is a HASH of key=>type pairs. Each key becomes a column of the table. The type must be a legal AutoDB (not MySQL!) base type ('string', 'integer', 'float', 'object').
Returns | Table object

# METHODS and FUNCTIONS – Simple Attributes

These are methods for getting and setting the values of simple attributes. Methods have the same name as the attribute. Some of these should be read-only (more precisely, should only be written by code internal to the object), but this is not enforced.

To get the value of attribute xxx, just say

$xxx=$object->xxx;

To set it, say

$object->xxx($new_value);

To clear it, say

$object->xxx(undef);

Attribute |
    name
Function | Table name
Access | Read-only

# METHODS and FUNCTIONS – Other

Title |
    keys
Usage | my %keys=$table->keys
    my $keys=$table->keys
Function | Returns key=>type pairs for keys registered for this table
Args |
    none
Returns | HASH or HASH ref depending on context

Title |
    put
Usage | $collection->put($key_values)
Function | Returns SQL statements needed to store the give key=>value pairs in the table. Does not touch the database
Args |
    $key_values
| HASH ref of key=value pairs to be stored. The HASH may contain more keys than are defined for this table, and may omit some keys defined for this table.
Returns | ARRAY or ARRAY ref depending on context. Each element of the results is a single SQL statement as a string.

Title |
    schema
Usage |
    my @sql=$table->schema
    my $sql=$table->schema
    my @sql=$table->schema($what)
    my $sql=$table->schema($what)
Function | Returns SQL statements needed to create, drop, or alter the table. Does not touch the database
Args |
    $what
| String indicating what schema operation is desired: create – default drop alter
Returns | ARRAY or ARRAY ref depending on context. Each element of the results is a single SQL statement as a string
Notes | Deprecated. Use create, drop, alter instead. The 'alter' function is a bit of a hack: it generates SQL to add all columns of the table to an empty table of the same name. This is what's needed by the Collection::merge code. The alternative of doing it right: comparing two tables and producing SQL to transform one into the other is overkill for what we need now.

Title |
    create
Usage | $table->create
Function | Returns SQL statements needed to create the tables that implement the table. Does not touch the database
Args |
    none
Returns | ARRAY or ARRAY ref depending on context. Each element of the results is a single SQL statement as a string.

Title |
    drop
Usage | $table->drop
Function | Returns SQL statements needed to drop the tables that implement the table. Does not touch the database
Args |
    none
Returns | ARRAY or ARRAY ref depending on context. Each element of the results is a single SQL statement as a string.

Title |
    alter
Usage | $table->alter
Function | Returns SQL statements needed to alter the tables that implement the table. Does not touch the database
Args |
    none
Returns | ARRAY or ARRAY ref depending on context. Each element of the results is a single SQL statement as a string.
Notes | Valid for BaseTables only. The 'alter' function is a bit of a hack: it generates SQL to add all columns of the table to an empty table of the same name. This is what's needed by the Collection::merge code. The alternative of doing it right: comparing two tables and producing SQL to transform one into the other is overkill for what we need now.

#