=pod 

=head1 NAME

Apache::Voodoo::Table - framework to handle common database operations

=head1 SYNOPSIS

 FIXME
 FIXME  Add the TONS of necessary documentation
 FIXME

=head1 EXAMPLE CONFIGURATION

 {
    table => 'table name',
    primary_key => 'column name' OR [ 'column', 'column2' ],
    primary_key_user_supplied => 0 | 1 (defaults to 0),
    primary_key_regexp => regular_expression (defaults to ^\d+$)
    columns => {
        name1 => {
            type => varchar, 
            length => +int or -1 for unlimited
            valid => 'email' |'url'| $code_ref

            --- Common to all data types ---
            regexp => regexp it must match.
            unique => 0|1 if (the column must be unique)
            required => 0|1
            references => {
                table       => 'name'
                primary_key => 'column'
                columns => 'column name' OR [ 'column1', 'column2', 'column3' ]
                select_label => column or sql concat(foo,bar,baz)
                select_default => primary_key value for default selected
                select_extra => 'order by foo or where stuff order by foo, etc.'
            }
        },
        name2 => {
            type => unsigned_int
            max  => maximum value
        },
        name3 => {
            type => signed_int
            max => maximum value
            min => minimum value
        },
        name4 => {
            type => (un)signed_decimal
            left => number of digits to left of decimal
            right => number of digits to right of decimal
        },
        name5 => {
            type => date,
            min => minimum date (optional) -- magic value: 'now' date must be >= today's date 
            max => maximum date (optional) -- magic value: 'now' date must be <= today's date
        },
        name6 => {
            type => time
        },
        name7 => {
            type => bit
        },
        name8 => {
            type => password (proposed magic type handling passwords, 
                              would assume varchar(32) not null as the column type
                              using Crypt::passwdMD5
                             )
        }
    },
    list_options => {
        default_sort => 'sort_name'
        sort => {
            'sort_name'  => [ column, column2, referenced_table.column, referenced_table.column2 ]
            'sort_name2' => [ column3, column4, referenced_table.column2 ]
        },
        search => [
            ['select list label','column'],
            ['select list label2','referenced_table.column']
        ]
    }
 }

=head1 METHODS

=over 4

=item success()

Returns 1 if the the last operation was "successful"

=over 8

=item 'add'    resulted in a new row

=item 'edit'   resulted in an update to a row

=item 'view'   returned a row

=item 'delete' 1 for 'no' on conformation; 2 for 'yes' and successful deletion

=item 'list'   returns 0 or more rows (no call errors)

=item 'toggle' flipped a row

=back

=item edit_details()

Returns details on the columns that we changed via edit.  Useful for producing a detailed audit log.

Return structure looks like:

    [
        [ 'column name','old value','new value' ]
    ]


=item add_insert_callback($subroutine_reference)

Adds a data validation routine to the add function

=item add_update_callback($subroutine_reference)

Adds a data validation routine to the edit function

=item add($p)

performs a database insertion

=item edit($p,$additional_where_clause_expression)

performs a database update

=item delete($p)

performs a delete from a table

=item list($p,$additional_where_clause_expression)

list all or part of the rows in a table

=item view($p,$additional_where_clause_expression)

Displays a particular row from the table

=item toggle($p,$column_name)

Toggles the column specified by the second parameter

=head1 AUTHOR

Maverick, /\/\averick@smurfbaneDOTorg

=head1 COPYRIGHT

Copyright (c) 2005 Steven Edwards.  All rights reserved.

You may use and distribute Voodoo under the terms described in the LICENSE file include
in this package or L<Apache::Voodoo::license>.  The summary is it's a legalese version
of the Artistic License :)