=head2 mk_group_accessors
-Creates a set of accessors in a given group.
+=over 4
+
+=item Arguments: $group, @fieldspec
+
+Returns: none
+
+=back
-=head3 Arguments: $group, @fieldspec
+Creates a set of accessors in a given group.
$group is the name of the accessor group for the generated accessors; they
will call get_$group($field) on get and set_$group($field, $value) on set.
this is used as both field and accessor name, if a listref it is expected to
be of the form [ $accessor, $field ].
-=head3 Return value: none
-
=cut
sub mk_group_accessors {
=head2 mk_group_ro_accessors
+=over 4
+
+=item Arguments: $group, @fieldspec
+
+Returns: none
+
+=back
+
Creates a set of read only accessors in a given group. Identical to
<L:/mk_group_accessors> but accessors will throw an error if passed a value
rather than setting the value.
-=head3 Arguments: $group, @fieldspec
-
-=head3 Return value: none
-
=cut
sub mk_group_ro_accessors {
=head2 mk_group_wo_accessors
+=over 4
+
+=item Arguments: $group, @fieldspec
+
+Returns: none
+
+=back
+
Creates a set of write only accessors in a given group. Identical to
<L:/mk_group_accessors> but accessors will throw an error if not passed a
value rather than getting the value.
-=head3 Arguments: $group, @fieldspec
-
-=head3 Return value: none
-
=cut
sub mk_group_wo_accessors {
=head2 make_group_accessor
-Returns a single accessor in a given group; called by mk_group_accessors
-for each entry in @fieldspec.
+=over 4
+
+=item Arguments: $group, $field
-=head3 Arguments: $group, $field
+Returns: $sub (\CODE)
-=head3 Return value: $sub (\CODE)
+=back
+
+Returns a single accessor in a given group; called by mk_group_accessors
+for each entry in @fieldspec.
=cut
=head2 make_group_ro_accessor
-Returns a single read-only accessor in a given group; called by
-mk_group_ro_accessors for each entry in @fieldspec.
+=over 4
+
+=item Arguments: $group, $field
-=head3 Arguments: $group, $field
+Returns: $sub (\CODE)
-=head3 Return value: $sub (\CODE)
+=back
+
+Returns a single read-only accessor in a given group; called by
+mk_group_ro_accessors for each entry in @fieldspec.
=cut
=head2 make_group_wo_accessor
-Returns a single write-only accessor in a given group; called by
-mk_group_wo_accessors for each entry in @fieldspec.
+=over 4
+
+=item Arguments: $group, $field
+
+Returns: $sub (\CODE)
-=head3 Arguments: $group, $field
+=back
-=head3 Return value: $sub (\CODE)
+Returns a single write-only accessor in a given group; called by
+mk_group_wo_accessors for each entry in @fieldspec.
=cut
=head2 get_simple
-Simple getter for hash-based objects which returns the value for the field
-name passed as an argument.
+=over 4
-=head3 Arguments: $field
+=item Arguments: $field
-=head3 Return value: $value
+Returns: $value
+
+=back
+
+Simple getter for hash-based objects which returns the value for the field
+name passed as an argument.
=cut
=head2 set_simple
-Simple setter for hash-based objects which sets and then returns the value
-for the field name passed as an argument.
+=over 4
+
+=item Arguments: $field, $new_value
-=head3 Arguments: $field, $new_value
+Returns: $new_value
-=head3 Return value: $new_value
+=back
+
+Simple setter for hash-based objects which sets and then returns the value
+for the field name passed as an argument.
=cut
=head2 get_component_class
+=over 4
+
+=item Arguments: $name
+
+Returns: $component_class
+
+=back
+
Returns the class name for a component; returns an object key if called on
an object, or attempts to return classdata referenced by _$name if called
on a class.
-=head3 Arguments: $name
-
-=head3 Return value: $component_class
-
=cut
sub get_component_class {
=head2 set_component_class
+=over 4
+
+=item Arguments: $name, $new_component_class
+
+Returns: $new_component_class
+
+=back
+
Sets a component class name; attempts to require the class before setting
but does not error if unable to do so. Sets an object key of the given name
if called or an object or classdata called _$name if called on a class.
-=head3 Arguments: $name, $new_component_class
-
-=head3 Return value: $new_component_class
-
=cut
sub set_component_class {
=head2 add_relationship
-=head3 Arguments: ('relname', 'Foreign::Class', $cond, $attrs)
+=over 4
+
+=item Arguments: ('relname', 'Foreign::Class', $cond, $attrs)
+
+=back
__PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
An arrayref containing a list of accessors in the foreign class to create in
the main class. If, for example, you do the following:
- MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes', undef, {
- proxy => [ qw/notes/ ],
- });
+ MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
+ undef, {
+ proxy => [ qw/notes/ ],
+ });
Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
=head2 register_relationship
-=head3 Arguments: ($relname, $rel_info)
+=over 4
+
+=item Arguments: ($relname, $rel_info)
+
+=back
Registers a relationship on the class. This is called internally by
L<DBIx::Class::ResultSourceProxy> to set up Accessors and Proxies.
sub register_relationship { }
-=head2 related_resultset($name)
+=head2 related_resultset
+
+=over 4
+
+=item Arguments: ($relationship_name)
+
+=item Returns: $related_resultset
+
+=back
- $rs = $obj->related_resultset('related_table');
+ $rs = $cd->related_resultset('artist');
-Returns a L<DBIx::Class::ResultSet> for the relationship named $name.
+Returns a L<DBIx::Class::ResultSet> for the relationship named
+$relationship_name.
=cut
Returns the count of all the items in the related resultset, restricted by the
current item or where conditions. Can be called on a
-L<DBIx::Classl::Manual::Glossary/"ResultSet"> or a
+L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
L<DBIx::Class::Manual::Glossary/"Row"> object.
=cut
my $new_obj = $obj->new_related('relname', \%col_data);
Create a new item of the related foreign class. If called on a
-L<DBIx::Class::Manual::Glossary/"Row"> object, it will magically
-set any primary key values into foreign key columns for you. The newly
-created item will not be saved into your storage until you call C<insert>
+L<DBIx::Class::Manual::Glossary/"Row"> object, it will magically set any
+primary key values into foreign key columns for you. The newly created item
+will not be saved into your storage until you call L<DBIx::Class::Row/insert>
on it.
=cut
my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
Attempt to find a related object using its primary key or unique constraints.
-See C<find> in L<DBIx::Class::ResultSet> for details.
+See L<DBIx::Class::ResultSet/find> for details.
=cut
my $new_obj = $obj->find_or_create_related('relname', \%col_data);
-Find or create an item of a related class. See C<find_or_create> in
-L<DBIx::Class::ResultSet> for details.
+Find or create an item of a related class. See
+L<DBIx::Class::ResultSet/"find_or_create"> for details.
=cut
example, to set the correct author for a book, find the Author object, then
call set_from_related on the book.
-The columns are only set in the local copy of the object, call C<update> to set
-them in the storage.
+The columns are only set in the local copy of the object, call L</update> to
+set them in the storage.
=cut
$book->update_from_related('author', $author_obj);
-As C<set_from_related>, but the changes are immediately updated onto your
-storage.
+The same as L</"set_from_related">, but the changes are immediately updated
+in storage.
=cut
=head2 new
-=head3 Arguments: ($source, \%$attrs)
+=over 4
+
+=item Arguments: ($source, \%$attrs)
+
+=back
The resultset constructor. Takes a source object (usually a
L<DBIx::Class::ResultSourceProxy::Table>) and an attribute hash (see
=head2 find
-=head3 Arguments: (@colvalues) | (\%cols, \%attrs?)
+=over 4
+
+=item Arguments: (@colvalues) | (\%cols, \%attrs?)
+
+=back
Finds a row based on its primary key or unique constraint. For example:
=head2 slice
-=head3 Arguments: ($first, $last)
+=over 4
+
+=item Arguments: ($first, $last)
+
+=back
Returns a subset of elements from the resultset.
=head2 update
-=head3 Arguments: (\%values)
+=over 4
+
+=item Arguments: (\%values)
+
+=back
Sets the specified columns in the resultset to the supplied values.
$self->throw_exception("Values for update must be a hash")
unless ref $values eq 'HASH';
return $self->result_source->storage->update(
- $self->result_source->from, $values, $self->{cond});
+ $self->result_source->from, $values, $self->{cond}
+ );
}
=head2 update_all
-=head3 Arguments: (\%values)
+=over 4
+
+=item Arguments: (\%values)
+
+=back
Fetches all objects and updates them one at a time. Note that C<update_all>
will run cascade triggers while L</update> will not.
$del->{$1} = $self->{cond}{$key};
}
}
+
} else {
$self->throw_exception(
- "Can't delete on resultset with condition unless hash or array");
+ "Can't delete on resultset with condition unless hash or array"
+ );
}
$self->result_source->storage->delete($self->result_source->from, $del);
=head2 page
-=head3 Arguments: ($page_num)
+=over 4
+
+=item Arguments: ($page_num)
+
+=back
Returns a new resultset for the specified page.
=head2 new_result
-=head3 Arguments: (\%vals)
+=over 4
+
+=item Arguments: (\%vals)
+
+=back
Creates a result in the resultset's result class.
=head2 create
-=head3 Arguments: (\%vals)
+=over 4
+
+=item Arguments: (\%vals)
+
+=back
Inserts a record into the resultset and returns the object.
=head2 find_or_create
-=head3 Arguments: (\%vals, \%attrs?)
+=over 4
+
+=item Arguments: (\%vals, \%attrs?)
+
+=back
$class->find_or_create({ key => $val, ... });
=head1 ATTRIBUTES
+XXX: FIXME: Attributes docs need clearing up
+
The resultset takes various attributes that modify its behavior. Here's an
overview of them:
=head2 columns
-=head3 Arguments: (arrayref)
+=over 4
+
+=item Arguments: (\@columns)
+
+=back
Shortcut to request a particular set of columns to be retrieved. Adds
C<me.> onto the start of any column without a C<.> in it and sets C<select>
=head2 include_columns
-=head3 Arguments: (arrayref)
+=over 4
+
+=item Arguments: (\@columns)
+
+=back
Shortcut to include additional columns in the returned results - for example
=head2 select
-=head3 Arguments: (arrayref)
+=over 4
+
+=item Arguments: (\@columns)
+
+=back
Indicates which columns should be selected from the storage. You can use
column names, or in the case of RDBMS back ends, function or stored procedure
=head2 as
-=head3 Arguments: (arrayref)
+=over 4
+
+=item Arguments: (\@names)
+
+=back
Indicates column names for object inflation. This is used in conjunction with
C<select>, usually when C<select> contains one or more function or stored
=head2 prefetch
-=head3 Arguments: arrayref/hashref
+=over 4
+
+=item Arguments: (\@relationships)
+
+=back
Contains one or more relationships that should be fetched along with the main
query (when they are accessed afterwards they will have already been
=head2 from
-=head3 Arguments: (arrayref)
+=over 4
+
+=item Arguments: (\@array)
+
+=back
The C<from> attribute gives you manual control over the C<FROM> clause of SQL
statements generated by L<DBIx::Class>, allowing you to express custom C<JOIN>
=head2 page
+=over 4
+
+=item Arguments: ($page)
+
+=back
+
For a paged resultset, specifies which page to retrieve. Leave unset
for an unpaged resultset.
=head2 rows
-For a paged resultset, how many rows per page:
+=over 4
+
+=item Arguments: ($rows)
+
+=back
+
+For a paged resultset, specifies how many rows are in each page:
rows => 10
=head2 group_by
-=head3 Arguments: (arrayref)
+=over 4
+
+=item Arguments: (\@columns)
+
+=back
A arrayref of columns to group by. Can include columns of joined tables.
=head2 set_primary_key
-=head3 Arguments: (@cols)
+=over 4
+
+=item Arguments: (@cols)
+
+=back
Defines one or more columns as primary key for this source. Should be
called after C<add_columns>.
constraint. Unique constraints are used when you call C<find> on a
L<DBIx::Class::ResultSet>, only columns in the constraint are searched,
- # For e.g. UNIQUE (column1, column2)
- __PACKAGE__->add_unique_constraint(constraint_name => [ qw/column1 column2/ ]);
+e.g.,
+
+ # For UNIQUE (column1, column2)
+ __PACKAGE__->add_unique_constraint(
+ constraint_name => [ qw/column1 column2/ ],
+ );
=cut
sub add_relationship {
my ($self, $rel, $f_source_name, $cond, $attrs) = @_;
- $self->throw_exception("Can't create relationship without join condition") unless $cond;
+ $self->throw_exception("Can't create relationship without join condition")
+ unless $cond;
$attrs ||= {};
my %rels = %{ $self->_relationships };
=head2 relationship_info
-=head3 Arguments: ($relname)
+=over 4
+
+=item Arguments: ($relname)
+
+=back
Returns the relationship information for the specified relationship name
=head2 has_relationship
-=head3 Arguments: ($rel)
+=over 4
+
+=item Arguments: ($rel)
+
+=back
Returns 1 if the source has a relationship of this name, 0 otherwise.
=head2 resolve_join
-=head3 Arguments: ($relation)
+=over 4
+
+=item Arguments: ($relation)
+
+=back
Returns the join structure required for the related result source
=head2 resolve_condition
-=head3 Arguments: ($cond, $as, $alias|$object)
+=over 4
+
+=item Arguments: ($cond, $as, $alias|$object)
+
+=back
Resolves the passed condition to a concrete query fragment. If given an alias,
returns a join condition; if given an object, inverts that object to produce
my %ret;
while (my ($k, $v) = each %{$cond}) {
# XXX should probably check these are valid columns
- $k =~ s/^foreign\.// || $self->throw_exception("Invalid rel cond key ${k}");
- $v =~ s/^self\.// || $self->throw_exception("Invalid rel cond val ${v}");
+ $k =~ s/^foreign\.// ||
+ $self->throw_exception("Invalid rel cond key ${k}");
+ $v =~ s/^self\.// ||
+ $self->throw_exception("Invalid rel cond val ${v}");
if (ref $for) { # Object
#warn "$self $k $for $v";
$ret{$k} = $for->get_column($v);
=head2 resolve_prefetch
-=head3 Arguments: (hashref/arrayref/scalar)
+=over 4
+
+=item Arguments: (hashref/arrayref/scalar)
+
+=back
Accepts one or more relationships for the current source and returns an
array of column names for each of those relationships. Column names are
=head2 related_source
-=head3 Arguments: ($relname)
+=over 4
+
+=item Arguments: ($relname)
+
+=back
Returns the result source object for the given relationship
=head2 related_class
-=head3 Arguments: ($relname)
+=over 4
+
+=item Arguments: ($relname)
+
+=back
Returns the class object for the given relationship
sub resultset {
my $self = shift;
- $self->throw_exception('resultset does not take any arguments. If you want another resultset, call it on the schema instead.') if scalar @_;
- return $self->{_resultset} if ref $self->{_resultset} eq $self->resultset_class;
- return $self->{_resultset} = $self->resultset_class->new($self, $self->{resultset_attributes});
+ $self->throw_exception(
+ 'resultset does not take any arguments. If you want another resultset, '.
+ 'call it on the schema instead.'
+ ) if scalar @_;
+ return $self->{_resultset}
+ if ref $self->{_resultset} eq $self->resultset_class;
+ return $self->{_resultset} = $self->resultset_class->new(
+ $self, $self->{resultset_attributes}
+ );
}
=head2 throw_exception
$class = ref $class if ref $class;
my $new = bless { _column_data => {} }, $class;
if ($attrs) {
- $new->throw_exception("attrs must be a hashref") unless ref($attrs) eq 'HASH';
+ $new->throw_exception("attrs must be a hashref")
+ unless ref($attrs) eq 'HASH';
while (my ($k, $v) = each %$attrs) {
- $new->throw_exception("No such column $k on $class") unless $class->has_column($k);
+ $new->throw_exception("No such column $k on $class")
+ unless $class->has_column($k);
$new->store_column($k => $v);
}
}
=head2 register_column
-=head3 Arguments: ($column, $column_info)
+=over 4
+
+=item Arguments: ($column, $column_info)
+
+=back
Registers a column on the class. If the column_info has an 'accessor' key,
creates an accessor named after the value if defined; if there is no such
=head2 register_class
-=head3 Arguments: ($moniker, $component_class)
+=over 4
+
+=item Arguments: ($moniker, $component_class)
+
+=back
Registers a class which isa L<DBIx::Class::ResultSourceProxy>. Equivalent to
calling
=head2 register_source
-=head3 Arguments: ($moniker, $result_source)
+=over 4
+
+=item Arguments: ($moniker, $result_source)
+
+=back
Registers the L<DBIx::Class::ResultSource> in the schema with the given
moniker.
=head2 class
-=head3 Arguments: ($moniker)
+=over 4
+
+=item Arguments: ($moniker)
-=head3 Returns: $classname
+=item Returns: $classname
+
+=back
Retrieves the result class name for the given moniker.
=head2 source
-=head3 Arguments: ($moniker)
+=over 4
+
+=item Arguments: ($moniker)
+
+=item Returns: $result_source
-=head3 Returns: $result_source
+=back
my $source = $schema->source('Book');
=head2 sources
-=head3 Returns: @source_monikers
+=over 4
+
+=item Returns: @source_monikers
+
+=back
Returns the source monikers of all source registrations on this schema.
=head2 resultset
-=head3 Arguments: ($moniker)
+=over 4
+
+=item Arguments: ($moniker)
-=head3 Returns: $result_set
+=item Returns: $result_set
+
+=back
my $rs = $schema->resultset('DVD');
=head2 load_classes
-=head3 Arguments: @classes?, { $namespace => [ @classes ] }+
+=over 4
+
+=item Arguments: @classes?, { $namespace => [ @classes ] }+
+
+=back
With no arguments, this method uses L<Module::Find> to find all classes under
the schema's namespace. Otherwise, this method loads the classes you specify
=head2 compose_connection
-=head3 Arguments: ($target_namespace, @db_info)
+=over 4
+
+=item Arguments: ($target_namespace, @db_info)
-=head3 Returns: $new_schema
+=item Returns: $new_schema
+
+=back
Calls L<DBIx::Class::schema/"compose_namespace"> to the target namespace,
calls L<DBIx::Class::Schema/connection>(@db_info) on the new schema, then
=head2 compose_namespace
-=head3 Arguments: $target_namespace, $additional_base_class?
+=over 4
+
+=item Arguments: $target_namespace, $additional_base_class?
-=head3 Returns: $new_schema
+=item Returns: $new_schema
+
+=back
For each L<DBIx::Class::ResultSource> in the schema, this method creates a
class in the target namespace (e.g. $target_namespace::CD,
=head2 setup_connection_class
-=head3 Arguments: ($target, @info)
+=over 4
+
+=item Arguments: ($target, @info)
+
+=back
Sets up a database connection class to inject between the schema and the
subclasses that the schema creates.
=head2 connection
-=head3 Arguments: (@args)
+=over 4
+
+=item Arguments: (@args)
-=head3 Returns: $new_schema
+=item Returns: $new_schema
+
+=back
Instantiates a new Storage object of type
L<DBIx::Class::Schema/"storage_type"> and passes the arguments to
=head2 connect
-=head3 Arguments: (@info)
+=over 4
+
+=item Arguments: (@info)
+
+=item Returns: $new_schema
-=head3 Returns: $new_schema
+=back
This is a convenience method. It is equivalent to calling
$schema->clone->connection(@info). See L</connection> and L</clone> for more
=head2 txn_do
-=head3 Arguments: (C<$coderef>, @coderef_args?)
+=over 4
+
+=item Arguments: (C<$coderef>, @coderef_args?)
+
+=item Returns: The return value of $coderef
-=head3 Returns: (C<$return_value> | C<@return_values> | C<undef>) for scalar,
-list and void contexts, respectively
+=back
Executes C<$coderef> with (optional) arguments C<@coderef_args> atomically,
returning its result (if any). If an exception is caught, a rollback is issued
=head2 clone
-=head3 Returns: $new_schema
+=over 4
+
+=item Returns: $new_schema
+
+=back
Clones the schema and its associated result_source objects and returns the
copy.
=head2 populate
-=head3 Arguments: ($moniker, \@data);
+=over 4
+
+=item Arguments: ($moniker, \@data);
+
+=back
Populates the source registered with the given moniker with the supplied data.
@data should be a list of listrefs -- the first containing column names, the
projects / dbsrgits/DBIx-Class.git / commitdiff