.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SQL::Translator::Schema::Table 3pm"
.TH SQL::Translator::Schema::Table 3pm 2024-01-20 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
SQL::Translator::Schema::Table \- SQL::Translator table object
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  use SQL::Translator::Schema::Table;
\&  my $table = SQL::Translator::Schema::Table\->new( name => \*(Aqfoo\*(Aq );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`SQL::Translator::Schema::Table\*(C'\fR is the table object.
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
Object constructor.
.PP
.Vb 4
\&  my $table  =  SQL::Translator::Schema::Table\->new(
\&      schema => $schema,
\&      name   => \*(Aqfoo\*(Aq,
\&  );
.Ve
.SS add_constraint
.IX Subsection "add_constraint"
Add a constraint to the table.  Returns the newly created
\&\f(CW\*(C`SQL::Translator::Schema::Constraint\*(C'\fR object.
.PP
.Vb 5
\&  my $c1     = $table\->add_constraint(
\&      name   => \*(Aqpk\*(Aq,
\&      type   => PRIMARY_KEY,
\&      fields => [ \*(Aqfoo_id\*(Aq ],
\&  );
\&
\&  my $c2 = SQL::Translator::Schema::Constraint\->new( name => \*(Aquniq\*(Aq );
\&  $c2    = $table\->add_constraint( $constraint );
.Ve
.SS drop_constraint
.IX Subsection "drop_constraint"
Remove a constraint from the table. Returns the constraint object if the index
was found and removed, an error otherwise. The single parameter can be either
an index name or an \f(CW\*(C`SQL::Translator::Schema::Constraint\*(C'\fR object.
.PP
.Vb 1
\&  $table\->drop_constraint(\*(Aqmyconstraint\*(Aq);
.Ve
.SS add_index
.IX Subsection "add_index"
Add an index to the table.  Returns the newly created
\&\f(CW\*(C`SQL::Translator::Schema::Index\*(C'\fR object.
.PP
.Vb 5
\&  my $i1     = $table\->add_index(
\&      name   => \*(Aqname\*(Aq,
\&      fields => [ \*(Aqname\*(Aq ],
\&      type   => \*(Aqnormal\*(Aq,
\&  );
\&
\&  my $i2 = SQL::Translator::Schema::Index\->new( name => \*(Aqid\*(Aq );
\&  $i2    = $table\->add_index( $index );
.Ve
.SS drop_index
.IX Subsection "drop_index"
Remove an index from the table. Returns the index object if the index was
found and removed, an error otherwise. The single parameter can be either
an index name of an \f(CW\*(C`SQL::Translator::Schema::Index\*(C'\fR object.
.PP
.Vb 1
\&  $table\->drop_index(\*(Aqmyindex\*(Aq);
.Ve
.SS add_field
.IX Subsection "add_field"
Add an field to the table.  Returns the newly created
\&\f(CW\*(C`SQL::Translator::Schema::Field\*(C'\fR object.  The "name" parameter is
required.  If you try to create a field with the same name as an
existing field, you will get an error and the field will not be created.
.PP
.Vb 5
\&  my $f1        =  $table\->add_field(
\&      name      => \*(Aqfoo_id\*(Aq,
\&      data_type => \*(Aqinteger\*(Aq,
\&      size      => 11,
\&  );
\&
\&  my $f2     =  SQL::Translator::Schema::Field\->new(
\&      name   => \*(Aqname\*(Aq,
\&      table  => $table,
\&  );
\&  $f2 = $table\->add_field( $field2 ) or die $table\->error;
.Ve
.SS drop_field
.IX Subsection "drop_field"
Remove a field from the table. Returns the field object if the field was
found and removed, an error otherwise. The single parameter can be either
a field name or an \f(CW\*(C`SQL::Translator::Schema::Field\*(C'\fR object.
.PP
.Vb 1
\&  $table\->drop_field(\*(Aqmyfield\*(Aq);
.Ve
.SS comments
.IX Subsection "comments"
Get or set the comments on a table.  May be called several times to
set and it will accumulate the comments.  Called in an array context,
returns each comment individually; called in a scalar context, returns
all the comments joined on newlines.
.PP
.Vb 3
\&  $table\->comments(\*(Aqfoo\*(Aq);
\&  $table\->comments(\*(Aqbar\*(Aq);
\&  print join( \*(Aq, \*(Aq, $table\->comments ); # prints "foo, bar"
.Ve
.SS get_constraints
.IX Subsection "get_constraints"
Returns all the constraint objects as an array or array reference.
.PP
.Vb 1
\&  my @constraints = $table\->get_constraints;
.Ve
.SS get_indices
.IX Subsection "get_indices"
Returns all the index objects as an array or array reference.
.PP
.Vb 1
\&  my @indices = $table\->get_indices;
.Ve
.SS get_field
.IX Subsection "get_field"
Returns a field by the name provided.
.PP
.Vb 1
\&  my $field = $table\->get_field(\*(Aqfoo\*(Aq);
.Ve
.SS get_fields
.IX Subsection "get_fields"
Returns all the field objects as an array or array reference.
.PP
.Vb 1
\&  my @fields = $table\->get_fields;
.Ve
.SS is_valid
.IX Subsection "is_valid"
Determine whether the view is valid or not.
.PP
.Vb 1
\&  my $ok = $view\->is_valid;
.Ve
.SS is_trivial_link
.IX Subsection "is_trivial_link"
True if table has no data (non-key) fields and only uses single key joins.
.SS is_data
.IX Subsection "is_data"
Returns true if the table has some non-key fields.
.SS can_link
.IX Subsection "can_link"
Determine whether the table can link two arg tables via many-to-many.
.PP
.Vb 1
\&  my $ok = $table\->can_link($table1,$table2);
.Ve
.SS name
.IX Subsection "name"
Get or set the table's name.
.PP
Errors ("No table name") if you try to set a blank name.
.PP
If provided an argument, checks the schema object for a table of
that name and disallows the change if one exists (setting the error to
"Can't use table name "%s": table exists").
.PP
.Vb 1
\&  my $table_name = $table\->name(\*(Aqfoo\*(Aq);
.Ve
.SS schema
.IX Subsection "schema"
Get or set the table's schema object.
.PP
.Vb 1
\&  my $schema = $table\->schema;
.Ve
.SS primary_key
.IX Subsection "primary_key"
Gets or sets the table's primary key(s).  Takes one or more field
names (as a string, list or array[ref]) as an argument.  If the field
names are present, it will create a new PK if none exists, or it will
add to the fields of an existing PK (and will unique the field names).
Returns the \f(CW\*(C`SQL::Translator::Schema::Constraint\*(C'\fR object representing
the primary key.
.PP
These are equivalent:
.PP
.Vb 6
\&  $table\->primary_key(\*(Aqid\*(Aq);
\&  $table\->primary_key([\*(Aqname\*(Aq]);
\&  $table\->primary_key(\*(Aqid\*(Aq,\*(Aqname\*(Aq]);
\&  $table\->primary_key([\*(Aqid\*(Aq,\*(Aqname\*(Aq]);
\&  $table\->primary_key(\*(Aqid,name\*(Aq);
\&  $table\->primary_key(qw[ id name ]);
\&
\&  my $pk = $table\->primary_key;
.Ve
.SS options
.IX Subsection "options"
Get or append to the table's options (e.g., table types for MySQL).
Returns an array or array reference.
.PP
.Vb 1
\&  my @options = $table\->options;
.Ve
.SS order
.IX Subsection "order"
Get or set the table's order.
.PP
.Vb 1
\&  my $order = $table\->order(3);
.Ve
.SS field_names
.IX Subsection "field_names"
Read-only method to return a list or array ref of the field names. Returns undef
or an empty list if the table has no fields set. Useful if you want to
avoid the overload magic of the Field objects returned by the get_fields method.
.PP
.Vb 1
\&  my @names = $constraint\->field_names;
.Ve
.SS equals
.IX Subsection "equals"
Determines if this table is the same as another
.PP
.Vb 1
\&  my $isIdentical = $table1\->equals( $table2 );
.Ve
.SH "LOOKUP METHODS"
.IX Header "LOOKUP METHODS"
The following are a set of shortcut methods for getting commonly used lists of
fields and constraints. They all return lists or array refs of Field or
Constraint objects.
.IP pkey_fields 4
.IX Item "pkey_fields"
The primary key fields.
.IP fkey_fields 4
.IX Item "fkey_fields"
All foreign key fields.
.IP nonpkey_fields 4
.IX Item "nonpkey_fields"
All the fields except the primary key.
.IP data_fields 4
.IX Item "data_fields"
All non key fields.
.IP unique_fields 4
.IX Item "unique_fields"
All fields with unique constraints.
.IP unique_constraints 4
.IX Item "unique_constraints"
All this tables unique constraints.
.IP fkey_constraints 4
.IX Item "fkey_constraints"
All this tables foreign key constraints. (See primary_key method to get the
primary key constraint)
.SH AUTHORS
.IX Header "AUTHORS"
Ken Youens-Clark <kclark@cpan.org>,
Allen Day <allenday@ucla.edu>.