use base qw/DBIx::Class/;
-use DBIx::Class::Exception;
use Scalar::Util 'blessed';
use List::Util 'first';
use Try::Tiny;
This class is responsible for defining and doing basic operations on rows
derived from L<DBIx::Class::ResultSource> objects.
-Row objects are returned from L<DBIx::Class::ResultSet>s using the
+Result objects are returned from L<DBIx::Class::ResultSet>s using the
L<create|DBIx::Class::ResultSet/create>, L<find|DBIx::Class::ResultSet/find>,
L<next|DBIx::Class::ResultSet/next> and L<all|DBIx::Class::ResultSet/all> methods,
as well as invocations of 'single' (
L<belongs_to|DBIx::Class::Relationship/belongs_to>,
L<has_one|DBIx::Class::Relationship/has_one> or
L<might_have|DBIx::Class::Relationship/might_have>)
-relationship accessors of L<DBIx::Class::Row> objects.
+relationship accessors of L<Result|DBIx::Class::Manual::ResultClass> objects.
=head1 NOTE
L<DBIx::Class::Row>. Therefore, while many of the methods available to a
L<DBIx::Class::Core>-derived Result class are described in the following
documentation, it does not detail all of the methods available to Result
-objects. Refer to L<DBIx::Class::Core> for more info.
+objects. Refer to L<DBIx::Class::Manual::ResultClass> for more info.
=head1 METHODS
=item Arguments: \%attrs or \%colsandvalues
-=item Returns: A DBIx::Class::Row object
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
=back
-While you can create a new row object by calling C<new> directly on
+While you can create a new result object by calling C<new> directly on
this class, you are better off calling it on a
L<DBIx::Class::ResultSet> object.
next;
}
}
- $new->throw_exception("No such column $key on $class")
+ $new->throw_exception("No such column '$key' on $class")
unless $class->has_column($key);
$new->store_column($key => $attrs->{$key});
}
=item Arguments: $value?
-=item Returns: $value
+=item Return Value: $value
=back
A column accessor method is created for each column, which is used for
getting/setting the value for that column.
-The actual method name is based on the L<accessor|DBIx::Class::ResultSource/accessor>
-name given in the table definition. Like L</set_column>, this will
-not store the data until L</insert> or L</update> is called on the row.
+The actual method name is based on the
+L<accessor|DBIx::Class::ResultSource/accessor> name given during the
+L<Result Class|DBIx::Class::Manual::ResultClass> L<column definition
+|DBIx::Class::ResultSource/add_columns>. Like L</set_column>, this
+will not store the data in the database until L</insert> or L</update>
+is called on the row.
=head2 insert
=item Arguments: none
-=item Returns: The Row object
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
=back
it isn't already in there. Returns the object itself. To insert an
entirely new row into the database, use L<DBIx::Class::ResultSet/create>.
-To fetch an uninserted row object, call
-L<new|DBIx::Class::ResultSet/new> on a resultset.
+To fetch an uninserted result object, call
+L<new_result|DBIx::Class::ResultSet/new_result> on a resultset.
This will also insert any uninserted, related objects held inside this
one, see L<DBIx::Class::ResultSet/create> for more details.
=item Arguments: none or 1|0
-=item Returns: 1|0
+=item Return Value: 1|0
=back
L<DBIx::Class::ResultSet/create> or L<DBIx::Class::ResultSet/insert>
are used.
-Creating a row object using L<DBIx::Class::ResultSet/new>, or calling
-L</delete> on one, sets it to false.
+Creating a result object using L<DBIx::Class::ResultSet/new_result>, or
+calling L</delete> on one, sets it to false.
=cut
=item Arguments: none or a hashref
-=item Returns: The Row object
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
=back
-Throws an exception if the row object is not yet in the database,
+Throws an exception if the result object is not yet in the database,
according to L</in_storage>.
This method issues an SQL UPDATE query to commit any changes to the
$row->update({ last_modified => \'NOW()' });
The update will pass the values verbatim into SQL. (See
-L<SQL::Abstract> docs). The values in your Row object will NOT change
+L<SQL::Abstract> docs). The values in your Result object will NOT change
as a result of the update call, if you want the object to be updated
with the actual values from the database, call L</discard_changes>
after the update.
=item Arguments: none
-=item Returns: The Row object
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
=back
rows.
If you delete an object within a txn_do() (see L<DBIx::Class::Storage/txn_do>)
-and the transaction subsequently fails, the row object will remain marked as
+and the transaction subsequently fails, the result object will remain marked as
not being in storage. If you know for a fact that the object is still in
storage (i.e. by inspecting the cause of the transaction's failure), you can
use C<< $obj->in_storage(1) >> to restore consistency between the object and
=item Arguments: $columnname
-=item Returns: The value of the column
+=item Return Value: The value of the column
=back
Throws an exception if the column name given doesn't exist according
to L<has_column|DBIx::Class::ResultSource/has_column>.
-Returns a raw column value from the row object, if it has already
+Returns a raw column value from the result object, if it has already
been fetched from the database or set by an accessor.
If an L<inflated value|DBIx::Class::InflateColumn> has been set, it
=item Arguments: $columnname
-=item Returns: 0|1
+=item Return Value: 0|1
=back
=item Arguments: none
-=item Returns: A hash of columnname, value pairs.
+=item Return Value: A hash of columnname, value pairs.
=back
=item Arguments: none
-=item Returns: A hash of column, value pairs
+=item Return Value: A hash of column, value pairs
=back
=item Arguments: $columnname
-=item Returns: undefined
+=item Return Value: not defined
=back
=item Arguments: none
-=item Returns: A hash of column, object|value pairs
+=item Return Value: A hash of column, object|value pairs
=back
=item Arguments: $columnname, $value
-=item Returns: $value
+=item Return Value: $value
=back
=item Arguments: \%columndata
-=item Returns: The Row object
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
=back
=item Arguments: \%columndata
-=item Returns: The Row object
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
=back
Sets more than one column value at once. Any inflated values are
deflated and the raw values stored.
-Any related values passed as Row objects, using the relation name as a
+Any related values passed as Result objects, using the relation name as a
key, are reduced to the appropriate foreign key values and stored. If
-instead of related row objects, a hashref of column, value data is
+instead of related result objects, a hashref of column, value data is
passed, will create the related object first then store.
Will even accept arrayrefs of data as a value to a
=item Arguments: \%replacementdata
-=item Returns: The Row object copy
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> copy
=back
=item Arguments: $columnname, $value
-=item Returns: The value sent to storage
+=item Return Value: The value sent to storage
=back
method is used internally by L</set_column> which you should probably
be using.
-This is the lowest level at which data is set on a row object,
+This is the lowest level at which data is set on a result object,
extend this method to catch all data setting methods.
=cut
=over
-=item Arguments: $result_source, \%columndata, \%prefetcheddata
+=item Arguments: L<$result_source|DBIx::Class::ResultSource>, \%columndata, \%prefetcheddata
-=item Returns: A Row object
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
=back
All L<DBIx::Class::ResultSet> methods that retrieve data from the
-database and turn it into row objects call this method.
+database and turn it into result objects call this method.
Extend this method in your Result classes to hook into this process,
for example to rebless the result into a different class.
foreach my $pre (keys %{$prefetch||{}}) {
- my (@pre_vals, $is_multi);
- if (ref $prefetch->{$pre}[0] eq 'ARRAY') {
- $is_multi = 1;
- @pre_vals = @{$prefetch->{$pre}};
- }
- else {
- @pre_vals = $prefetch->{$pre};
- }
+ my @pre_vals;
+ @pre_vals = (ref $prefetch->{$pre}[0] eq 'ARRAY')
+ ? @{$prefetch->{$pre}} : $prefetch->{$pre}
+ if @{$prefetch->{$pre}};
- my $pre_source = try {
- $source->related_source($pre)
- }
- catch {
- $class->throw_exception(sprintf
-
- "Can't inflate manual prefetch into non-existent relationship '%s' from '%s', "
- . "check the inflation specification (columns/as) ending in '%s.%s'.",
-
- $pre,
- $source->source_name,
- $pre,
- (keys %{$pre_vals[0][0]})[0] || 'something.something...',
- );
- };
+ my $pre_source = $source->related_source($pre);
my $accessor = $source->relationship_info($pre)->{attrs}{accessor}
- or $class->throw_exception("No accessor type declared for prefetched $pre");
-
- if (! $is_multi and $accessor eq 'multi') {
- $class->throw_exception("Manual prefetch (via select/columns) not supported with accessor 'multi'");
- }
+ or $class->throw_exception("No accessor type declared for prefetched relationship '$pre'");
my @pre_objects;
for my $me_pref (@pre_vals) {
- # FIXME - this should not be necessary
- # the collapser currently *could* return bogus elements with all
- # columns set to undef
- my $has_def;
- for (values %{$me_pref->[0]}) {
- if (defined $_) {
- $has_def++;
- last;
- }
- }
- next unless $has_def;
+ # FIXME SUBOPTIMAL - the new row parsers can very well optimize
+ # this away entirely, and *never* return such empty rows.
+ # For now we maintain inflate_result API backcompat, see
+ # t/resultset/inflate_result_api.t
+ next unless defined first { defined $_ } values %{$me_pref->[0]};
- push @pre_objects, $pre_source->result_class->inflate_result(
- $pre_source, @$me_pref
- );
+ push @pre_objects, $pre_source->result_class->inflate_result(
+ $pre_source, @$me_pref
+ );
}
if ($accessor eq 'single') {
=item Arguments: none
-=item Returns: Result of update or insert operation
+=item Return Value: Result of update or insert operation
=back
=item Arguments: none
-=item Returns: 0|1 or @columnnames
+=item Return Value: 0|1 or @columnnames
=back
=item Arguments: $columname
-=item Returns: 0|1
+=item Return Value: 0|1
=back
=over
-=item Arguments: $result_source_instance
+=item Arguments: L<$result_source?|DBIx::Class::ResultSource>
-=item Returns: a ResultSource instance
+=item Return Value: L<$result_source|DBIx::Class::ResultSource>
=back
=item Arguments: $columnname, \%columninfo
-=item Returns: undefined
+=item Return Value: not defined
=back
=item Arguments: \%attrs
-=item Returns: A Row object
+=item Return Value: A Result object
=back
-Fetches a fresh copy of the Row object from the database and returns it.
+Fetches a fresh copy of the Result object from the database and returns it.
Throws an exception if a proper WHERE clause identifying the database row
can not be constructed (i.e. if the original object does not contain its
entire
). If passed the \%attrs argument, will first apply these attributes to
the resultset used to find the row.
-This copy can then be used to compare to an existing row object, to
+This copy can then be used to compare to an existing result object, to
determine if any changes have been made in the database since it was
created.
-To just update your Row object with any latest changes from the
+To just update your Result object with any latest changes from the
database, use L</discard_changes> instead.
The \%attrs argument should be compatible with
=item Arguments: none or $attrs
-=item Returns: self (updates object in-place)
+=item Return Value: self (updates object in-place)
=back
projects / dbsrgits/DBIx-Class.git / blobdiff