+DESCRIPTION
+This is still experimental. I've added a functional interface so that it can be used
+in Form Processors and not require modification of the model.
+ You can feed the ->create method with a recursive datastructure and have
+ the related records created. Unfortunately you cannot do a similar thing
+ with update_or_create - this module tries to fill that void.
+
+ It is a base class for ResultSets providing just one method:
+ recursive_update which works just like update_or_create but can
+ recursively update or create data objects composed of multiple rows. All
+ rows need to be identified by primary keys - so you need to provide them
+ in the update structure (unless they can be deduced from the parent row
+ - for example when you have a belongs_to relationship). If not all
+ colums comprising the primary key are specified - then a new row will be
+ created, with the expectation that the missing columns will be filled by
+ it (as in the case of auto_increment primary keys).
+
+ If the resultset itself stores an assignement for the primary key, like
+ in the case of:
+
+ my $restricted_rs = $user_rs->search( { id => 1 } );
+
+ then you need to inform recursive_update about additional predicate with
+ a second argument:
+
+ my $user = $restricted_rs->recursive_update( {
+ owned_dvds => [
+ {
+ title => 'One Flew Over the Cuckoo's Nest'
+ }
+ ]
+ },
+ [ 'id' ]
+ );
+
+ This will work with a new DBIC release.
+
+ For a many_to_many (pseudo) relation you can supply a list of primary
+ keys from the other table - and it will link the record at hand to those
+ and only those records identified by them. This is convenient for
+ handling web forms with check boxes (or a SELECT box with multiple
+ choice) that let you update such (pseudo) relations.
+
+ For a description how to set up base classes for ResultSets see
+ load_namespaces in DBIx::Class::Schema.
+
+DESIGN CHOICES
+ Treatment of many to many pseudo relations
+ The function gets the information about m2m relations from
+ DBIx::Class::IntrospectableM2M. If it is not loaded in the ResultSource
+ classes - then the code relies on the fact that: if($object->can($name)
+ and !$object->result_source->has_relationship($name) and $object->can(
+ 'set_' . $name ) )
+
+ then $name must be a many to many pseudo relation. And that in a
+ similarly ugly was I find out what is the ResultSource of objects from
+ that many to many pseudo relation.
+
+INTERFACE
+METHODS
+ recursive_update
+ The method that does the work here.
+
+ is_m2m
+ $self->is_m2m( 'name ' ) - answers the question if 'name' is a many to
+ many (pseudo) relation on $self.
+
+ get_m2m_source
+ $self->get_m2m_source( 'name' ) - returns the ResultSource linked to by
+ the many to many (pseudo) relation 'name' from $self.
+
+DIAGNOSTICS
+CONFIGURATION AND ENVIRONMENT
+ DBIx::Class::RecursiveUpdate requires no configuration files or
+ environment variables.