specify_cli 0.0.5

data/lib/specify/models/taxonomy/taxon.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Specify
+  module Model
+    # Taxon is the _item_ class for the Specify::Model::Taxonomy _tree_. A
+    # Taxon holds information about the items to be classified, i.e. concepts
+    # of taxonomic names. Each Taxon belongs to a Specify::Model::Rank, that
+    # represents its formal Linnean classification rank.
+    #
+    # A Taxon has a _parent_ (another instance of Taxon) unless it is the root
+    # taxon of the _tree_ and can have _children_ (other instances of Taxon).
+    class Taxon < Sequel::Model(:taxon)
+      include Createable
+      include Updateable
+
+      many_to_one :taxonomy,
+                  key: :TaxonTreeDefID
+      many_to_one :rank,
+                  key: :TaxonTreeDefItemID
+      many_to_one :parent,
+                  class: self,
+                  key: :ParentID
+      many_to_one :accepted_name,
+                  class: self,
+                  key: :AcceptedID
+      one_to_many :synonyms,
+                  class: self,
+                  key: :AcceptedID
+      one_to_many :children,
+                  class: self,
+                  key: :ParentID
+      one_to_many :common_names,
+                  key: :TaxonID
+
+      # Assigns new instances that are created from a Specify::Model::Rank to
+      # the rank's Specify::Model::Taxonomy. Assigns a GUID for the record.
+      def before_create
+        self.taxonomy = rank&.taxonomy || parent.rank&.taxonomy
+        self[:GUID] = SecureRandom.uuid
+        super
+      end
+
+      # Returns +true+ if +self+ has _children_.
+      def children?
+        !children.empty?
+      end
+
+      # Returns a String with the taxon name.
+      def name
+        self[:Name]
+      end
+    end
+  end
+end

data/lib/specify/models/taxonomy/taxonomy.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Specify
+  module Model
+    # Taxnomy is the _tree_ class for the <em>taxonomy tree</em>. Taxonomies
+    # hold all Specify::Model::Rank and Specify::Model::Taxon instances
+    # belonging to a taxonomy used by a Specify::Model::Discipline.
+    class Taxonomy < Sequel::Model(:taxontreedef)
+      include TreeQueryable
+      include Updateable
+
+      one_to_many :disciplines,
+                  key: :TaxonTreeDefID
+      one_to_many :ranks,
+                  key: :TaxonTreeDefID
+      one_to_many :names,
+                  class: 'Specify::Model::Taxon',
+                  key: :TaxonTreeDefID
+    end
+  end
+end

data/lib/specify/models/tree_queryable.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Specify
+  module Model
+    # TreeQueryable is a mixin that provides methods to query _trees_
+    # such as Specify::Model::Taxnoomy and Specify::Model::Geography.
+    #
+    # Trees are nested hierarchies that are represented by three classes
+    # - an _item_ class, holding information about the items to be classified in
+    # a _tree_, such as taxonomic or geographic names.
+    # - a _rank_ class, which designates items as belonging to a formal rank or
+    # level within the tree
+    # - the _tree_ class itself, which identifies all items and ranks belonging
+    # to one tree.
+    #
+    # For taxonomies, the _tree_ class is Specify::Model::Taxonomy,
+    # the _item_ class is Specify::Model::Taxon, the _rank_ class is
+    # Specify::Model::Rank.
+    #
+    # For geographies, the _tree_ class is Specify::Model::Geography, the
+    # _item_ class is Specify::Model::GeographicName, the _rank_ class is
+    # Specify::Model::AdministrativeDivision.
+    module TreeQueryable
+      AMBIGUOUS_MATCH_ERROR = 'Ambiguous results during tree search'
+
+      # Returns the _rank_ instance in a tree for +rank_name+ (a String).
+      #
+      # _rank_ classes are Specify::Model::AdministrativeDivision (for
+      # Specify::Model::Geography), and Specify::Model::Rank (for
+      # Specify::Model::Taxonomy).
+      def rank(rank_name)
+        ranks_dataset.first(Name: rank_name.capitalize)
+      end
+
+      # Preforms a tree search, traversing a hierarchy from highest to lowest
+      # _rank_. +hash+ is a Hash with the structure
+      # <tt>{ 'rank' => 'name' }</tt> where +rank+ is an existing _rank_ name,
+      # +name+ an existing _item_ name with that rank. Give key value paris in
+      # descencing order of rank:
+      #   { 'rank 1' => 'name',
+      #     'rank 2' => 'name'
+      #     'rank n' => 'name' }
+      def search_tree(hash)
+        hash.reduce(nil) do |item, (rank_name, name)|
+          searchset = item&.children_dataset || names_dataset
+          item = searchset.where(Name: name,
+                                 rank: rank(rank_name))
+          next item.first unless item.count > 1
+          raise AMBIGUOUS_MATCH_ERROR +
+                " for #{name}: #{item.to_a.map(&:FullName)}"
+        end
+      end
+    end
+  end
+end

data/lib/specify/models/updateable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Specify
+  module Model
+    # Updateable is a mixin that provides the standard #before_update hook for
+    # Specify::Model classes.
+    #
+    # Most tables in the _Specify_ schema have a _Version_ (an Integer) that is
+    # incremented for each modification and a modification timestamp. The
+    # #before_update hook will set these.
+    module Updateable
+      # Sets the _Version_ and modification timestamp of a record.
+      def before_update
+        self[:Version] += 1
+        self[:TimestampModified] = Time.now
+        super
+      end
+    end
+  end
+end

data/lib/specify/models/user.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Specify
+  module Model
+    # Users represent _Specify_ users.
+    class User < Sequel::Model(:specifyuser)
+      include Updateable
+
+      one_to_many :agents,
+                  key: :SpecifyUserID
+      one_to_many :app_resource_dirs,
+                  key: :SpecifyUserID
+
+      # Returns +true+ if +collection+ (a Specify::Model::Collection) is the
+      # same #login_collection.
+      def collection_valid?(collection)
+        login_collection == collection
+      end
+
+      # Creates a string representation of +self+.
+      def inspect
+        "#{self} user name: #{self.Name}, logged in: #{self.IsLoggedIn}"
+      end
+
+      # Logs the user in to +collection+ (a Specify::Model::Collection).
+      #
+      # Returns a Hash with the Specify::Model::Collection as key, the timestamp
+      # for the login as the value.
+      def log_in(collection)
+        logged_in?(collection) || new_login(collection)
+      end
+
+      # Logs the user out.
+      #
+      # Returns the timestamp for the logout.
+      def log_out
+        return true unless self[:IsLoggedIn]
+        self[:LoginOutTime] = Time.now
+        self[:IsLoggedIn] = false
+        self[:LoginCollectionName] = nil
+        self[:LoginDisciplineName] = nil
+        save
+        self[:LoginOutTime]
+      end
+
+      # Returns a Hash with the Specify::Model::Collection as key, the timestamp
+      # for the login as the value if +self+ is logged in to +collection+ (a
+      # Specify::Model::Collection), +nil+ otherwise.
+      def logged_in?(collection)
+        return nil unless self[:IsLoggedIn]
+        raise LoginError::INCONSISTENT_LOGIN unless collection_valid? collection
+        { collection => self[:LoginOutTime] }
+      end
+
+      # Returns the Specify::Model::Agent for +self+ in the
+      # Specify::Model::Division division to which the login_discipline belongs.
+      def logged_in_agent
+        agents_dataset.first(division: login_discipline.division)
+      end
+
+      # Returns the Specify::Model::Collection that +self+ is logged in to.
+      def login_collection
+        login_discipline.collections_dataset
+                        .first CollectionName: self[:LoginCollectionName]
+      end
+
+      # Returns the Specify::Model::Discipline that +self+ is logged in to.
+      def login_discipline
+        Discipline.first Name: self[:LoginDisciplineName]
+      end
+
+      # Returns a String with the _Specify_ username for +self+.
+      def name
+        self[:Name]
+      end
+
+      # Registers a new login in +collection+ (a Specify::Model::Collection).
+      def new_login(collection)
+        login_time = Time.now
+        self[:LoginOutTime] = login_time
+        self[:IsLoggedIn] = true
+        self[:LoginCollectionName] = collection[:CollectionName]
+        self[:LoginDisciplineName] = collection.discipline[:Name]
+        save
+        { collection => self[:LoginOutTime] }
+      end
+
+      # Returns the Specify::Model::AppResourceDir for +self+ in +collection+
+      # (a Specify::Model::Collection).
+      def view_set_dir(collection)
+        app_resource_dirs_dataset.first(collection: collection,
+                                        discipline: collection.discipline,
+                                        UserType: self[:UserType],
+                                        IsPersonal: true)
+      end
+
+      # Returns the Specify::Model::ViewSetObject for +self+ in +collection+ (a
+      # Specify::Model::Collection)
+      def view_set(collection)
+        view_set_dir(collection)&.view_set_object
+      end
+    end
+  end
+end

data/lib/specify/models/view_set_object.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Specify
+  module Model
+    # ViewSetObjects represent Specify user forms (views). The actual views are
+    # _.views.xml_ files that are stored as blobs in the database.
+    class ViewSetObject < Sequel::Model(:spviewsetobj)
+      include Createable
+      include Updateable
+
+      many_to_one :app_resource_dir,
+                  class: 'Specify::Model::AppResourceDir',
+                  key: :SpAppResourceDirID
+      one_to_one :app_resource_data,
+                 class: 'Specify::Model::AppResourceData',
+                 key: :SpViewSetObjID
+      many_to_one :created_by,
+                  class: 'Specify::Model::Agent',
+                  key: :CreatedByAgentID
+      many_to_one :modified_by,
+                  class: 'Specify::Model::Agent',
+                  key: :ModifiedByAgentID
+
+      # Persists +file+ (a _.views.xml_ file) as a blob in the database.
+      def import(file)
+        app_resource_data.import file
+        app_resource_dir.save
+        save
+      end
+    end
+  end
+end

data/lib/specify/number_format.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Specify
+  # NumberFormats represent auto numbering formatters in a Specify::Database.
+  # Number formats in _Specify_ are applied to Strings, to ensure they conform
+  # to a defined format.
+  #
+  # If the NumberFormat can be auto-incremented, it will have a serial number
+  # part, the _incrementer_.
+  class NumberFormat
+    # The number of digits (length) of the serial number part.
+    attr_accessor :incrementer_length
+
+    # Not implemented
+    def self.from_xml(format_node)
+      # TODO: implement
+    end
+
+    # Returns a new NumberFormat
+    #
+    # +options+ is not implemented; if empty, the NumberFormat will be numeric,
+    # i.e. consist only of the _incrementer_.
+    def initialize(incrementer_length = 9, options = {})
+      @incrementer_length = incrementer_length
+      @options = options
+    end
+
+    # Not implemented
+    def self.parse(format_string)
+      # TODO: implement
+    end
+
+    # Returns a new formatted String for +number+
+    def create(number)
+      number.to_s.rjust(incrementer_length, '0') if numeric?
+    end
+
+    # Returns the serial number part (_incrementer_) of the formatted
+    # +number_string+.
+    def incrementer(number_string)
+      return number_string.to_i if numeric?
+    end
+
+    # Returns +true+ if the +self+ is a numeric NumberFormat.
+    def numeric?
+      @options.empty?
+    end
+
+    # Returns a String template for +self+, where # marks a digit of the
+    # _incrementer_ (serial number part).
+    def template
+      return '#' * incrementer_length if numeric?
+    end
+
+    # Returns a Regexp to match the match the _incrementer_ in the NumberFormat.
+    def to_regexp
+      return /^(?<incrementer>\d{#{incrementer_length}})$/ if numeric?
+    end
+  end
+end

data/lib/specify/services.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'services/service'
+require_relative 'services/stub_generator'
+require_relative 'services/view_loader'
+
+module Specify
+  # The Service module contains classes that will carry out tasks on a
+  # Specify::Database. Service classes are subclasses of Service::Service.
+  module Service
+    ACCESSION_NOT_FOUND_ERROR = 'Accession not found: '
+    USER_NOT_FOUND_ERROR = 'User not found: '
+    GEOGRAPHY_NOT_FOUND_ERROR = 'Geography not found: '
+    LOCALITY_NOT_FOUND_ERROR = 'Locality not found: '
+    TAXON_NOT_FOUND_ERROR = 'Taxon not found: '
+    PREPTYPE_NOT_FOUND_ERROR = 'Preparation type not found: '
+  end
+end

data/lib/specify/services/service.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Specify
+  module Service
+    # Superclass for service classes.
+    class Service
+      # The Specify::Session#agent for #session.
+      attr_reader :agent
+
+      # The Specify::Model::Collection for #session.
+      attr_reader :collection
+
+      # The Specify::Model::Discipline for #session.
+      attr_reader :discipline
+
+      # The Specify::Model::Division for #session.
+      attr_reader :division
+
+      # The Specify::Session for +self+ (the session that the Service uses
+      # during work with a Specify::Database).
+      attr_reader :session
+
+      # Returns a new Service.
+      #
+      # +host+: the hostname for the MySQL/MariaDB server.
+      #
+      # +database+: a String with a Specify::Database#database.
+      #
+      # +collection+: a String with an existing Specify::Model::Collection#name.
+      #
+      # +config+: a YAML file containing the database configuration.
+      #
+      # +specify_user+: a String with an existing Specify::Model::User#name.
+      def initialize(host:, database:, collection:, config:, specify_user: nil)
+        @config = Configuration::DBConfig.new(host, database, config)
+        @db = Database.new database, @config.connection
+        session_user = specify_user || @config.session_user
+        @session = @db.start_session session_user, collection
+        @collection = @session.collection
+        @discipline = @session.discipline
+        @division = @session.division
+        @agent = @session.session_agent
+      end
+
+      # Returns the Sequel::Database instance for the current connection.
+      def database
+        @db.connection
+      end
+    end
+  end
+end

data/lib/specify/services/stub_generator.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module Specify
+  module Service
+    # A StubGenerator creates Specify::Model::CollectionObject stub records
+    # (mostly empty records with a minmum of information) in collection in a
+    # Specify::Database.
+    class StubGenerator < Service
+      # An existing Specify::Model::Accession.
+      attr_reader :accession
+
+      # An existing Specify::Model::Agent.
+      attr_reader :cataloger
+
+      # An existing Specify::Model::GeographicName.
+      attr_reader :collecting_geography
+
+      # An existing Specify::Model::Locality.
+      attr_reader :collecting_locality
+
+      # String; the name for the #record_set that will be created for the
+      # generated Specify::Model::CollectionObject records.
+      attr_accessor :dataset_name
+
+      # String; the name of the Specify::Model::Locality that will be created if
+      # no existing Specify::Model::Locality is passed via #collecting_data=.
+      attr_accessor :default_locality_name
+
+      # Integer. See Specify::Model::Preparation#count.
+      attr_reader :preparation_count
+
+      # An existing Specify::Model::PreparationType.
+      attr_reader :preparation_type
+
+      # A Specify::Model::RecordSet.
+      attr_reader :record_set
+
+      # An existing Specify::Model::Taxon.
+      attr_reader :taxon
+
+      # Returns a new StubGenerator with attributes from a YAML +file+.
+      #
+      # +file+ should have the structure:
+      #     ---
+      #     :stub_generator:
+      #       :host: <hostname>
+      #       :database: <database name>
+      #       :collection: <collection name>
+      #       :config: <database configuration file>
+      #     dataset_name: <record set name>
+      #     accession: <accession number>
+      #     cataloger: <specify user name>
+      #     collecting_data:
+      #       <1st rank>: <name>
+      #       <2nd rank>: <name>
+      #       <3rd rank>: <name>
+      #       :locality: <name>
+      #     default_locality_name: <name>
+      #     determination:
+      #       <1st rank>: <name>
+      #       <2nd rank>: <name>
+      #       <3rd rank>: <name>
+      #     preparation:
+      #       :type: <preparation type>
+      #       :count: <preparation count>
+      #
+      # Items prefixed with +:+ in the example above will be deserialized as
+      # Ruby symbols and need to be prefixed with +:+ in the file. Leave out any
+      # items that are not to be set. The section +:stub_generator:+ is
+      # required.
+      def self.load_yaml(file)
+        unwrap Psych.load_file(file)
+      end
+
+      # Returns a new StubGenerator with attributes from +hash+.
+      #
+      # +hash+ should have the structure
+      # {
+      #   stub_generator: {
+      #     host: <hostname>,
+      #     database: <database name>,
+      #     collection: <collection name>,
+      #     config: <database configuration file>
+      #   },
+      #   dataset_name => <record set name>,
+      #   accession => <accession number>,
+      #   cataloger => <specify user name>,
+      #   collecting_data => {
+      #     <1st rank> => <name>,
+      #     <2nd rank> => <name>,
+      #     <3rd rank> => <name>,
+      #     locality: <name>
+      #   },
+      #   default_locality_name => <name>,
+      #   determination => {
+      #     <1st rank> => <name>,
+      #     <2nd rank> => <name>,
+      #     <3rd rank> => <name>
+      #   },
+      #   preparation => {
+      #     type: <preparation type>,
+      #     count: <preparation count>
+      #   }
+      # }
+      # Items that are symbols in the example above need to be symbols in the
+      # +hash+ passed. Leave out any items that are not to be set. The key
+      # +:stub_generator+ is required.
+      def self.unwrap(hash)
+        new hash.delete(:stub_generator) do |stubs|
+          hash.each do |key, value|
+            setter = (key + '=').to_sym
+            puts "#{setter}#{value}"
+            next unless value
+            stubs.public_send(setter, value)
+          end
+        end
+      end
+
+      # Returns a new StubGenerator.
+      def initialize(collection:,
+                     config:,
+                     host:,
+                     database:,
+                     specify_user: nil)
+        super
+        @accession = nil
+        @cataloger = agent
+        @collecting_geography = nil
+        @collecting_locality = nil
+        @default_locality_name = 'not cataloged, see label'
+        @dataset_name = "stub record set #{Time.now}"
+        @preparation_type = nil
+        @preparation_count = nil
+        @record_set = nil
+        @taxon = nil
+        yield(self) if block_given?
+      end
+
+      # Sets #accession to the Specify::Model::Accession with +accession_number+
+      def accession=(accession_number)
+        @accession = division.accessions_dataset
+                             .first AccessionNumber: accession_number
+        raise ACCESSION_NOT_FOUND_ERROR + accession_number unless accession
+      end
+
+      # Sets #cataloger to the Specify::Model::Agent representing the
+      # Specify::Model::User with +user_name+ in #division.
+      def cataloger=(user_name)
+        cataloger_user = Model::User.first(Name: user_name)
+        raise USER_NOT_FOUND_ERROR + user_name unless cataloger_user
+        @cataloger = cataloger_user.agents_dataset.first division: division
+      end
+
+      # Sets #collecting_geography and #collecting_locality.
+      #
+      # +vals+ is a Hash with the structure <tt>{ 'rank' => 'name',
+      # :locality => 'name' }</tt> where +rank+ is an existing
+      # Specify::Model::AdministrativeDivision#name, +name+ an existing
+      # Specify::Model::GeographicName#name with that rank. +:locality+ is not a
+      # geographic rank and must be given as a symbol. When traversing a tree
+      # hierarchy, give key value paris in descencing order of rank:
+      #   { 'Country' => 'United States',
+      #     'State' => 'Kansas',
+      #     'County' => 'Douglas County',
+      #     :locality => 'Freestate Brewery' }
+      def collecting_data=(vals)
+        locality = vals.delete :locality
+        unless vals.empty?
+          @collecting_geography = geography.search_tree(vals)
+          unless @collecting_geography
+            missing_geo = vals.values.join(', ')
+            raise GEOGRAPHY_NOT_FOUND_ERROR + missing_geo
+          end
+        end
+        return unless locality
+        @collecting_locality = find_locality locality
+        raise LOCALITY_NOT_FOUND_ERROR + locality unless collecting_locality
+      end
+
+      # Returns #collecting_locality or #default_locality if
+      # #collecting_locality is +nil+ but #collecting_geography is not;
+      # Will create the Specify::Model::GeographicName for #default_locality
+      # if it does not exist in #localities.
+      def collecting_locality!
+        return collecting_locality if collecting_locality
+        return unless collecting_geography
+        default_locality!
+      end
+
+      # Creates +count+ records for Specify::Model::CollectionObject with the
+      # attributes of +self+.
+      def create(count)
+        @record_set = collection.add_record_set Name: dataset_name,
+                                                user: cataloger.user
+        count.times do
+          stub = create_stub
+          @record_set.add_record_set_item collection_object: stub
+        end
+      end
+
+      # Returns the Specify::Model::GeographicName for #default locality if it
+      # exists.
+      def default_locality
+        find_locality default_locality_name
+      end
+
+      # Returns the Specify::Model::GeographicName for #default locality.
+      # Creates the record if it does not exist in #localities.
+      def default_locality!
+        return default_locality if default_locality
+        default_locality ||
+          discipline.add_locality(LocalityName: default_locality_name,
+                                  geographic_name: collecting_geography)
+      end
+
+      # Sets #taxon, to which stub records will be determined.
+      # +vals+ is a Hash with the structure <tt>{ 'rank' => 'name' }</tt> where
+      # +rank+ is an existing Specify::Model::Rank#name, +name+ an existing
+      # Specify::Model::Taxon#name with that rank. When traversing a tree
+      # hierarchy, give key value paris in descencing order of rank:
+      #   { 'Phylum' => 'Arthropoda',
+      #     'Class' => 'Trilobita',
+      #     'Order' => 'Asaphida',
+      #     'Family' => 'Asaphidae' }
+      def determination=(vals)
+        @taxon = taxonomy.search_tree vals
+        raise TAXON_NOT_FOUND_ERROR + vals.to_s unless taxon
+      end
+
+      # Returns the Specify::Model::Locality for +locality_name+ in #localities.
+      def find_locality(locality_name)
+        locality_matches = localities.where LocalityName: locality_name
+        raise Model::AMBIGUOUS_MATCH_ERROR if locality_matches.count > 1
+        locality_matches.first
+      end
+
+      # Returns the Specify::Model::CollectionObject records in #record_set
+      # (the records created by #create).
+      def generated
+        record_set&.collection_objects
+      end
+
+      # Returns the Specify::Model::Geography for #discipline.
+      def geography
+        discipline.geography
+      end
+
+      # Returns a Sequel::Dataset of Specify::Model::Locality records in
+      # #collecting_geography or #division if #collecting_geography is +nil+.
+      def localities
+        @collecting_geography&.localities_dataset ||
+          discipline.localities_dataset
+      end
+
+      # Sets #preparation_type and #preparation_count. +type+ must be an
+      # existing Specify::Model::PreparationType#name. +count+ should be an
+      # Integer.
+      #
+      # Returns an array with the #preparation_type and #preparation_count.
+      def preparation=(type:, count: nil)
+        @preparation_type = collection.preparation_types_dataset
+                                      .first Name: type
+        raise PREPTYPE_NOT_FOUND_ERROR + type unless preparation_type
+        @preparation_count = count
+        [preparation_type, preparation_count].compact
+      end
+
+      # Returns the Specify::Model::Taxonomy for #discipline.
+      def taxonomy
+        discipline.taxonomy
+      end
+
+      private
+
+      def create_stub
+        co = collection.add_collection_object(cataloger: cataloger)
+        co.accession = accession
+        co.geo_locate(locality: collecting_locality!) if collecting_locality!
+        co.identify(taxon: taxon) if taxon
+        make_preparation(co) if preparation_type
+        co.save
+      end
+
+      def make_preparation(collection_object)
+        collection_object.add_preparation collection: collection,
+                                          preparation_type: preparation_type,
+                                          CountAmt: preparation_count
+      end
+    end
+  end
+end