specify_cli 0.0.5

data/lib/specify.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# require 'specify/version.rb'
+
+require 'date'
+require 'fileutils'
+require 'io/console'
+require 'mysql2'
+require 'open3'
+require 'pathname'
+require 'psych'
+require 'readline'
+require 'securerandom'
+require 'sequel'
+
+require_relative 'specify/branch_parser'
+require_relative 'specify/cli'
+require_relative 'specify/configuration'
+require_relative 'specify/database'
+require_relative 'specify/number_format'
+require_relative 'specify/session'
+require_relative 'specify/user_type'
+require_relative 'specify/services'
+
+# FIXME: causes warnings, but is also required for call from bash script
+#        raises name error for VERSION and DESCRIPTION constants otherwise
+require_relative 'specify/version'
+
+# A module that provides functionaliy to manage Specify app resources.
+module Specify
+  GIT_CURRENT_BRANCH = 'git rev-parse --abbrev-ref HEAD'
+
+  BRANCH_ERROR = 'Branch name not parsable: '
+
+  # FileError is a module that contains errors for file operations.
+  module FileError
+    VIEWS_FILE = 'Files must be .views.xml files'
+    NO_FILE = "File not found"
+  end
+
+  # LoginError is a module that contains errors for User logins.
+  module LoginError
+    INCONSISTENT_LOGIN = 'User is already logged in to a different collection'
+  end
+end

data/lib/specify/branch_parser.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Specify
+  # BranchParsers parse the information required to set a
+  # Specify::Service::ViewLoade#target for upload of _.views.xml_ files from a
+  # string that follows the convention <tt>Database/CollectionName/level</tt>.
+  #
+  # This can be the name of a git branch of a repository residing in a folder
+  # denoting the hostname.
+  class BranchParser
+    # The name of the collection. Must be an existing
+    # Specify::Model::Collection#name.
+    attr_reader :collection
+
+    # A Specify::Configuration::HostConfig.
+    attr_reader :config
+
+    # The name of a _Specify_ database.
+    attr_reader :database
+
+    # The name of a MySQL/MariaDB host.
+    attr_reader :host
+
+    # The name of a _Specify_ user (an existing Specify::Model::User#name).
+    attr_reader :user
+
+    # Creates a new instance of BranchParser for the current Git _HEAD_.
+    #
+    # +config+: a database configuration YAML file.
+    def self.current_branch(config)
+      stdout_str, stderr_str, status = Open3.capture3(GIT_CURRENT_BRANCH)
+      unless status.exitstatus.zero?
+        STDERR.puts "There was an error running #{GIT_CURRENT_BRANCH}"
+        STDERR.puts stderr_str
+        exit 1
+      end
+      branch = stdout_str.chomp
+      new(Dir.pwd, branch, config)
+    end
+
+    # Returns a new BranchParser with +view_file_path+ and +name+.
+    #
+    # +view_file_path+: the directory path of the _.vews.xml_ file (that path
+    # must be mapped to a host name in the +config+).
+    #
+    # +name+: a String with a branch name conforming to the convention
+    # <tt>Database/CollectionName/level</tt>.
+    #
+    # +config+: a database configuration YAML file.
+    def initialize(view_file_path, name, config = nil)
+      @config = Configuration::HostConfig.new(config)
+      @database, collection, @level, @user = *name.split('/')
+      raise ArgumentError, BRANCH_ERROR + name unless collection && level
+      @host = @config.resolve_host view_file_path
+      @collection = normalize_name collection
+    end
+
+    # Returns the attributes of +self+ as a hash.
+    def to_h
+      { host: host,
+        database: database,
+        collection: collection,
+        level: level }
+    end
+
+    # Returns the level to a Specify::Service::ViewLoader will upload.
+    def level
+      case @level
+      when 'collection', 'discipline'
+        @level.to_sym
+      when 'user'
+        { user: @user }
+      else
+        { user_type: @level.downcase.to_sym }
+      end
+    end
+
+    private
+
+    def normalize_name(name)
+      name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1 \2')
+          .gsub(/([a-z\d])([A-Z])/, '\1 \2')
+    end
+  end
+end

data/lib/specify/cli.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'cli/database_setup'
+require_relative 'cli/stubs'
+require_relative 'cli/viewset'
+
+module Specify
+  # The CLI module contains methods used by the command line interface.
+  module CLI
+  end
+end

data/lib/specify/cli/database_setup.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Specify
+  module CLI
+    # Asks the user to configure a database.
+    def self.configure_database(config)
+      STDERR.puts "Configuring new database: #{config.database}"
+      config.user_name = require_input 'MySQL user name'
+      config.user_password = require_input 'password (blank for prompt)'
+      config.session_user = require_input 'Specify user (leave blank to skip)'
+      config.save
+    end
+
+    # Asks the user to configure a host.
+    def self.configure_host(config)
+      return unless proceed? "host #{config.host} not known"
+      config.port = require_input 'port number (leave blank for default)'
+      config.save
+    end
+
+    # Creates a new database configuratin YAML file.
+    def self.db_config!(file, global_options)
+      return if File.exist?(global_options[:db_config])
+      STDERR.puts "Creating new config file #{file}"
+      Specify::Configuration::Config.empty file do |config|
+        config.add_host global_options[:host], global_options[:port]
+      end
+    end
+
+    # Asks the user to proceed. Returns +true+ if the user answers answers with
+    # 'Yes'.
+    def self.proceed?(message)
+      STDERR.puts message
+      STDERR.print "Configure? (Y/n)"
+      return true if /^[Yy](es)?/.match Readline.readline(': ')
+    end
+
+    # Prompts the user for input with +message+.
+    def self.require_input(message)
+      STDERR.print message
+      answer = Readline.readline(': ')
+      return if answer.empty?
+      answer
+    end
+  end
+end

data/lib/specify/cli/stubs.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Specify
+  module CLI
+    # Transforms +arg+ (a String passed as a command line argument) containing
+    # hierarchical information (such as geographic or taxonomic) into a
+    # structured Hash that can be used to set the
+    # Specify::Service::StubGenerator#collecting_data= or
+    # Specify::Service::StubGenerator#determination=.
+    def self.arg_to_hash(arg)
+      return unless arg
+      arg.split(';')
+         .map { |pair| pair.split(':').map(&:strip) }
+         .to_h
+         .transform_keys { |key| key == 'locality' ? key.to_sym : key }
+    end
+
+    # Creates stub records with +generator+ (a Specify::Service::StubGenerator).
+    #
+    # +count+: the number of stub records to be created.
+    def self.make_stubs(generator, count)
+      STDERR.puts "started creating #{count} records"
+      STDERR.puts "cataloger: #{generator.cataloger}"
+      generator.database.transaction do
+        generator.create count
+        STDERR.puts "creating: #{generator.generated.last.catalog_number}"
+      end
+      STDERR.puts 'done'
+      puts "generated #{generator.generated.count} catalog numbers:"
+      puts '--------------------------'
+      generator.generated.each { |co| puts co.CatalogNumber }
+    end
+
+    # Returns a Hash for intialization of a Specify::Service::StubGenerator
+    # from +global_options+, +args+, and command +options+.
+    def self.wrap_args(global_options, args, options)
+      params = {}
+      stub_generator = {}
+      stub_generator[:host] = global_options[:host]
+      stub_generator[:database] = global_options[:database]
+      stub_generator[:collection] = args.shift
+      stub_generator[:specify_user] = global_options[:specify_user]
+      stub_generator[:config] = global_options[:db_config]
+      params[:stub_generator] = stub_generator
+      params.merge stub_parameters(options)
+    end
+
+    # Parses the parameters for stub records to created by a
+    # Specify::Service::StubGenerator from the command +options+.
+    def self.stub_parameters(options)
+      params = { 'dataset_name' => options[:dataset],
+                 'cataloger' => options[:cataloger],
+                 'accession' => options[:accession],
+                 'collecting_data' => arg_to_hash(options[:geography]),
+                 'default_locality_name' => options[:locality],
+                 'determination' => arg_to_hash(options[:taxon]) }
+      return params unless options[:preptype]
+      params['preparation'] = { type: options[:preptype],
+                                count: options[:prepcount] }
+      params.compact
+    end
+  end
+end

data/lib/specify/cli/viewset.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Specify
+  module CLI
+    # Parses the _level_ for the Specify::Service::ViewLoader to upload
+    # _.vioews.xml_ files to from the command +options+.
+    def self.level(options)
+      if options[:d]
+        :discipline
+      elsif options[:c]
+        :collection
+      elsif options[:t]
+        { user_type: options[:t] }
+      elsif options[:u]
+        { user: options[:u] }
+      else
+        raise 'level required (use -d, -c, -t, or -u option)'
+      end
+    end
+  end
+end

data/lib/specify/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'configuration/config'
+require_relative 'configuration/db_config'
+require_relative 'configuration/host_config'
+
+module Specify
+  # Configuration is a module that contains classes that provide configuration
+  # facilities.
+  module Configuration
+  end
+end

data/lib/specify/configuration/config.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Specify
+  module Configuration
+    # Configurations wrap a database configuaratin file (_.rc.yaml_ file).
+    #
+    # Configuration is the superclass of the DBConfig and HostConfig classes.
+    class Config
+      # A Hash containing the directory-host-mapping parameters for the
+      # HostConfig subclass.
+      attr_reader :dir_names
+
+      # A Hash containing the database parameters for the DBConfig subclass.
+      attr_reader :hosts
+
+      # Returns a new empty Config for +file+ that can serve as a template.
+      #
+      # +file+: the YAML file containg the configuration
+      def self.empty(file, &block)
+        if File.exist?(file)
+          raise "#{file} exists, won't overwrite"
+        end
+        config = new file, dir_names: {}, hosts: {}, &block
+        config.save
+        config
+      end
+
+      # Returns a new Config for +file+ (a YAML file containg the
+      # configuration).
+      #
+      # <tt>dir_names</tt>: a Hash with directory names as keys, host names as
+      # values.
+      #
+      # +hosts+: a Hash with host configurations. The hash should have the
+      # structure:
+      #   {
+      #     :hosts => {
+      #       'hostname' => {
+      #         :port => Integer,
+      #         :databases => {
+      #           'database name' => {
+      #             :db_user => {
+      #               :name => 'mysql_user_name',
+      #               :password => 'password'
+      #             },
+      #             :sp_user => 'specify_user_name'
+      #           }
+      #         }
+      #       }
+      #     }
+      #   }
+      # Leave +:password+ out to be prompted.
+      def initialize(file = nil, dir_names: nil, hosts: nil)
+        @file = Pathname.new(file)
+        if dir_names || hosts
+          @dir_names = dir_names
+          @hosts = hosts
+          @params = { dir_names: dir_names, hosts: hosts }
+        else
+          @params = Psych.load_file(@file)
+          @dir_names = @params[:dir_names]
+          @hosts = @params[:hosts]
+        end
+        yield(self) if block_given?
+        @saved = nil
+      end
+
+      # Adds a configuration for the database with +name+ to the +host+
+      # configuration.
+      def add_database(name, host:)
+        add_host(host) unless hosts[host]
+        if hosts.dig host, :databases, name
+          raise "Database '#{name}' on '#{host}' already configured"
+        end
+        db = hosts[host][:databases][name] = db_template
+        yield(db) if block_given?
+        @saved = false
+      end
+
+      # Adds a configuration for the host with +name+.
+      def add_host(name, port = nil)
+        raise "Host '#{name}' already configured" if hosts[name]
+        hosts[name] = { port: port, databases: {} }
+        @saved = false
+      end
+
+      # Returns a Hash with the contents of the configuration YAML file.
+      def params
+        { dir_names: @dir_names, hosts: @hosts }
+      end
+
+      # Saves the current state to the YAML configuration file.
+      def save
+        File.open(@file, 'w') do |file|
+          file.write(Psych.dump(@params))
+        end
+        @saved = true
+      end
+
+      # Returns +false+ if the instance has been modified since the last save.
+      def saved?
+        @saved
+      end
+
+      # Marks the instance as modified.
+      def touch
+        @saved = false
+      end
+
+      private
+
+      def db_template
+        {
+          db_user: { name: nil, password: nil },
+          sp_user: nil
+        }
+      end
+    end
+  end
+end

data/lib/specify/configuration/db_config.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Specify
+  module Configuration
+    # DBConfigs are Specify:Database configurations.
+    class DBConfig < Config
+      # The name of the _Specify_ database.
+      attr_reader :database
+
+      # The name of the MySQL/MariaDB host for the _Specify_ database.
+      attr_reader :host
+
+      # The port for the MySQL/MariaDB server for the _Specify_ database.
+      attr_reader :port
+
+      # The MySQL/MariaDB user for the database. This is typically the _Specify_
+      # <em>master user</em>.
+      attr_reader :user_name
+
+      # An existing Specify::Model::User#name; the name of the
+      # Specify::Model::User that is logged in to #collection during a Session.
+      attr_reader :session_user
+
+      # Returns a new DBConfig for +database+ on +host+
+      #
+      # _file_: the YAML file (path) containg the configuration.
+      def initialize(host, database, file = nil)
+        super(file)
+        @host = host
+        @database = database
+        @port = hosts.dig @host, :port
+        @user_name = params&.dig :db_user, :name
+        @user_password = params&.dig :db_user, :password
+        @session_user = params&.fetch :sp_user, nil
+        @saved = known? ? true : false
+      end
+
+      # Returns the connection paramaters for the database as a Hash.
+      def connection
+        raise "#{database} on #{host} not configured" unless known?
+        { host: host,
+          port: port || 3306,
+          user: user_name,
+          password: @user_password }
+      end
+
+      # Returns +true+ if #user_name differs from the user +:name+ in the
+      # #params of the YAML file.
+      def changed_user?
+        params[:db_user][:name] != user_name
+      end
+
+      # Returns +true+ if the <em>user_password</em> attribute differs from the
+      # +:password+ in the #params of the YAML file.
+      def changed_password?
+        params[:db_user][:password] != @user_password
+      end
+
+      # Returns +true+ if #port differs from the +:port+ in the #params of the
+      # YAML file.
+      def changed_port?
+        hosts[host][:port] != port
+      end
+
+      # Returns +true+ if the #session_user differs from the <tt>:so_user</tt>
+      # in the #params of the YAML file.
+      def changed_session_user?
+        params[:sp_user] != session_user
+      end
+
+      # Sets the #database.
+      def database=(name)
+        @database = name
+        touch
+      end
+
+      # Returns a Hash with the MySQL/MariaDB user name and password.
+      def db_user
+        { name: @user_name, password: @user_password }
+      end
+
+      # Sets the #host
+      def host=(name)
+        @host = name
+        touch
+      end
+
+      # Returns +true+ if #host is known (has been configured), +false+
+      # otherwise.
+      def host?
+        hosts[host]
+      end
+
+      # Returns +true+ if #database is known (has been configured), +false+
+      # otherwise.
+      def known?
+        params ? true : false
+      end
+
+      # Returns a Hash with the parameters for the #host #database from the
+      # configuration YAML file.
+      def params
+        super.dig:hosts, @host, :databases, @database
+      end
+
+      # Sets the #port
+      def port=(number)
+        @port = number&.to_i
+        raise ArgumentError, "invalid port number: #{number}" unless port_valid?
+        touch
+      end
+
+      # Saves the current state to the YAML file.
+      def save
+        return true if saved?
+        host? ? update_host : save_new_host
+        super
+      end
+
+      # Sets #session_user.
+      def session_user=(name)
+        @session_user = name
+        touch
+      end
+
+      # Sets the #user_name.
+      def user_name=(name)
+        @user_name = name
+        touch
+      end
+
+      # Sets the MySQL/MariaDB <em>user_password</em>.
+      def user_password=(password)
+        @user_password = password
+        touch
+      end
+
+      private
+
+      def save_new_host
+        add_host host, port
+        add_database database, host: host
+      end
+
+      def update_database
+        params[:db_user][:name] = user_name if changed_user?
+        params[:db_user][:password] = @user_password if changed_password?
+        params[:sp_user] = session_user if changed_session_user?
+      end
+
+      def update_host
+        hosts[host][:port] = port if changed_port?
+        add_database database, host: host unless known?
+        update_database
+      end
+
+      def port_valid?
+        port.nil? || port.to_i.positive?
+      end
+    end
+  end
+end