=head1 NAME

Bio::Chado::Schema::Util - utility functions shared by Bio::Chado::Schema objects

=head1 SYNOPSIS

  sub create_organismprops {
      my ($self, $props, $opts) = @_;

      # process opts
      $opts ||= {};
      $opts->{cv_name} = 'organism_property'
          unless defined $opts->{cv_name};

      return Bio::Chado::Schema::Util->create_props
          ( properties => $props,
            options    => $opts,
            row        => $self,
            prop_relation_name => 'organismprops',
          );
  }

=head1 DESCRIPTION

Helper functions used by several schema classes.

Important Note: 
This package is located in the Schema.pm file as secondary package 
and it haven't a file for itself. Nevertheless, the use will be the same.

=head1 PACKAGE METHODS

=head2 create_properties

  Usage: *::Util->create_properties( row => $self,
                                     properties => { baz => 2, foo => 'bar' },
                                     options => { cv_name => autocreate => 0, ...},
                                     prop_relation_name => 'organismprops',
                                   );

  Desc : Chado has a number of <thing>prop tables with a similar
         structure.  This utility function is used by a number of
         modules to create properties in these kinds of tables.

  Args : row => the DBIC row object to create properties for,
         prop_relation_name => the DBIC relation name for the
                               properties table to operate on,
                               e.g. 'featureprops',
         properties => hashref of { propname => value, ...},
         options => options hashref as:
             {
               autocreate => 0,
                  (optional) boolean, if passed, automatically create cv,
                  cvterm, and dbxref rows if one cannot be found for the
                  given featureprop name.  Default false.

               cv_name => cv.name to use for the given featureprops.
                          Defaults to 'feature_property',

               db_name => db.name to use for autocreated dbxrefs,
                          default 'null',

               allow_duplicate_values => default false.
                   If true, allow duplicate instances of the same cvterm
                   and value in the properties of the feature.  Duplicate
                   values will have different ranks.

               dbxref_accession_prefix => optional, default
                                          'autocreated:',
               definitions => optional hashref of:
                   { cvterm_name => definition,
                   }
                to load into the cvterm table when autocreating cvterms
             }
  Ret  : hashref of { propname => new row object in property table }

=cut


=head1 AUTHOR

Robert Buels, <rmb32@cornell.edu>

Naama Menda, <naama.menda@gmail.com>

=head1 COPYRIGHT & LICENSE

Copyright 2009 Boyce Thompson Institute for Plant Research

This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut


####################################################################################
##                                                                                ##
## Important Note:                                                                ##
## This package is actually located in ../Schema.pm to prevent it being found by  ##
## Module::Find and similar tools.                                                ##
##                                                                                ##
####################################################################################
