specify_cli 0.0.5

data/lib/specify/services/view_loader.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Specify
+  module Service
+    # ViewLoaders will upload _.views.xml_ files to a Specify::Database.
+    class ViewLoader < Service
+      # The target to which the ViewLoader uploads _.views.xml_ files; an
+      # instance of Specify::Model::Discipline, Specify::Model::Collection,
+      # Specify::UserType, or Specify::Model::User
+      attr_reader :target
+
+      # Creates a new instance from a branch +name+, if +name+ conforms to the
+      # naming convention <em>database_name/collection_name/level</em>, where
+      # _level_ is _discipline_, _collection_, _manager_, _fullaccess_,
+      # _limitedaccess_, or _guest_), or _user/username_.
+      #
+      # +path+ is the filepath for the view file to be uploaded.
+      #
+      # +config+ is the YAML file containing the database configuration.
+      def self.from_branch(config:, path: nil, name: nil)
+        parser = if name
+                   BranchParser.new(path, name, config)
+                 else
+                   BranchParser.current_branch config
+                 end
+        new parser.to_h.merge(config: config)
+      end
+
+      # Returns a new ViewLoader.
+      #
+      # +level+ is the level to which the _.views.xml_ file will be uploaded.
+      # valid values are _:discipline_, _:collection_,
+      # <tt>{ :user_type => String }</tt> (String Symbol must be a valid
+      # Specify::UserType#name) or <tt>{ :user => String }</tt> (where String
+      # must be an existing Specify::Model::User#user name).
+      def initialize(host:,
+                     database:,
+                     collection:,
+                     specify_user: nil,
+                     level: nil,
+                     config:)
+        super(host: host,
+              database: database,
+              collection: collection,
+              specify_user: specify_user,
+              config: config)
+        @target = nil
+        self.target = level
+      end
+
+      # Returns the Specify::Model::User instance for +hash+ if +hash+ has the
+      # key +:user+ and the value for that key is an existing
+      # Specify::Model::User#name.
+      def self.user_target(hash)
+        return unless hash.key? :user
+        Model::User.first(Name: hash[:user])
+      end
+
+      # Returns the Specify::UserType for +hash+ if hash has the key
+      # +user_type+, and the value for that key is a valid
+      # Specify::UserType#name.
+      def self.user_type_target(hash)
+        return unless hash.key? :user_type
+        UserType.new(hash[:user_type])
+      end
+
+      # Creates a string representation of +self+.
+      def inspect
+        "#{self} database: #{@db.database}, target: #{@target}"
+      end
+
+      # Loads the _views.xml_ +file+ and stores it as a SQL blob in the
+      # Specify::Model::ViewSetObject for the #target.
+      def import(file)
+        view_set = @target.view_set(collection) ||
+                   create_view_set(file)
+        view_set.import(views_file(file))
+      end
+
+      # Returns +true+ if the view is personal, +false+ otherwise.
+      def personal?
+        @target.is_a?(Model::User) ? true : false
+      end
+
+      # Sets the target for the instance. +level+ must be +:discipline+,
+      # +:collection+, or a Hash with the key :user_type and a valid
+      # Specify::UserType#name as value or the key +:user+ and an existing
+      # Specify::Model::User#name.
+      def target=(level)
+        return unless level
+        @target = case level
+                  when :collection
+                    collection
+                  when :discipline
+                    discipline
+                  else
+                    ViewLoader.user_target(level) ||
+                    ViewLoader.user_type_target(level)
+                  end
+      end
+
+      # Returns the Specify::Model::Collection that _views.xml_ files will be
+      # uploaded to (all supported upload levels except +:disciplin+ are
+      # scoped to a collection. Will be #collection or +nil+.
+      def view_collection
+        collection unless @target.is_a? Model::Discipline
+      end
+
+      # Returns the Specify::Model::Discipline that _views.xml_ files will be
+      # uploaded to.
+      def view_discipline
+        discipline
+      end
+
+      # Returns +2+ if the view is for a collection, +0+ otherwise.
+      def view_level
+        @target.is_a?(Model::Collection) ? 2 : 0
+      end
+
+      # Returns the Specify::Model::Discipline#name, which is the
+      # Specify::Model::AppResourceDir#discipline_type.
+      def view_type
+        view_discipline.name
+      end
+
+      # Returns the Specify::Model::User that _views.xml_ files will be
+      # uploaded to. Same as #session Specify::Session#user unless the view is
+      # for a different user.
+      def view_user
+        @target.is_a?(Model::User) ? @target : @session.user
+      end
+
+      # Returns a String with a valid Specify::UserType#name for #target.
+      def view_user_type
+        case @target
+        when UserType
+          @target.name.to_s
+        when Model::User
+          @target.UserType.downcase
+        end
+      end
+
+      private
+
+      def create_view_dir
+        vals = { created_by: agent,
+                 DisciplineType: view_type,
+                 UserType: view_user_type,
+                 IsPersonal: personal?,
+                 collection: view_collection,
+                 discipline: view_discipline,
+                 user: view_user }
+        @target.view_set_dir = @target.add_app_resource_dir(vals)
+      end
+
+      def create_view_set(file)
+        vals = { Level: view_level,
+                 FileName: file,
+                 Name: file.basename('.xml'),
+                 app_resource_dir: create_view_dir,
+                 created_by: agent }
+        view_set = Model::ViewSetObject.create vals
+        Model::AppResourceData.create viewsetobj: view_set,
+                                      created_by: agent
+        @target.save
+        view_set.save
+      end
+
+      def views_file(file)
+        raise ArgumentError, FileError::NO_FILE unless File.exist?(file)
+        path = Pathname.new file
+        return File.open path if path.file? && path.fnmatch?('*.views.xml')
+        raise ArgumentError, FileError::VIEWS_FILE
+      end
+    end
+  end
+end

data/lib/specify/session.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'observer'
+
+module Specify
+  # A Session is responsible for logging an existing Specify::Model::User in and
+  # out of a Specify::Model::Collection. Session objects are used to set the
+  # #created_by and #modified_by attributes for any record created or updated to
+  # the session #user.
+  class Session
+    include Observable
+
+    # +true+ if the session is open (the #user is logged in), +false+ otherwise.
+    attr_reader :active
+
+    # The Specify::Model::Collection that #user is logged in to during
+    # the life span of the session.
+    attr_reader :collection
+
+    # The Specify::Model::Discipline that #user is logged in to during
+    # the life span of the session.
+    attr_reader :discipline
+
+    # The Specify::Model::Division that #collection and #discipline belong to.
+    attr_reader :division
+
+    # The Specify::Model::User that is logged in to #collection during the
+    # session.
+    attr_reader :user
+
+    # Returns a new Session.
+    #
+    # +user+ is a String with an existing Specify::Model::User#name.
+    #
+    # +collection+ is a String with and existing
+    # Specify::Model::Collection#name.
+    def initialize(user, collection)
+      @user = Model::User.first(Name: user)
+      @collection = Model::Collection.first(CollectionName: collection)
+      @discipline = @collection.discipline
+      @division = @discipline.division
+      @active = false
+    end
+
+    # Creates a string representation of +self+.
+    def inspect
+      "#{self} specify user: #{@user}"\
+      ", collection: #{@collection}, open: #{@active}"
+    end
+
+    # Closes this session, logs #user out of #collection.
+    def close
+      @user.log_out
+      @active = false
+      changed
+      notify_observers(self)
+      self
+    end
+
+    # Opens this session, logs #user in to #collection.
+    def open
+      @user.log_in(@collection)
+      @active = true
+      self
+    end
+
+    # Returns +true+ if this session is currently open.
+    def open?
+      @active
+    end
+
+    # Returns the Specify::Model::Agent for #user in #division.
+    def session_agent
+      user.logged_in_agent
+    end
+  end
+end

data/lib/specify/user_type.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Specify
+  # A UserType represents a lvel to which _.views.xml_ files can be uploaded.
+  # This is the only level that is not represented by a proper Model class,
+  # the others being Specify::Model::Collection, Specify::Model::Discipline,
+  # and Specify::Model::User. Like the model classes, a UserType implements
+  # #view_set_dir and #view_set to give access to the correct
+  # Specify::Model::AppResourceDir and Specify::Model::ViewSetObject instances.
+  class UserType
+    # The Specify::Model::AppResourceDir associated with +self+
+    attr_writer :view_set_dir
+
+    # A String, must be either +manager+, +fullaccess+, +limitedaccess+, or
+    # +guest+
+    attr_reader :name
+
+    # Returns a new UserType.
+    # +name+ must be a valid #name.
+    def initialize(name)
+      @name = name.downcase
+      @view_set_dir = nil
+      valid?
+    end
+
+    # Returns a new instance of Specify::Model::AppResourceDir with +values+.
+    def add_app_resource_dir(values)
+      Model::AppResourceDir.create values
+    end
+
+    # Returns +self+.
+    #
+    # This is a dummy method to allow use as a Specify::ViewLoader#target
+    # alongside Specify::Model::Collection, Specify::Model::Discipline, and
+    # Specify::Model::User.
+    def save
+      self
+    end
+
+    # Returns +true+ if #name is any of +fullaccess+, +guest+, +limitedaccess+,
+    # or +manager+; +false+ otherwise.
+    def valid?
+      %w[fullaccess guest limitedaccess manager].include? @name
+    end
+
+    # Returns the Specify::Model::AppResourceDir for this user type (#name) in
+    # +collection+ (a Specify::Model::Collection).
+    def view_set_dir(collection)
+      Model::AppResourceDir.first(collection: collection,
+                                  discipline: collection.discipline,
+                                  UserType: @name.to_s,
+                                  IsPersonal: false)
+    end
+
+    # Returns the Specify::Model::ViewSetObject for this user type +collection+
+    # (a Specify::Model::Collection).
+    def view_set(collection)
+      view_set_dir(collection)&.view_set_object
+    end
+  end
+end

data/lib/specify/version.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Specify
+  # :nodoc:
+  VERSION = '0.0.5'
+
+  # :nodoc:
+  SUMMARY = 'A command line interface for Specify'
+
+  # :nodoc:
+  DESCRIPTION = <<~HEREDOC
+    specify_cli is a tool that allows certain tasks in a Specify database
+    (http://www.sustain.specifysoftware.org) to be carried out from the command
+    line.
+    Currently supported tasks:
+    - upload of views to the database
+    - generation of stub records
+  HEREDOC
+end

data/man/specify_cli-database.1

@@ -0,0 +1,60 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "SPECIFY_CLI\-DATABASE" "1" "August 2018" "" ""
+.
+.SH "NAME"
+\fBspecify_cli\-database\fR \- A command line interface for Specify
+.
+.SH "SYNOPSIS"
+\fBspecify_cli\fR [\fIglobal options\fR] \fBdatabase\fR \fIname\fR
+.
+.SH "DESCRIPTION"
+The database configuration file (default: \fI~/\.specify_dbs\.rc\.yaml\fR) has a \fBhosts\fR section which contains settings for Specify databases by grouped by \fIhostname\fR\.
+.
+.P
+Use the \fBdatabase\fR command to add information for a specific database using this command\.
+.
+.P
+Use the specify_cli global option \fB\-\-host\fR to provide the host information and pass the \fIname\fR of the database to configure as an argument\.
+.
+.P
+The command will look up the \fIhost\fR and \fIdatabase\fR in the database configuration file and ask for necessary information to configure either\. The command will not overwrite existing configurations\. If you need to change information, edit the file\.
+.
+.P
+Information required to configure a \fIhost\fR is the port number\.
+.
+.P
+Information required to configure a \fIdatabase\fR is the MySQL/MariaDB user name and password\. The user will be the typically be the Specify \fImaster user\fR (or any user with equivalent permissions on the database) Leave the password blank to be prompted when working with commands that read the file (\fBspecify_cli\-stubs(1)\fR, \fBspecify_cli\-viewset(1)\fR)\. Apart from the MySQL/MariaDB user, \fBspecify_cli\fR the command will also ask for a \fIspecify user\fR name\. Every command (except the configuration commands \fBspecify_cli\-database(1)\fR and \fBspecify_cli\-repository(1)\fR) 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 \fIspecify user\fR\.
+.
+.SH "OPTIONS"
+None\.
+.
+.SH "EXAMPLES"
+Configure a database \fBSpecify\fR on the host \fBspecify\.example\.org\fR:
+.
+.IP "" 4
+.
+.nf
+
+$ specify_cli \-\-host=specify\.example\.org database Specify
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Configure a database \fBSpecifyTest\fR on localhost:
+.
+.IP "" 4
+.
+.nf
+
+$ specify_cli database SpecifyTest
+.
+.fi
+.
+.IP "" 0
+.
+.SH "SPECIFY_CLI"
+Part of the specify_cli(1) suite

data/man/specify_cli-database.1.html

@@ -0,0 +1,137 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv='content-type' value='text/html;charset=utf8'>
+  <meta name='generator' value='Ronn/v0.7.3 (http://github.com/rtomayko/ronn/tree/0.7.3)'>
+  <title>specify_cli-database(1) - A command line interface for Specify</title>
+  <style type='text/css' media='all'>
+  /* style: man */
+  body#manpage {margin:0}
+  .mp {max-width:100ex;padding:0 9ex 1ex 4ex}
+  .mp p,.mp pre,.mp ul,.mp ol,.mp dl {margin:0 0 20px 0}
+  .mp h2 {margin:10px 0 0 0}
+  .mp > p,.mp > pre,.mp > ul,.mp > ol,.mp > dl {margin-left:8ex}
+  .mp h3 {margin:0 0 0 4ex}
+  .mp dt {margin:0;clear:left}
+  .mp dt.flush {float:left;width:8ex}
+  .mp dd {margin:0 0 0 9ex}
+  .mp h1,.mp h2,.mp h3,.mp h4 {clear:left}
+  .mp pre {margin-bottom:20px}
+  .mp pre+h2,.mp pre+h3 {margin-top:22px}
+  .mp h2+pre,.mp h3+pre {margin-top:5px}
+  .mp img {display:block;margin:auto}
+  .mp h1.man-title {display:none}
+  .mp,.mp code,.mp pre,.mp tt,.mp kbd,.mp samp,.mp h3,.mp h4 {font-family:monospace;font-size:14px;line-height:1.42857142857143}
+  .mp h2 {font-size:16px;line-height:1.25}
+  .mp h1 {font-size:20px;line-height:2}
+  .mp {text-align:justify;background:#fff}
+  .mp,.mp code,.mp pre,.mp pre code,.mp tt,.mp kbd,.mp samp {color:#131211}
+  .mp h1,.mp h2,.mp h3,.mp h4 {color:#030201}
+  .mp u {text-decoration:underline}
+  .mp code,.mp strong,.mp b {font-weight:bold;color:#131211}
+  .mp em,.mp var {font-style:italic;color:#232221;text-decoration:none}
+  .mp a,.mp a:link,.mp a:hover,.mp a code,.mp a pre,.mp a tt,.mp a kbd,.mp a samp {color:#0000ff}
+  .mp b.man-ref {font-weight:normal;color:#434241}
+  .mp pre {padding:0 4ex}
+  .mp pre code {font-weight:normal;color:#434241}
+  .mp h2+pre,h3+pre {padding-left:0}
+  ol.man-decor,ol.man-decor li {margin:3px 0 10px 0;padding:0;float:left;width:33%;list-style-type:none;text-transform:uppercase;color:#999;letter-spacing:1px}
+  ol.man-decor {width:100%}
+  ol.man-decor li.tl {text-align:left}
+  ol.man-decor li.tc {text-align:center;letter-spacing:4px}
+  ol.man-decor li.tr {text-align:right;float:right}
+  </style>
+</head>
+<!--
+  The following styles are deprecated and will be removed at some point:
+  div#man, div#man ol.man, div#man ol.head, div#man ol.man.
+
+  The .man-page, .man-decor, .man-head, .man-foot, .man-title, and
+  .man-navigation should be used instead.
+-->
+<body id='manpage'>
+  <div class='mp' id='man'>
+
+  <div class='man-navigation' style='display:none'>
+    <a href="#NAME">NAME</a>
+    <a href="#SYNOPSIS">SYNOPSIS</a>
+    <a href="#DESCRIPTION">DESCRIPTION</a>
+    <a href="#OPTIONS">OPTIONS</a>
+    <a href="#EXAMPLES">EXAMPLES</a>
+    <a href="#SPECIFY_CLI">SPECIFY_CLI</a>
+  </div>
+
+  <ol class='man-decor man-head man head'>
+    <li class='tl'>specify_cli-database(1)</li>
+    <li class='tc'></li>
+    <li class='tr'>specify_cli-database(1)</li>
+  </ol>
+
+  <h2 id="NAME">NAME</h2>
+<p class="man-name">
+  <code>specify_cli-database</code> - <span class="man-whatis">A command line interface for Specify</span>
+</p>
+
+<h2 id="SYNOPSIS">SYNOPSIS</h2>
+
+<p><code>specify_cli</code> [<var>global options</var>] <code>database</code> <var>name</var></p>
+
+<h2 id="DESCRIPTION">DESCRIPTION</h2>
+
+<p>The database configuration file (default: <em>~/.specify_dbs.rc.yaml</em>) has a
+<code>hosts</code> section which contains settings for Specify databases by grouped by
+<em>hostname</em>.</p>
+
+<p>Use the <code>database</code> command to add information for a specific database using this command.</p>
+
+<p>Use the specify_cli global option <code>--host</code> to provide the host information and
+pass the <em>name</em> of the database to configure as an argument.</p>
+
+<p>The command will look up the <em>host</em> and <em>database</em> in the database configuration
+file and ask for necessary information to configure either. The command will
+not overwrite existing configurations. If you need to change information, edit
+the file.</p>
+
+<p>Information required to configure a <em>host</em> is the port number.</p>
+
+<p>Information required to configure a <em>database</em> is the MySQL/MariaDB user name
+and password. The user will be the typically be the Specify <em>master user</em> (or
+any user with equivalent permissions on the database) Leave the password blank
+to be prompted when working with commands that read the file (<strong><span class="man-ref">specify_cli-stubs<span class="s">(1)</span></span></strong>, <strong><span class="man-ref">specify_cli-viewset<span class="s">(1)</span></span></strong>). Apart from the
+MySQL/MariaDB user, <code>specify_cli</code> the command will also ask for a <em>specify user</em>
+name. Every command (except the configuration commands
+<strong><a class="man-ref" href="specify_cli-database.1.html">specify_cli-database<span class="s">(1)</span></a></strong> and <strong><span class="man-ref">specify_cli-repository<span class="s">(1)</span></span></strong>) 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 <em>specify user</em>.</p>
+
+<h2 id="OPTIONS">OPTIONS</h2>
+
+<p>None.</p>
+
+<h2 id="EXAMPLES">EXAMPLES</h2>
+
+<p>Configure a database <code>Specify</code> on the host <code>specify.example.org</code>:</p>
+
+<pre><code>$ specify_cli --host=specify.example.org database Specify
+</code></pre>
+
+<p>Configure a database <code>SpecifyTest</code> on localhost:</p>
+
+<pre><code>$ specify_cli database SpecifyTest
+</code></pre>
+
+<h2 id="SPECIFY_CLI">SPECIFY_CLI</h2>
+
+<p>Part of the <span class="man-ref">specify_cli<span class="s">(1)</span></span> suite</p>
+
+
+  <ol class='man-decor man-foot man foot'>
+    <li class='tl'></li>
+    <li class='tc'>August 2018</li>
+    <li class='tr'>specify_cli-database(1)</li>
+  </ol>
+
+  </div>
+</body>
+</html>