[dbsrgits/SQL-Translator.git] / lib / SQL / Translator / Schema / Table.pm

package SQL::Translator::Schema::Table;

# ----------------------------------------------------------------------
# $Id: Table.pm,v 1.16 2003-08-29 08:00:51 allenday Exp $
# ----------------------------------------------------------------------
# Copyright (C) 2003 Ken Y. Clark <kclark@cpan.org>
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License as
# published by the Free Software Foundation; version 2.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
# 02111-1307  USA
# -------------------------------------------------------------------

=pod

=head1 NAME

SQL::Translator::Schema::Table - SQL::Translator table object

=head1 SYNOPSIS

  use SQL::Translator::Schema::Table;
  my $table = SQL::Translator::Schema::Table->new( name => 'foo' );

=head1 DESCSIPTION

C<SQL::Translator::Schema::Table> is the table object.

=head1 METHODS

=cut

use strict;
use Class::Base;
use SQL::Translator::Utils 'parse_list_arg';
use SQL::Translator::Schema::Constants;
use SQL::Translator::Schema::Constraint;
use SQL::Translator::Schema::Field;
use SQL::Translator::Schema::Index;
use Data::Dumper;

use base 'Class::Base';
use vars qw( $VERSION $FIELD_ORDER );

$VERSION = sprintf "%d.%02d", q$Revision: 1.16 $ =~ /(\d+)\.(\d+)/;

# ----------------------------------------------------------------------
sub init {

=pod

=head2 new

Object constructor.

  my $table  =  SQL::Translator::Schema::Table->new( 
      schema => $schema,
      name   => 'foo',
  );

=cut

    my ( $self, $config ) = @_;
    
    for my $arg ( qw[ schema name comments ] ) {
        next unless defined $config->{ $arg };
        defined $self->$arg( $config->{ $arg } ) or return;
    }

    return $self;
}

# ----------------------------------------------------------------------
sub add_constraint {

=pod

=head2 add_constraint

Add a constraint to the table.  Returns the newly created 
C<SQL::Translator::Schema::Constraint> object.

  my $c1 = $table->add_constraint(
      name        => 'pk',
      type        => PRIMARY_KEY,
      fields      => [ 'foo_id' ],
  );

  my $c2 = SQL::Translator::Schema::Constraint->new( name => 'uniq' );
  $c2    = $table->add_constraint( $constraint );

=cut

    my $self             = shift;
    my $constraint_class = 'SQL::Translator::Schema::Constraint';
    my $constraint;

    if ( UNIVERSAL::isa( $_[0], $constraint_class ) ) {
        $constraint = shift;
        $constraint->table( $self );
    }
    else {
        my %args = @_;
        $args{'table'} = $self;
        $constraint = $constraint_class->new( \%args ) or 
            return $self->error( $constraint_class->error );
    }

    #
    # If we're trying to add a PK when one is already defined,
    # then just add the fields to the existing definition.
    #
    my $ok = 1;
    my $pk = $self->primary_key;
    if ( $pk && $constraint->type eq PRIMARY_KEY ) {
        $self->primary_key( $constraint->fields );
        $constraint = $pk;
        $ok         = 0;
    }
    elsif ( $constraint->type eq PRIMARY_KEY ) {
        for my $fname ( $constraint->fields ) {
            if ( my $f = $self->get_field( $fname ) ) {
                $f->is_primary_key( 1 );
            }
        }
    }
    #
    # See if another constraint of the same type 
    # covers the same fields.
    #
    elsif ( $constraint->type ne CHECK_C ) {
        my @field_names = $constraint->fields;
        for my $c ( 
            grep { $_->type eq $constraint->type } 
            $self->get_constraints 
        ) {
            my %fields = map { $_, 1 } $c->fields;
            for my $field_name ( @field_names ) {
                if ( $fields{ $field_name } ) {
                    $constraint = $c;
                    $ok = 0; 
                    last;
                }
            }
            last unless $ok;
        }
    }

    if ( $ok ) {
        push @{ $self->{'constraints'} }, $constraint;
    }

    return $constraint;
}

# ----------------------------------------------------------------------
sub add_index {

=pod

=head2 add_index

Add an index to the table.  Returns the newly created
C<SQL::Translator::Schema::Index> object.

  my $i1 = $table->add_index(
      name   => 'name',
      fields => [ 'name' ],
      type   => 'normal',
  );

  my $i2 = SQL::Translator::Schema::Index->new( name => 'id' );
  $i2    = $table->add_index( $index );

=cut

    my $self        = shift;
    my $index_class = 'SQL::Translator::Schema::Index';
    my $index;

    if ( UNIVERSAL::isa( $_[0], $index_class ) ) {
        $index = shift;
        $index->table( $self );
    }
    else {
        my %args = @_;
        $args{'table'} = $self;
        $index = $index_class->new( \%args ) or return 
            $self->error( $index_class->error );
    }

    push @{ $self->{'indices'} }, $index;
    return $index;
}

# ----------------------------------------------------------------------
sub add_field {

=pod

=head2 add_field

Add an field to the table.  Returns the newly created
C<SQL::Translator::Schema::Field> 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.

  my $f1    =  $table->add_field(
      name      => 'foo_id',
      data_type => 'integer',
      size      => 11,
  );

  my $f2 =  SQL::Translator::Schema::Field->new( 
      name   => 'name', 
      table  => $table,
  );
  $f2    = $table->add_field( $field2 ) or die $table->error;

=cut

    my $self        = shift;
    my $field_class = 'SQL::Translator::Schema::Field';
    my $field;

    if ( UNIVERSAL::isa( $_[0], $field_class ) ) {
        $field = shift;
        $field->table( $self );
    }
    else {
        my %args = @_;
        $args{'table'} = $self;
        $field = $field_class->new( \%args ) or return 
            $self->error( $field_class->error );
    }

    $field->order( ++$FIELD_ORDER );
    my $field_name = $field->name or return $self->error('No name');

    if ( exists $self->{'fields'}{ $field_name } ) { 
        return $self->error(qq[Can\'t create field: "$field_name" exists]);
    }
    else {
        $self->{'fields'}{ $field_name } = $field;
    }

    return $field;
}

# ----------------------------------------------------------------------
sub comments {

=pod

=head2 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.

  $table->comments('foo');
  $table->comments('bar');
  print join( ', ', $table->comments ); # prints "foo, bar"

=cut

    my $self     = shift;
    my @comments = ref $_[0] ? @{ $_[0] } : @_;

    for my $arg ( @comments ) {
        $arg = $arg->[0] if ref $arg;
        push @{ $self->{'comments'} }, $arg if defined $arg && $arg;
    }

    if ( @{ $self->{'comments'} || [] } ) {
        return wantarray 
            ? @{ $self->{'comments'} }
            : join( "\n", @{ $self->{'comments'} } )
        ;
    } 
    else {
        return wantarray ? () : undef;
    }
}

# ----------------------------------------------------------------------
sub get_constraints {

=pod

=head2 get_constraints

Returns all the constraint objects as an array or array reference.

  my @constraints = $table->get_constraints;

=cut

    my $self = shift;

    if ( ref $self->{'constraints'} ) {
        return wantarray 
            ? @{ $self->{'constraints'} } : $self->{'constraints'};
    }
    else {
        $self->error('No constraints');
        return wantarray ? () : undef;
    }
}

# ----------------------------------------------------------------------
sub get_indices {

=pod

=head2 get_indices

Returns all the index objects as an array or array reference.

  my @indices = $table->get_indices;

=cut

    my $self = shift;

    if ( ref $self->{'indices'} ) {
        return wantarray 
            ? @{ $self->{'indices'} } 
            : $self->{'indices'};
    }
    else {
        $self->error('No indices');
        return wantarray ? () : undef;
    }
}

# ----------------------------------------------------------------------
sub get_field {

=pod

=head2 get_field

Returns a field by the name provided.

  my $field = $table->get_field('foo');

=cut

    my $self       = shift;
    my $field_name = shift or return $self->error('No field name');
    return $self->error( qq[Field "$field_name" does not exist] ) unless
        exists $self->{'fields'}{ $field_name };
    return $self->{'fields'}{ $field_name };
}

# ----------------------------------------------------------------------
sub get_fields {

=pod

=head2 get_fields

Returns all the field objects as an array or array reference.

  my @fields = $table->get_fields;

=cut

    my $self = shift;
    my @fields = 
        map  { $_->[1] }
        sort { $a->[0] <=> $b->[0] }
        map  { [ $_->order, $_ ] }
        values %{ $self->{'fields'} || {} };

    if ( @fields ) {
        return wantarray ? @fields : \@fields;
    }
    else {
        $self->error('No fields');
        return wantarray ? () : undef;
    }
}

# ----------------------------------------------------------------------
sub is_valid {

=pod

=head2 is_valid

Determine whether the view is valid or not.

  my $ok = $view->is_valid;

=cut

    my $self = shift;
    return $self->error('No name')   unless $self->name;
    return $self->error('No fields') unless $self->get_fields;

    for my $object ( 
        $self->get_fields, $self->get_indices, $self->get_constraints 
    ) {
        return $object->error unless $object->is_valid;
    }

    return 1;
}

sub is_data {
  my $self = shift;
  return $self->{'is_data'} if defined $self->{'is_data'};

  $self->{'is_data'} = 0;

  foreach my $field ($self->get_fields){
	if(!$field->is_primary_key and !$field->is_foreign_key){
	  $self->{'is_data'} = 1;
	  return $self->{'is_data'}
	}
  }

  return $self->{'is_data'};
}

sub can_link {

=pod

=head2 can_link

Determine whether the table can link two arg tables via many-to-many.

  my $ok = $table->can_link($table1,$table2);

=cut

  my($self,$table1,$table2) = @_;

  return $self->{'can_link'}{$table1->name}{$table2->name} if defined $self->{'can_link'}{$table1->name}{$table2->name};

  if($self->is_data == 1){
	$self->{'can_link'}{$table1->name}{$table2->name} = [0];
	$self->{'can_link'}{$table2->name}{$table1->name} = [0];
	return $self->{'can_link'}{$table1->name}{$table2->name};
  }

  my %fk = ();

  foreach my $field ($self->get_fields){
	#if the table has non-key fields, it can't be a link
	if(!$field->is_primary_key and !$field->is_foreign_key){
	  $self->{'can_link'}{$table1->name}{$table2->name} = [0];
	  $self->{'can_link'}{$table2->name}{$table1->name} = [0];
	  return $self->{'can_link'}{$table1->name}{$table2->name};

	#otherwise, count up how many fields refer to each FK table.field
	} elsif($field->is_foreign_key){
	  push @{ $fk{$field->foreign_key_reference->reference_table->name} }, $field->foreign_key_reference;
	}
  }

  #trivial traversal, only one way to link the two tables
  if(scalar($fk{ $table1->name } == 1)
	 and
	 scalar($fk{ $table2->name } == 1)
	){
	$self->{'can_link'}{$table1->name}{$table2->name} = ['one2one', $fk{$table1->name}, $fk{$table2->name}];
	$self->{'can_link'}{$table1->name}{$table2->name} = ['one2one', $fk{$table2->name}, $fk{$table1->name}];

  #non-trivial traversal.  one way to link table2, many ways to link table1
  } elsif(scalar($fk{ $table1->name }  > 1)
		  and
		  scalar($fk{ $table2->name } == 1)
		 ){
	$self->{'can_link'}{$table1->name}{$table2->name} = ['many2one', $fk{$table1->name}, $fk{$table2->name}];
	$self->{'can_link'}{$table2->name}{$table1->name} = ['one2many', $fk{$table2->name}, $fk{$table1->name}];

  #non-trivial traversal.  one way to link table1, many ways to link table2
  } elsif(scalar($fk{ $table1->name } == 1)
		  and
		  scalar($fk{ $table2->name }  > 1)
		 ){
	$self->{'can_link'}{$table1->name}{$table2->name} = ['one2many', $fk{$table1->name}, $fk{$table2->name}];
	$self->{'can_link'}{$table2->name}{$table1->name} = ['many2one', $fk{$table2->name}, $fk{$table1->name}];

  #non-trivial traversal.  many ways to link table1 and table2
  } elsif(scalar($fk{ $table1->name }  > 1)
		  and
		  scalar($fk{ $table2->name }  > 1)
		 ){
	$self->{'can_link'}{$table1->name}{$table2->name} = ['many2many', $fk{$table1->name}, $fk{$table2->name}];
	$self->{'can_link'}{$table2->name}{$table1->name} = ['many2many', $fk{$table2->name}, $fk{$table1->name}];

  #one of the tables didn't export a key to this table, no linking possible
  } else {
	$self->{'can_link'}{$table1->name}{$table2->name} = [0];
	$self->{'can_link'}{$table2->name}{$table1->name} = [0];
  }

  return $self->{'can_link'}{$table1->name}{$table2->name};
}

# ----------------------------------------------------------------------
sub name {

=pod

=head2 name

Get or set the table\'s name.

If provided an argument, checks the schema object for a table of 
that name and disallows the change if one exists.

  my $table_name = $table->name('foo');

=cut

    my $self = shift;

    if ( my $arg = shift ) {
        if ( my $schema = $self->schema ) {
            return $self->error( qq[Can\'t use table name "$arg": table exists] )
                if $schema->get_table( $arg );
        }
        $self->{'name'} = $arg;
    }

    return $self->{'name'} || '';
}

# ----------------------------------------------------------------------
sub schema {

=pod

=head2 schema

Get or set the table\'s schema object.

  my $schema = $table->schema;

=cut

    my $self = shift;
    if ( my $arg = shift ) {
        return $self->error('Not a schema object') unless
            UNIVERSAL::isa( $arg, 'SQL::Translator::Schema' );
        $self->{'schema'} = $arg;
    }

    return $self->{'schema'};
}

# ----------------------------------------------------------------------
sub primary_key {

=pod

=head2 options

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 C<SQL::Translator::Schema::Constraint> object representing
the primary key.

These are eqivalent:

  $table->primary_key('id');
  $table->primary_key(['name']);
  $table->primary_key('id','name']);
  $table->primary_key(['id','name']);
  $table->primary_key('id,name');
  $table->primary_key(qw[ id name ]);

  my $pk = $table->primary_key;

=cut

    my $self   = shift;
    my $fields = parse_list_arg( @_ );

    my $constraint;
    if ( @$fields ) {
        for my $f ( @$fields ) {
            return $self->error(qq[Invalid field "$f"]) unless 
                $self->get_field($f);
        }

        my $has_pk;
        for my $c ( $self->get_constraints ) {
            if ( $c->type eq PRIMARY_KEY ) {
                $has_pk = 1;
                $c->fields( @{ $c->fields }, @$fields );
                $constraint = $c;
            } 
        }

        unless ( $has_pk ) {
            $constraint = $self->add_constraint(
                type   => PRIMARY_KEY,
                fields => $fields,
            ) or return;
        }
    }

    if ( $constraint ) {
        return $constraint;
    }
    else {
        for my $c ( $self->get_constraints ) {
            return $c if $c->type eq PRIMARY_KEY;
        }
    }

    return;
}

# ----------------------------------------------------------------------
sub options {

=pod

=head2 options

Get or set the table\'s options (e.g., table types for MySQL).  Returns
an array or array reference.

  my @options = $table->options;

=cut

    my $self    = shift;
    my $options = parse_list_arg( @_ );

    push @{ $self->{'options'} }, @$options;

    if ( ref $self->{'options'} ) {
        return wantarray ? @{ $self->{'options'} || [] } : $self->{'options'};
    }
    else {
        return wantarray ? () : [];
    }
}

# ----------------------------------------------------------------------
sub order {

=pod

=head2 order

Get or set the table\'s order.

  my $order = $table->order(3);

=cut

    my ( $self, $arg ) = @_;

    if ( defined $arg && $arg =~ /^\d+$/ ) {
        $self->{'order'} = $arg;
    }

    return $self->{'order'} || 0;
}

# ----------------------------------------------------------------------
sub DESTROY {
    my $self = shift;
    undef $self->{'schema'}; # destroy cyclical reference
    undef $_ for @{ $self->{'constraints'} };
    undef $_ for @{ $self->{'indices'} };
    undef $_ for values %{ $self->{'fields'} };
}

1;

# ----------------------------------------------------------------------

=pod

=head1 AUTHOR

Ken Y. Clark E<lt>kclark@cpan.orgE<gt>

=cut
Commit	Line	Data
3c5de62a	1	package SQL::Translator::Schema::Table;
	2
	3	# ----------------------------------------------------------------------
c8515c9f	4	# $Id: Table.pm,v 1.16 2003-08-29 08:00:51 allenday Exp $
3c5de62a	5	# ----------------------------------------------------------------------
	6	# Copyright (C) 2003 Ken Y. Clark <kclark@cpan.org>
	7	#
	8	# This program is free software; you can redistribute it and/or
	9	# modify it under the terms of the GNU General Public License as
	10	# published by the Free Software Foundation; version 2.
	11	#
	12	# This program is distributed in the hope that it will be useful, but
	13	# WITHOUT ANY WARRANTY; without even the implied warranty of
	14	# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	15	# General Public License for more details.
	16	#
	17	# You should have received a copy of the GNU General Public License
	18	# along with this program; if not, write to the Free Software
	19	# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
	20	# 02111-1307 USA
	21	# -------------------------------------------------------------------
	22
	23	=pod
	24
	25	=head1 NAME
	26
	27	SQL::Translator::Schema::Table - SQL::Translator table object
	28
	29	=head1 SYNOPSIS
	30
	31	use SQL::Translator::Schema::Table;
0f3cc5c0	32	my $table = SQL::Translator::Schema::Table->new( name => 'foo' );
3c5de62a	33
	34	=head1 DESCSIPTION
	35
	36	C<SQL::Translator::Schema::Table> is the table object.
	37
	38	=head1 METHODS
	39
	40	=cut
	41
	42	use strict;
	43	use Class::Base;
30f4ec44	44	use SQL::Translator::Utils 'parse_list_arg';
0f3cc5c0	45	use SQL::Translator::Schema::Constants;
3c5de62a	46	use SQL::Translator::Schema::Constraint;
	47	use SQL::Translator::Schema::Field;
	48	use SQL::Translator::Schema::Index;
c8515c9f	49	use Data::Dumper;
3c5de62a	50
3c5de62a	51	use base 'Class::Base';
0f3cc5c0	52	use vars qw( $VERSION $FIELD_ORDER );
3c5de62a	53
c8515c9f	54	$VERSION = sprintf "%d.%02d", q$Revision: 1.16 $ =~ /(\d+)\.(\d+)/;
3c5de62a	55
	56	# ----------------------------------------------------------------------
	57	sub init {
	58
	59	=pod
	60
	61	=head2 new
	62
	63	Object constructor.
	64
43b9dc7a	65	my $table = SQL::Translator::Schema::Table->new(
	66	schema => $schema,
	67	name => 'foo',
	68	);
3c5de62a	69
	70	=cut
	71
	72	my ( $self, $config ) = @_;
43b9dc7a	73
88b8377e	74	for my $arg ( qw[ schema name comments ] ) {
43b9dc7a	75	next unless defined $config->{ $arg };
88b8377e	76	defined $self->$arg( $config->{ $arg } ) or return;
43b9dc7a	77	}
43b9dc7a	78
3c5de62a	79	return $self;
	80	}
	81
	82	# ----------------------------------------------------------------------
3c5de62a	83	sub add_constraint {
	84
	85	=pod
	86
	87	=head2 add_constraint
	88
0f3cc5c0	89	Add a constraint to the table. Returns the newly created
0f3cc5c0	90	C<SQL::Translator::Schema::Constraint> object.
3c5de62a	91
dfdb0568	92	my $c1 = $table->add_constraint(
43b9dc7a	93	name => 'pk',
	94	type => PRIMARY_KEY,
	95	fields => [ 'foo_id' ],
3c5de62a	96	);
3c5de62a	97
dfdb0568	98	my $c2 = SQL::Translator::Schema::Constraint->new( name => 'uniq' );
dfdb0568	99	$c2 = $table->add_constraint( $constraint );
43b9dc7a	100
3c5de62a	101	=cut
3c5de62a	102
43b9dc7a	103	my $self = shift;
	104	my $constraint_class = 'SQL::Translator::Schema::Constraint';
	105	my $constraint;
	106
	107	if ( UNIVERSAL::isa( $_[0], $constraint_class ) ) {
	108	$constraint = shift;
	109	$constraint->table( $self );
	110	}
	111	else {
	112	my %args = @_;
	113	$args{'table'} = $self;
	114	$constraint = $constraint_class->new( \%args ) or
	115	return $self->error( $constraint_class->error );
	116	}
	117
dfdb0568	118	#
	119	# If we're trying to add a PK when one is already defined,
	120	# then just add the fields to the existing definition.
	121	#
3dd9026c	122	my $ok = 1;
dfdb0568	123	my $pk = $self->primary_key;
	124	if ( $pk && $constraint->type eq PRIMARY_KEY ) {
	125	$self->primary_key( $constraint->fields );
	126	$constraint = $pk;
3dd9026c	127	$ok = 0;
dfdb0568	128	}
2ccf2299	129	elsif ( $constraint->type eq PRIMARY_KEY ) {
	130	for my $fname ( $constraint->fields ) {
	131	if ( my $f = $self->get_field( $fname ) ) {
	132	$f->is_primary_key( 1 );
	133	}
	134	}
	135	}
3dd9026c	136	#
	137	# See if another constraint of the same type
	138	# covers the same fields.
	139	#
	140	elsif ( $constraint->type ne CHECK_C ) {
dfdb0568	141	my @field_names = $constraint->fields;
dfdb0568	142	for my $c (
	143	grep { $_->type eq $constraint->type }
	144	$self->get_constraints
	145	) {
	146	my %fields = map { $_, 1 } $c->fields;
	147	for my $field_name ( @field_names ) {
	148	if ( $fields{ $field_name } ) {
	149	$constraint = $c;
	150	$ok = 0;
	151	last;
	152	}
	153	}
	154	last unless $ok;
	155	}
	156	}
	157
	158	if ( $ok ) {
	159	push @{ $self->{'constraints'} }, $constraint;
	160	}
	161
3c5de62a	162	return $constraint;
	163	}
	164
	165	# ----------------------------------------------------------------------
	166	sub add_index {
	167
	168	=pod
	169
	170	=head2 add_index
	171
0f3cc5c0	172	Add an index to the table. Returns the newly created
0f3cc5c0	173	C<SQL::Translator::Schema::Index> object.
3c5de62a	174
dfdb0568	175	my $i1 = $table->add_index(
3c5de62a	176	name => 'name',
	177	fields => [ 'name' ],
	178	type => 'normal',
	179	);
	180
dfdb0568	181	my $i2 = SQL::Translator::Schema::Index->new( name => 'id' );
dfdb0568	182	$i2 = $table->add_index( $index );
43b9dc7a	183
3c5de62a	184	=cut
3c5de62a	185
43b9dc7a	186	my $self = shift;
	187	my $index_class = 'SQL::Translator::Schema::Index';
	188	my $index;
	189
	190	if ( UNIVERSAL::isa( $_[0], $index_class ) ) {
	191	$index = shift;
	192	$index->table( $self );
	193	}
	194	else {
	195	my %args = @_;
	196	$args{'table'} = $self;
	197	$index = $index_class->new( \%args ) or return
	198	$self->error( $index_class->error );
	199	}
	200
3c5de62a	201	push @{ $self->{'indices'} }, $index;
	202	return $index;
	203	}
	204
	205	# ----------------------------------------------------------------------
	206	sub add_field {
	207
	208	=pod
	209
	210	=head2 add_field
	211
43b9dc7a	212	Add an field to the table. Returns the newly created
	213	C<SQL::Translator::Schema::Field> object. The "name" parameter is
	214	required. If you try to create a field with the same name as an
	215	existing field, you will get an error and the field will not be created.
3c5de62a	216
dfdb0568	217	my $f1 = $table->add_field(
0f3cc5c0	218	name => 'foo_id',
	219	data_type => 'integer',
	220	size => 11,
3c5de62a	221	);
3c5de62a	222
dfdb0568	223	my $f2 = SQL::Translator::Schema::Field->new(
43b9dc7a	224	name => 'name',
	225	table => $table,
	226	);
dfdb0568	227	$f2 = $table->add_field( $field2 ) or die $table->error;
43b9dc7a	228
3c5de62a	229	=cut
3c5de62a	230
dfdb0568	231	my $self = shift;
43b9dc7a	232	my $field_class = 'SQL::Translator::Schema::Field';
	233	my $field;
	234
	235	if ( UNIVERSAL::isa( $_[0], $field_class ) ) {
	236	$field = shift;
	237	$field->table( $self );
	238	}
	239	else {
	240	my %args = @_;
	241	$args{'table'} = $self;
	242	$field = $field_class->new( \%args ) or return
	243	$self->error( $field_class->error );
	244	}
	245
30f4ec44	246	$field->order( ++$FIELD_ORDER );
43b9dc7a	247	my $field_name = $field->name or return $self->error('No name');
	248
	249	if ( exists $self->{'fields'}{ $field_name } ) {
69c7a62f	250	return $self->error(qq[Can\'t create field: "$field_name" exists]);
43b9dc7a	251	}
	252	else {
	253	$self->{'fields'}{ $field_name } = $field;
43b9dc7a	254	}
43b9dc7a	255
3c5de62a	256	return $field;
	257	}
	258
	259	# ----------------------------------------------------------------------
88b8377e	260	sub comments {
	261
	262	=pod
	263
	264	=head2 comments
	265
	266	Get or set the comments on a table. May be called several times to
	267	set and it will accumulate the comments. Called in an array context,
	268	returns each comment individually; called in a scalar context, returns
	269	all the comments joined on newlines.
	270
	271	$table->comments('foo');
	272	$table->comments('bar');
	273	print join( ', ', $table->comments ); # prints "foo, bar"
	274
	275	=cut
	276
eb3b8ae4	277	my $self = shift;
eb3b8ae4	278	my @comments = ref $_[0] ? @{ $_[0] } : @_;
b891fb49	279
eb3b8ae4	280	for my $arg ( @comments ) {
b891fb49	281	$arg = $arg->[0] if ref $arg;
eb3b8ae4	282	push @{ $self->{'comments'} }, $arg if defined $arg && $arg;
b891fb49	283	}
88b8377e	284
eb3b8ae4	285	if ( @{ $self->{'comments'} \|\| [] } ) {
	286	return wantarray
	287	? @{ $self->{'comments'} }
	288	: join( "\n", @{ $self->{'comments'} } )
	289	;
	290	}
	291	else {
	292	return wantarray ? () : undef;
	293	}
88b8377e	294	}
	295
	296	# ----------------------------------------------------------------------
0f3cc5c0	297	sub get_constraints {
	298
	299	=pod
	300
	301	=head2 get_constraints
	302
	303	Returns all the constraint objects as an array or array reference.
	304
	305	my @constraints = $table->get_constraints;
	306
	307	=cut
	308
	309	my $self = shift;
	310
	311	if ( ref $self->{'constraints'} ) {
	312	return wantarray
	313	? @{ $self->{'constraints'} } : $self->{'constraints'};
	314	}
	315	else {
	316	$self->error('No constraints');
	317	return wantarray ? () : undef;
	318	}
	319	}
	320
	321	# ----------------------------------------------------------------------
	322	sub get_indices {
3c5de62a	323
	324	=pod
	325
0f3cc5c0	326	=head2 get_indices
3c5de62a	327
0f3cc5c0	328	Returns all the index objects as an array or array reference.
3c5de62a	329
0f3cc5c0	330	my @indices = $table->get_indices;
3c5de62a	331
	332	=cut
	333
	334	my $self = shift;
0f3cc5c0	335
	336	if ( ref $self->{'indices'} ) {
	337	return wantarray
	338	? @{ $self->{'indices'} }
	339	: $self->{'indices'};
	340	}
	341	else {
	342	$self->error('No indices');
	343	return wantarray ? () : undef;
	344	}
	345	}
	346
	347	# ----------------------------------------------------------------------
43b9dc7a	348	sub get_field {
	349
	350	=pod
	351
	352	=head2 get_field
	353
	354	Returns a field by the name provided.
	355
	356	my $field = $table->get_field('foo');
	357
	358	=cut
	359
	360	my $self = shift;
	361	my $field_name = shift or return $self->error('No field name');
	362	return $self->error( qq[Field "$field_name" does not exist] ) unless
	363	exists $self->{'fields'}{ $field_name };
	364	return $self->{'fields'}{ $field_name };
	365	}
	366
	367	# ----------------------------------------------------------------------
0f3cc5c0	368	sub get_fields {
	369
	370	=pod
	371
	372	=head2 get_fields
	373
	374	Returns all the field objects as an array or array reference.
	375
	376	my @fields = $table->get_fields;
	377
	378	=cut
	379
	380	my $self = shift;
	381	my @fields =
30f4ec44	382	map { $_->[1] }
	383	sort { $a->[0] <=> $b->[0] }
	384	map { [ $_->order, $_ ] }
0f3cc5c0	385	values %{ $self->{'fields'} \|\| {} };
	386
	387	if ( @fields ) {
	388	return wantarray ? @fields : \@fields;
	389	}
	390	else {
	391	$self->error('No fields');
	392	return wantarray ? () : undef;
	393	}
3c5de62a	394	}
	395
	396	# ----------------------------------------------------------------------
	397	sub is_valid {
	398
	399	=pod
	400
	401	=head2 is_valid
	402
	403	Determine whether the view is valid or not.
	404
	405	my $ok = $view->is_valid;
	406
	407	=cut
	408
	409	my $self = shift;
43b9dc7a	410	return $self->error('No name') unless $self->name;
0f3cc5c0	411	return $self->error('No fields') unless $self->get_fields;
	412
	413	for my $object (
	414	$self->get_fields, $self->get_indices, $self->get_constraints
	415	) {
	416	return $object->error unless $object->is_valid;
	417	}
	418
	419	return 1;
3c5de62a	420	}
3c5de62a	421
69c7a62f	422	sub is_data {
	423	my $self = shift;
	424	return $self->{'is_data'} if defined $self->{'is_data'};
	425
	426	$self->{'is_data'} = 0;
	427
	428	foreach my $field ($self->get_fields){
c8515c9f	429	if(!$field->is_primary_key and !$field->is_foreign_key){
69c7a62f	430	$self->{'is_data'} = 1;
	431	return $self->{'is_data'}
	432	}
	433	}
	434
	435	return $self->{'is_data'};
	436	}
	437
	438	sub can_link {
	439
	440	=pod
	441
	442	=head2 can_link
	443
	444	Determine whether the table can link two arg tables via many-to-many.
	445
	446	my $ok = $table->can_link($table1,$table2);
	447
	448	=cut
	449
	450	my($self,$table1,$table2) = @_;
	451
69c7a62f	452	return $self->{'can_link'}{$table1->name}{$table2->name} if defined $self->{'can_link'}{$table1->name}{$table2->name};
	453
	454	if($self->is_data == 1){
c8515c9f	455	$self->{'can_link'}{$table1->name}{$table2->name} = [0];
c8515c9f	456	$self->{'can_link'}{$table2->name}{$table1->name} = [0];
69c7a62f	457	return $self->{'can_link'}{$table1->name}{$table2->name};
	458	}
	459
	460	my %fk = ();
	461
	462	foreach my $field ($self->get_fields){
	463	#if the table has non-key fields, it can't be a link
c8515c9f	464	if(!$field->is_primary_key and !$field->is_foreign_key){
	465	$self->{'can_link'}{$table1->name}{$table2->name} = [0];
	466	$self->{'can_link'}{$table2->name}{$table1->name} = [0];
69c7a62f	467	return $self->{'can_link'}{$table1->name}{$table2->name};
	468
	469	#otherwise, count up how many fields refer to each FK table.field
	470	} elsif($field->is_foreign_key){
c8515c9f	471	push @{ $fk{$field->foreign_key_reference->reference_table->name} }, $field->foreign_key_reference;
69c7a62f	472	}
	473	}
	474
c8515c9f	475	#trivial traversal, only one way to link the two tables
c8515c9f	476	if(scalar($fk{ $table1->name } == 1)
69c7a62f	477	and
c8515c9f	478	scalar($fk{ $table2->name } == 1)
69c7a62f	479	){
c8515c9f	480	$self->{'can_link'}{$table1->name}{$table2->name} = ['one2one', $fk{$table1->name}, $fk{$table2->name}];
	481	$self->{'can_link'}{$table1->name}{$table2->name} = ['one2one', $fk{$table2->name}, $fk{$table1->name}];
	482
	483	#non-trivial traversal. one way to link table2, many ways to link table1
	484	} elsif(scalar($fk{ $table1->name } > 1)
	485	and
	486	scalar($fk{ $table2->name } == 1)
	487	){
	488	$self->{'can_link'}{$table1->name}{$table2->name} = ['many2one', $fk{$table1->name}, $fk{$table2->name}];
	489	$self->{'can_link'}{$table2->name}{$table1->name} = ['one2many', $fk{$table2->name}, $fk{$table1->name}];
	490
	491	#non-trivial traversal. one way to link table1, many ways to link table2
	492	} elsif(scalar($fk{ $table1->name } == 1)
	493	and
	494	scalar($fk{ $table2->name } > 1)
	495	){
	496	$self->{'can_link'}{$table1->name}{$table2->name} = ['one2many', $fk{$table1->name}, $fk{$table2->name}];
	497	$self->{'can_link'}{$table2->name}{$table1->name} = ['many2one', $fk{$table2->name}, $fk{$table1->name}];
	498
	499	#non-trivial traversal. many ways to link table1 and table2
	500	} elsif(scalar($fk{ $table1->name } > 1)
	501	and
	502	scalar($fk{ $table2->name } > 1)
	503	){
	504	$self->{'can_link'}{$table1->name}{$table2->name} = ['many2many', $fk{$table1->name}, $fk{$table2->name}];
	505	$self->{'can_link'}{$table2->name}{$table1->name} = ['many2many', $fk{$table2->name}, $fk{$table1->name}];
	506
	507	#one of the tables didn't export a key to this table, no linking possible
69c7a62f	508	} else {
c8515c9f	509	$self->{'can_link'}{$table1->name}{$table2->name} = [0];
c8515c9f	510	$self->{'can_link'}{$table2->name}{$table1->name} = [0];
69c7a62f	511	}
	512
	513	return $self->{'can_link'}{$table1->name}{$table2->name};
	514	}
	515
43b9dc7a	516	# ----------------------------------------------------------------------
dfdb0568	517	sub name {
	518
	519	=pod
	520
	521	=head2 name
	522
69c7a62f	523	Get or set the table\'s name.
dfdb0568	524
	525	If provided an argument, checks the schema object for a table of
	526	that name and disallows the change if one exists.
	527
	528	my $table_name = $table->name('foo');
	529
	530	=cut
	531
	532	my $self = shift;
	533
	534	if ( my $arg = shift ) {
	535	if ( my $schema = $self->schema ) {
69c7a62f	536	return $self->error( qq[Can\'t use table name "$arg": table exists] )
dfdb0568	537	if $schema->get_table( $arg );
	538	}
	539	$self->{'name'} = $arg;
	540	}
	541
	542	return $self->{'name'} \|\| '';
	543	}
	544
	545	# ----------------------------------------------------------------------
43b9dc7a	546	sub schema {
	547
	548	=pod
	549
	550	=head2 schema
	551
69c7a62f	552	Get or set the table\'s schema object.
43b9dc7a	553
	554	my $schema = $table->schema;
	555
	556	=cut
	557
	558	my $self = shift;
	559	if ( my $arg = shift ) {
	560	return $self->error('Not a schema object') unless
	561	UNIVERSAL::isa( $arg, 'SQL::Translator::Schema' );
	562	$self->{'schema'} = $arg;
	563	}
	564
	565	return $self->{'schema'};
	566	}
	567
	568	# ----------------------------------------------------------------------
	569	sub primary_key {
	570
	571	=pod
	572
	573	=head2 options
	574
69c7a62f	575	Gets or sets the table\'s primary key(s). Takes one or more field
5e84ac85	576	names (as a string, list or array[ref]) as an argument. If the field
	577	names are present, it will create a new PK if none exists, or it will
	578	add to the fields of an existing PK (and will unique the field names).
	579	Returns the C<SQL::Translator::Schema::Constraint> object representing
	580	the primary key.
	581
	582	These are eqivalent:
43b9dc7a	583
43b9dc7a	584	$table->primary_key('id');
5e84ac85	585	$table->primary_key(['name']);
5e84ac85	586	$table->primary_key('id','name']);
43b9dc7a	587	$table->primary_key(['id','name']);
	588	$table->primary_key('id,name');
	589	$table->primary_key(qw[ id name ]);
	590
	591	my $pk = $table->primary_key;
	592
	593	=cut
	594
30f4ec44	595	my $self = shift;
30f4ec44	596	my $fields = parse_list_arg( @_ );
43b9dc7a	597
5e84ac85	598	my $constraint;
43b9dc7a	599	if ( @$fields ) {
	600	for my $f ( @$fields ) {
	601	return $self->error(qq[Invalid field "$f"]) unless
	602	$self->get_field($f);
	603	}
	604
	605	my $has_pk;
	606	for my $c ( $self->get_constraints ) {
	607	if ( $c->type eq PRIMARY_KEY ) {
	608	$has_pk = 1;
	609	$c->fields( @{ $c->fields }, @$fields );
5e84ac85	610	$constraint = $c;
43b9dc7a	611	}
	612	}
	613
	614	unless ( $has_pk ) {
5e84ac85	615	$constraint = $self->add_constraint(
43b9dc7a	616	type => PRIMARY_KEY,
43b9dc7a	617	fields => $fields,
88b8377e	618	) or return;
43b9dc7a	619	}
	620	}
	621
5e84ac85	622	if ( $constraint ) {
	623	return $constraint;
	624	}
	625	else {
	626	for my $c ( $self->get_constraints ) {
	627	return $c if $c->type eq PRIMARY_KEY;
	628	}
43b9dc7a	629	}
43b9dc7a	630
dfdb0568	631	return;
43b9dc7a	632	}
	633
	634	# ----------------------------------------------------------------------
	635	sub options {
	636
	637	=pod
	638
	639	=head2 options
	640
69c7a62f	641	Get or set the table\'s options (e.g., table types for MySQL). Returns
43b9dc7a	642	an array or array reference.
	643
	644	my @options = $table->options;
	645
	646	=cut
	647
	648	my $self = shift;
30f4ec44	649	my $options = parse_list_arg( @_ );
43b9dc7a	650
	651	push @{ $self->{'options'} }, @$options;
	652
	653	if ( ref $self->{'options'} ) {
	654	return wantarray ? @{ $self->{'options'} \|\| [] } : $self->{'options'};
	655	}
	656	else {
	657	return wantarray ? () : [];
	658	}
	659	}
	660
30f4ec44	661	# ----------------------------------------------------------------------
	662	sub order {
	663
	664	=pod
	665
	666	=head2 order
	667
69c7a62f	668	Get or set the table\'s order.
30f4ec44	669
	670	my $order = $table->order(3);
	671
	672	=cut
	673
	674	my ( $self, $arg ) = @_;
	675
	676	if ( defined $arg && $arg =~ /^\d+$/ ) {
	677	$self->{'order'} = $arg;
	678	}
	679
	680	return $self->{'order'} \|\| 0;
	681	}
	682
	683	# ----------------------------------------------------------------------
	684	sub DESTROY {
	685	my $self = shift;
	686	undef $self->{'schema'}; # destroy cyclical reference
	687	undef $_ for @{ $self->{'constraints'} };
	688	undef $_ for @{ $self->{'indices'} };
	689	undef $_ for values %{ $self->{'fields'} };
	690	}
	691
3c5de62a	692	1;
	693
	694	# ----------------------------------------------------------------------
	695
	696	=pod
	697
	698	=head1 AUTHOR
	699
	700	Ken Y. Clark E<lt>kclark@cpan.orgE<gt>
	701
	702	=cut