specify_cli 0.0.5

data/man/specify_cli.1.ronn

@@ -0,0 +1,157 @@
+specify_cli(1) -- A command line interface for Specify
+===============================================================================
+
+## SYNOPSIS
+
+`specify_cli` [**-D**|**--database** <name>]
+              [**-H**|**--host** <name>]
+              [**-P**|**--password** <password>]
+              [**-U**|**--specify_user** <name>]
+              [**-c**|**--db_config** <file>]
+              [**-p**|**--port** <number>]
+              [**-u**|**--user** <name>]
+              <command> [<options>] [<args>]
+
+## DESCRIPTION
+**specify_cli** is a tool that allows certain tasks in a Specify database to be
+carried out from the command line.
+Specify is a management system for biological collections developed by the
+Specify Collections Consortium (http://www.sustain.specifysoftware.org).
+
+**specify_cli** is an independent development that is not supported by the
+Specify Collections Consortium. It operates directly on the MySQL/MariaDB
+backend used by Specify. **Use at your own risk**.
+
+Tasks currently supported:
+
+* upload of user interface form definitions (*.views.xml* files) to the database
+* generation of collection object stub records
+
+## FILES
+
+`~/.specify_dbs.rc.yaml` is a YAML file that stores information about
+Specify databases and directories containing *.views.xml* files.
+The file has the general structure:
+
+    ---
+    :dir_names:
+      <view_file_directory>: <hostname>
+      ...
+    :hosts:
+      <hostname>:
+        :port: <port_number>
+        :databases:
+          <database_name>:
+            :db_user:
+              :name: <mysql_username>
+              :password: <password>
+            :sp_user: <specify_username>
+          ...
+        ...
+
+The section `dir_names` contains directory-host-mappings. A directory-host-
+mapping is a key-value-pair, where the key is the path of a directory on your
+hard drive, the value is a host name. This is used to automatically resolve the
+correct host for a *.views.xml* file based on the directory it is in. Add
+mappings here by editing the file or using the **specify_cli-repository(1)**
+command.
+
+The section `hosts` contains settings for Specify databases by grouped by
+`<hostname>`. For each host, the `port` and any `databases` can be configured in
+this file by editing it or by using the **specify_cli-database(1)** command. The `databases` section contains connection settings for the individual databases by
+`<database_name>`. The `db_user` is the MySQL/MariaDB user used to connect to
+the database and will typically be the Specify *master user*. Leave `password`
+blank to be prompted for the password when you run the command (this will not
+work when triggered as a bash script from another application, e.g. a text
+editor). Apart from the `db_user` `specify_cli` also needs a Specify user (a
+user that Specify uses internally), which is provided under `sp_user`. Every
+command (except the configuration commands **specify_cli-database(1)** and **specify_cli-repository(1)**) will start a session in Specify where the Specify
+user will be logged in to the collection. Any records created or modified during
+this session will be marked as created by or modified by the `sp_user`.
+
+## COMMANDS
+
+* `specify_cli-database`(1)
+    Add a database configuration.
+* `specify_cli-stubs`(1)
+    Create stub records
+* `specify_cli-repository`(1)
+    Map a git repository to a host for automatic target resolution.
+* `specify_cli-viewset`(1)
+    Upload a view to the database.
+
+## OPTIONS
+
+* `-D`, `--database` <name>:
+    The name of the Specify database to connect to.
+* `-H`, `--host` <name>:
+    The name or IP address of the host. Default: `localhost`
+* `-P`, `--password` <password>:
+    The password for the MySQL/MariaDB user. Leave blank to be prompted.
+* `-U`, `--specify_user` <name>:
+    The name of the Specify user.
+* `-c`, `--db_config` <file>:
+    A database configuration file (if other than the default
+    `~/.specify_dbs.rc.yaml`)
+* `-p`, `--port` <number>:
+    The port for the MySQL/MariaDB host.
+* `-u`, `--user` <name>:
+    The MySQL/MariaDB user name.
+
+## EXAMPLES
+
+Configure a database `Specify` on the host `specify.example.org`:
+
+    $ specify_cli --host=specify.example.org database specify
+
+Map the current directory to the host `specify.example.org`:
+
+    $ specify_cli --host=specify.example.org repository -c
+
+Map `~/specify_forms/invertpaleo` to `localhost`:
+
+    $ specify_cli repository ~/specify_forms/invertpaleo
+
+Create 10 blank stub records in the collection `Triloites` in the database
+`Specify` on localhost:
+
+    $ specify_cli -D Specify stubs Trilobites 10
+
+Create 10 stub records for herbarium sheets in the collection `Orchids` in the
+database `Specify` on localhost, determined to taxon `Orchidaceae`:
+
+    $ specify_cli -D Specify stubs --taxon='Family: Orchidaceae'\n
+        --preptype=Sheet --perpcount=1 Orchids 10
+
+Upload `invertpaleo.views.xml` to discipline level for collection `Trilobites`
+in the database `Specify` on localhost:
+
+    $ specify_cli -D Specify viewset -d Trilobites invertpaleo.views.xml
+
+Upload `invertpaleo.views.xml` auto-resolving target from current Git branch:
+
+    $ specify_cli viewset -b invertpaleo.views.xml
+
+## LICENSE
+
+MIT License
+
+Copyright (c) 2018 Martin Stein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/spec/branch_parser_spec.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+TEST_BRANCH = 'SPSPEC/TestCollection/user/specuser'
+
+# Tests for the
+module Specify
+  RSpec.describe BranchParser do
+
+
+    context 'when creating instances from branch names' do
+      let :config do
+        Pathname.new(Dir.pwd).join('spec', 'support', 'db.yml')
+      end
+
+      let(:path) { 'sp_resource' }
+
+      let(:collection_level) { 'SPSPEC/TestCollection/collection' }
+      let(:discipline_level) { 'SPSPEC/TestCollection/discipline' }
+      let(:user_type_level) { 'SPSPEC/TestCollection/Manager' }
+      let(:user_level) { 'SPSPEC/TestCollection/user/specuser' }
+
+      let :config do
+        Pathname.new(Dir.pwd).join('spec', 'support', 'db.yml')
+      end
+
+      context 'when collection' do
+        subject { described_class.new path, collection_level, config }
+
+        it do
+          is_expected.to have_attributes host: 'localhost',
+                                         database: 'SPSPEC',
+        	                               collection: 'Test Collection',
+        	                               level: :collection
+        end
+      end
+
+      context 'when discipline' do
+        subject { described_class.new path, discipline_level, config }
+
+        it do
+          is_expected.to have_attributes host: 'localhost',
+                                         database: 'SPSPEC',
+        	                               collection: 'Test Collection',
+        	                               level: :discipline
+        end
+      end
+
+      context 'when user type' do
+        subject { described_class.new path, user_type_level, config }
+
+        it do
+          is_expected.to have_attributes host: 'localhost',
+                                         database: 'SPSPEC',
+        	                               collection: 'Test Collection',
+        	                               level: { user_type: :manager }
+        end
+      end
+
+      context 'when user' do
+        subject { described_class.new path, user_level, config }
+
+        it do
+          is_expected.to have_attributes host: 'localhost',
+                                         database: 'SPSPEC',
+        	                               collection: 'Test Collection',
+        	                               level: { user: 'specuser' }
+        end
+      end
+    end
+
+    context 'when fetching the git branch', skip: true do
+      before :all do
+      	@origin = `#{GIT_CURRENT_BRANCH}`.chomp
+      	break if TEST_BRANCH == @origin
+        set_branch
+      end
+
+    	it 'parses a name from the current branch' do
+        expect(described_class.current_branch)
+          .to have_attributes database: 'SPSPEC',
+                              collection: 'Test Collection',
+                              level: { user: 'specuser' }
+    	end
+
+    	it 'exits with an error message if the branch name is not parsable' do
+    		expect { described_class.new('master') }
+    		  .to raise_error ArgumentError, BRANCH_ERROR + 'master'
+    	end
+
+    	after :all do
+    	  system("git checkout #{@origin}")
+    	end
+    end
+  end
+end

data/spec/cli/stubs_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Specify
+  module CLI
+    RSpec.describe 'stubs' do
+      let :opts do
+        geo = 'Continent: North America; Country: United States;'\
+              ' locality: Springfield'
+        {
+          accession: "2018-AA-001",
+          cataloger: "specuser",
+          dataset: "Test dataset",
+          geography: geo,
+          locality: "Not transcribed",
+          taxon: "Kingdom: Plantae; Division: Tracheophyta",
+          preptype: "Sheet",
+          prepcount: "1",
+          file: nil
+        }
+      end
+
+      let :stub_params do
+        {
+          "dataset_name" => "Test dataset",
+          "cataloger" => "specuser",
+          "accession" => "2018-AA-001",
+          "collecting_data" => { "Continent" => "North America",
+                                 "Country" => "United States",
+                                 locality: 'Springfield' },
+          "default_locality_name" => "Not transcribed",
+          "determination" => { "Kingdom" => "Plantae",
+                               "Division" => "Tracheophyta" },
+          "preparation" => { type: "Sheet", count: "1" }
+        }
+      end
+
+      describe '.stub_parameters' do
+      	subject { CLI.stub_parameters opts }
+
+      	it { is_expected.to eq stub_params }
+      end
+    end
+  end
+end

data/spec/configuration/config_spec.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+# Tests for the
+module Specify
+  module Configuration
+    RSpec.describe Config do
+      subject { described_class.new file }
+
+      let(:config) { described_class.empty empty_file }
+
+      let :file do
+        Pathname.new(Dir.pwd).join('spec', 'support', 'db.yml')
+      end
+
+      let :empty_file do
+        Pathname.new(Dir.pwd).join('spec', 'support', 'empty.yml')
+      end
+
+      let :file_dir_names do
+        a_hash_including('sp_resource' => 'localhost')
+      end
+
+      let :file_hosts do
+        db_user = a_hash_including name: 'specmaster',
+                                   password: 'masterpass'
+        spspec = a_hash_including db_user: db_user,
+                                  sp_user: 'specuser'
+        databases = a_hash_including 'SPSPEC' => spspec
+        localhost = a_hash_including port: 3306,
+                                     databases: databases
+        a_hash_including 'localhost' => localhost
+      end
+
+      let :hosts do
+        a_hash_including 'localhost' => a_hash_including(port: 3600)
+      end
+
+      it do
+        is_expected.to have_attributes dir_names: file_dir_names,
+                                       hosts: file_hosts
+      end
+
+      describe '.empty' do
+        subject { described_class.empty empty_file }
+
+        before { FileUtils.touch default_file }
+
+        let(:default_file) { File.expand_path('~/.specify_dbs.rc.yaml') }
+
+        let :params do
+          a_hash_including dir_names: an_instance_of(Hash).and(be_empty),
+                           hosts: an_instance_of(Hash).and(be_empty)
+        end
+
+        it { is_expected.to have_attributes params: params }
+
+        context 'when passed no file but default file exists' do
+          subject(:make_empty)  { described_class.empty file }
+
+          it do
+            error = "#{file} exists, won't overwrite"
+            expect { make_empty }.to raise_error error
+          end
+        end
+
+        context 'when passed the dafault file path and default file exists' do
+          subject(:make_empty) { described_class.empty default_file }
+
+          it do
+            error = "#{default_file} exists, won't overwrite"
+            expect { make_empty }.to raise_error error
+          end
+        end
+
+        context 'when given block mapping dir_names' do
+          subject do
+            described_class.empty(empty_file) do |config|
+              config.dir_names['specify_dir'] = 'localhost'
+            end
+          end
+
+          let :dir_names do
+            a_hash_including 'specify_dir' => 'localhost'
+          end
+
+          it { is_expected.to have_attributes dir_names: dir_names }
+        end
+
+        context 'when given block adding hosts' do
+          subject do
+            described_class.empty(empty_file) do |config|
+              config.add_host 'localhost', 3600
+            end
+          end
+
+          it do
+            is_expected.to have_attributes hosts: hosts
+          end
+        end
+
+        context 'when given block adding databases' do
+          subject do
+            described_class.empty(empty_file) do |config|
+              config.add_database 'SPSPEC', host: 'localhost' do |db|
+                db[:db_user][:name] = 'specmaster'
+                db[:db_user][:password] = 'masterpass'
+                db[:sp_user] = 'specuser'
+              end
+            end
+          end
+
+          let :hosts do
+            db_user = a_hash_including name: 'specmaster',
+                                       password: 'masterpass'
+            spspec = a_hash_including db_user: db_user,
+                                      sp_user: 'specuser'
+            databases = a_hash_including 'SPSPEC' => spspec
+            localhost = a_hash_including databases: databases
+            a_hash_including 'localhost' => localhost
+          end
+
+          it { is_expected.to have_attributes hosts: hosts }
+        end
+      end
+
+      describe '#add_host' do
+        subject(:add_host) { config.add_host 'localhost', 3600 }
+
+        context 'when adding a new host' do
+          it do
+            expect { add_host }
+              .to change(config, :hosts).from(be_empty).to hosts
+          end
+        end
+
+        context 'when adding an existing host' do
+          before { config.add_host 'localhost' }
+
+          it do
+            expect { add_host }
+              .to raise_error 'Host \'localhost\' already configured'
+          end
+        end
+      end
+
+      describe '#add_database' do
+        subject :add_database do
+          config.add_database 'SPSPEC', host: 'localhost' do |db|
+            db[:db_user][:name] = 'specmaster'
+            db[:db_user][:password] = 'masterpass'
+            db[:sp_user] = 'specuser'
+          end
+        end
+
+        let :databases do
+          db_user = a_hash_including name: 'specmaster',
+                                     password: 'masterpass'
+          spspec = a_hash_including db_user: db_user,
+                                    sp_user: 'specuser'
+          a_hash_including 'SPSPEC' => spspec
+        end
+
+        context 'when the database is not configured for the host' do
+          let :localhost_db do
+            localhost = a_hash_including port: nil,
+                                         databases: databases
+            a_hash_including 'localhost' => localhost
+          end
+
+          it do
+            expect { add_database }
+              .to change(config, :hosts)
+              .from(be_empty).to(localhost_db)
+          end
+        end
+
+        context 'when the database is already configured for the host' do
+          before { config.add_database 'SPSPEC', host: 'localhost' }
+
+          let(:e) { 'Database \'SPSPEC\' on \'localhost\' already configured' }
+
+          it do
+            expect { add_database }
+              .to raise_error e
+          end
+        end
+      end
+
+      describe '#params' do
+        subject { described_class.new(file).params }
+
+        it do
+          is_expected.to be_a(Hash)
+            .and include(dir_names: file_dir_names,
+                         hosts: file_hosts)
+        end
+      end
+
+      describe '#save' do
+        subject(:save) { config.save }
+
+        let :dir_names do
+          a_hash_including 'specify_dir' => 'localhost'
+        end
+
+        let :hosts do
+          db_user = a_hash_including name: 'specmaster',
+                                     password: 'masterpass'
+          spspec = a_hash_including db_user: db_user,
+                                    sp_user: 'specuser'
+          databases = a_hash_including 'SPSPEC' => spspec
+          localhost = a_hash_including databases: databases,
+                                       port: 3600
+          a_hash_including 'localhost' => localhost
+        end
+
+        before do
+          config.dir_names['specify_dir'] = 'localhost'
+          config.add_host 'localhost', 3600
+          config.add_database 'SPSPEC', host: 'localhost' do |db|
+            db[:db_user][:name] = 'specmaster'
+            db[:db_user][:password] = 'masterpass'
+            db[:sp_user] = 'specuser'
+          end
+        end
+
+        it do
+          expect { save }
+            .to change { Psych.load_file(empty_file) }
+            .to include hosts: hosts, dir_names: dir_names
+        end
+
+        it do
+          expect { save }
+            .to change(config, :saved?).from(be_falsey).to be_truthy
+        end
+      end
+
+      describe '#saved?' do
+        subject { config.saved? }
+
+        context 'when the instance has not been modified' do
+          it { is_expected.to be_truthy }
+        end
+
+        context 'when the instance has been modified' do
+          before { config.touch }
+
+          it { is_expected.to be_falsey }
+        end
+      end
+
+      describe '#touch' do
+        subject(:touch) { config.touch }
+
+        it do
+          expect { touch }
+            .to change(config, :saved?).from(be_truthy).to be_falsey
+        end
+      end
+
+      after do
+        File.delete(empty_file) if File.exist?(empty_file)
+      end
+    end
+  end
+end