alma_course_loader 0.9.1

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/alma_course_loader.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'alma_course_loader/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'alma_course_loader'
+  spec.version       = AlmaCourseLoader::VERSION
+  spec.authors       = ['Lancaster University Library']
+  spec.email         = ['library.dit@lancaster.ac.uk']
+
+  spec.summary       = 'Support for creating Alma course loader files'
+  spec.description   = 'This gem provides basic support for creating Alma' \
+                       'course loader files.'
+  spec.homepage      = 'https://github.com/lulibrary/alma_course_loader'
+  spec.license       = 'MIT'
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'clamp'
+  spec.add_dependency 'dotenv'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'minitest'
+  spec.add_development_dependency 'minitest-reporters'
+  spec.add_development_dependency 'rubocop'
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "alma_course_loader"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/course_loader_diff

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'alma_course_loader/cli/diff'
+
+dsn = ENV['SENTRY_DSN']
+unless dsn.nil? || dsn.empty?
+  require 'raven'
+  Raven.configure { |config| config.dsn = dsn }
+end
+AlmaCourseLoader::CLI::Diff.run

data/lib/alma_course_loader.rb

@@ -0,0 +1,8 @@
+require 'alma_course_loader/diff'
+require 'alma_course_loader/filter'
+require 'alma_course_loader/reader'
+require 'alma_course_loader/writer'
+require 'alma_course_loader/version'
+
+# A framework for generating Alma course loader files
+module AlmaCourseLoader; end

data/lib/alma_course_loader/cli/course_loader.rb

@@ -0,0 +1,129 @@
+require 'clamp'
+require 'dotenv'
+
+require 'alma_course_loader/filter'
+
+module AlmaCourseLoader
+  module CLI
+    # The abstract base class for course loader command line processing
+    # @abstract Loader implementations should subclass this class and implement
+    #   the #extractors, #reader and #time_period methods
+    class CourseLoader < Clamp::Command
+      # Exit codes
+      EXIT_OK = 0
+
+      # Clamp command-line options
+      option %w[-d --delete], :flag, 'generate a course delete file'
+      option %w[-e --env-file], 'ENV_FILE', 'environment definitions file'
+      option %w[-f --filter], 'FILTER',
+             'filter condition: [field][op]value', multivalued: true do |value|
+        AlmaCourseLoader::Filter.parse(value, extractors)
+      end
+      option %w[-F --fields], :flag, 'list the fields available to filters'
+      option %w[-l --log-file], 'LOG_FILE', 'the activity log file'
+      option %w[-L --log-level], 'LOG_LEVEL',
+             'the log level (fatal|error|warn|info|debug)' do |value|
+        {
+          debug: Logger::DEBUG,
+          error: Logger::ERROR,
+          fatal: Logger::FATAL,
+          info: Logger::INFO,
+          warn: Logger::WARN
+        }[value.downcase.to_sym] || Logger::ERROR
+      end
+      option %w[-o --out-file], 'OUT_FILE', 'the output file'
+      option %w[-r --rollover], :flag, 'generate a course rollover file'
+      option %w[-t --time-period], 'PERIOD',
+             'the academic year (2016 etc.)', multivalued: true do |value|
+        time_period(value)
+      end
+      option %w[-T --current-time-period], 'CURRENT_PERIOD',
+             'the current academic year' do |value|
+        time_period(value)
+      end
+
+      # Displays an error message and exits
+      # @param msg [String, nil] the error message
+      # @param code [Integer] the exit code - do not exit if nil
+      # @return [void]
+      def error(msg = nil, code = nil)
+        STDERR.puts(msg) if msg
+        exit(code) if code
+      end
+
+      # Returns a hash of named field value extractor descriptions. Keys
+      # correspond to the keys of the extractors hash, values should be short
+      # descriptions of each field extractor.
+      # @abstract Subclasses should implement this method
+      # @return [Hash<String|Symbol, String>] the field extractor descriptions
+      def extractor_details
+        nil
+      end
+
+      # Returns a hash of named field value extractors
+      # @abstract Subclasses must implement this method
+      # @return [Hash<String|Symbol, Method|Proc>] the field extractors
+      def extractors
+        raise NotImplementedError
+      end
+
+      # Clamp entry point - executes the command
+      # @return [void]
+      def execute
+        # List the available field extractors and exit if required
+        list_fields if fields?
+        # Otherwise write a course loader file and exit
+        write_file
+      end
+
+      # Lists the available field extractors and exits
+      # @return [void]
+      def list_fields
+        d = extractor_details || {}
+        extractors.each_key { |k| puts "#{k}#{d[k] ? ': ' : ''}#{d[k] || ''}" }
+        exit(EXIT_OK)
+      end
+
+      # Creates a Logger instance
+      # @return [Logger] the Logger instance
+      def logger
+        return nil unless log_file
+        logger = Logger.new(log_file)
+        logger.level = log_level
+        logger
+      end
+
+      # Creates a Reader instance to retrieve course data
+      # @abstract Subclasses must implement this method.
+      #   Filters are defined in the filter_list array:
+      #     MyReader.new(..., filters: filter_list)
+      # @return [AlmaCourseLoader::Reader] a subclass of Reader
+      def reader
+        raise NotImplementedError
+      end
+
+      # Parses a time period string and returns an appropriate representation
+      # @abstract Subclasses may implement this method
+      # @param time_period_s [String] the time period string
+      # @return [Object] the subclass-specific representation of the time period
+      def time_period(time_period_s)
+        time_period_s
+      end
+
+      # Writes an Alma course loader file and exits
+      # @return [void]
+      def write_file
+        op = if rollover?
+               :rollover
+             elsif delete?
+               :delete
+             else
+               :update
+             end
+        Dotenv.load(env_file) unless env_file.nil? || env_file.empty?
+        AlmaCourseLoader::Writer.write(out_file, op, reader)
+        exit(EXIT_OK)
+      end
+    end
+  end
+end

data/lib/alma_course_loader/cli/diff.rb

@@ -0,0 +1,85 @@
+require 'clamp'
+require 'logger'
+
+module AlmaCourseLoader
+  module CLI
+    # Implements the course_loader_diff command-line interface
+    class Diff < Clamp::Command
+      # Exit codes
+      EXIT_OK = 0
+      # Log file alignment for multi-line entries
+      LOG_SPACE = '                     '.freeze
+      private_constant :LOG_SPACE
+      # Log file timestamp
+      LOG_TIME = '%Y-%m-%d %H:%M:%S: '.freeze
+
+      option %w[-c --create], 'FILE', 'write new courses to FILE'
+      option %w[-d --delete], 'FILE', 'write deleted courses to FILE'
+      option %w[-l --log], 'FILE', 'log activity to FILE',
+             attribute_name: :log_file
+      option %w[-r --rollover], :flag,
+             'create courses with rollover if rollover course/section is given'
+      option %w[-u --update], 'FILE', 'write updated courses to FILE'
+      option %w[-v --verbose], :flag, 'enable verbose logging'
+      parameter 'OLD', 'the old course loader file', attribute_name: :old_file
+      parameter 'NEW', 'the new course loader file', attribute_name: :new_file
+
+      # Clamp entry point - executes the command
+      def execute
+        filename = log_filename
+        @logger = logger(filename)
+        ::AlmaCourseLoader::Diff.diff(old_file, new_file,
+                                      create: create, delete: delete,
+                                      rollover: rollover?,
+                                      update: update) do |old, new, op, opts|
+          log(old, new, op, opts) if @logger
+        end
+        @logger.close if @logger && filename
+        exit(EXIT_OK)
+      end
+
+      # Logs a course update operation
+      # @param old [String] the course entry from the old file
+      # @param new [String] the course entry from the new file
+      # @param op [Symbol] the course operation (:create|:delete|:update)
+      # @param opts [Hash<Symbol, Object>] the diff options
+      # @return [void]
+      def log(old, new, op, opts)
+        fields = log_course_fields(old, new, op, opts)
+        course = "#{fields[0]}:#{fields[2]}"
+        @logger.info("#{op.to_s.capitalize} #{course}\n")
+        return unless verbose?
+        @logger.debug("#{old.nil? ? '' : '< '}#{old}\n") if old
+        @logger.debug("#{new.nil? ? '' : '> '}#{new}\n") if new
+      end
+
+      # Returns the course entry fields
+      # @param old [String] the course entry from the old file
+      # @param new [String] the course entry from the new file
+      # @param op [Symbol] the course operation (:create|:delete|:update)
+      # @param opts [Hash<Symbol, Object>] the diff options
+      def log_course_fields(old, new, op, opts)
+        op == :delete ? old.split("\t") : new.split("\t")
+      end
+
+      # Returns the command-line log filename or nil to force logging to STDOUT
+      # @return [String, nil] the log filename
+      def log_filename
+        log_file.nil? || log_file.empty? || log_file == '-' ? nil : log_file
+      end
+
+      # Returns a Logger instance
+      # @param filename [String, nil] the log filename, or nil to log to STDOUT
+      # @return [Logger] the logger
+      def logger(filename = nil)
+        logger = Logger.new(filename || STDOUT)
+        logger.level = verbose? ? Logger::DEBUG : Logger::INFO
+        logger.formatter = proc do |severity, datetime, _prog_name, msg|
+          time_s = severity == 'DEBUG' ? LOG_SPACE : datetime.strftime(LOG_TIME)
+          "#{time_s}#{msg}"
+        end
+        logger
+      end
+    end
+  end
+end

data/lib/alma_course_loader/diff.rb

@@ -0,0 +1,173 @@
+require 'logger'
+
+module AlmaCourseLoader
+  # Exception raised by the diff block to ignore the current course
+  class SkipCourse < StandardError; end
+
+  # Compares two course loader files and outputs separate files of new, deleted
+  # and updated courses
+  class Diff
+    # Course loader operations
+    OPS = %i[create delete update].freeze
+
+    class << self
+      # Reports differences between old and new course loader files
+      # @param old_file [String] the old course loader filename
+      # @param new_file [String] the new course loader filename
+      # @param opts [Hash] the diff options
+      # @option opts [IO] :create the new courses file
+      # @option opts [IO] :delete the deleted courses file
+      # @option opts [Boolean] :rollover if true, create new courses as
+      #   rollovers when rollover course/section are present
+      # @option opts [IO] :update the updated courses file
+      # @yield [old_line, new_line, op, opts] passes course loader lines,
+      #   operation (:create|:delete|:update) and diff options to the block; the
+      #   block is only called for differences between files
+      # @yieldparam old_line [String] the old course loader line
+      # @yieldparam new_line [String] the new course loader line
+      # @yieldparam op [Symbol] the operation (:create|:delete|:update)
+      # @yieldparam opts [Hash] the diff options
+      # @return [void]
+      def diff(old_file = nil, new_file = nil, **opts, &block)
+        # Read the course loader data from the old and new files
+        old = read(old_file)
+        new = read(new_file)
+        # Create the creations, deletions and updates output files
+        files = open_output_files(opts)
+        # Perform the diff
+        process(old, new, files, opts, &block)
+      ensure
+        close_output_files(files)
+      end
+
+      private
+
+      # Returns true if the course entry has rollover course/section, else false
+      # @param fields [Array<String>] the course loader fields
+      # @return [Boolean] true if rollover course/section are set, else false
+      def can_rollover?(fields)
+        # Rollover requires course code and section
+        return false if fields[29].nil? || fields[29].empty?
+        return false if fields[30].nil? || fields[30].empty?
+        true
+      end
+
+      # Closes output files
+      # @param files [Hash<Symbol, IO>] the output files
+      # @return [void]
+      def close_output_files(files = nil)
+        files.values.each(&:close) if files
+      end
+
+      # Formats the course loader line for the specified operation
+      # @param line [String] the course loader line
+      # @param op [Symbol] the operation (:create|:delete|:update)
+      # @param opts [Hash<Symbol, Object>] the diff options
+      # @return [String] the course loader line with the specified operation
+      def format(line, op, opts = {})
+        # Format the line (rollover code/section are never needed)
+        line = line.split("\t")
+        if op == :create && opts[:rollover] && can_rollover?(line)
+          line[28] = 'ROLLOVER' # Rollover code/section already present
+        elsif op == :delete
+          line[28..30] = ['DELETE', '', ''] # Rollover code/section not needed
+        else # op is either :create without rollover or :update
+          line[28..30] = ['', '', ''] # Update, rollover code/section not needed
+        end
+        # Return the formatted line
+        line.join("\t")
+      end
+
+      # Returns the key for the course loader data hash
+      # @param fields [Array<String>] the course loader entry fields
+      # @return [String] the key for the course loader data hash
+      def key(fields)
+        # course-code:section-id
+        "#{fields[0]}:#{fields[2]}"
+      end
+
+      # Creates an output file
+      # @param file [IO, String] the output file instance or filename
+      # @param mode [String] the output file mode
+      # @return [IO] the output file
+      def open(file, mode = 'w')
+        return file if file.nil? || file.is_a?(IO)
+        raise ArgumentError('IO or filename expected') unless file.is_a?(String)
+        File.open(file, mode)
+      end
+
+      # Creates output files
+      # @param opts [Hash] the diff options
+      # @return [Hash<Symbol, IO>] the output files, indexed by operation
+      #   (:create|:delete|:update)
+      def open_output_files(opts)
+        files = {}
+        OPS.each { |op| files[op] = open(opts[op]) }
+        files
+      end
+
+      # Returns the diff operation
+      # @param old_line [String] the old course loader line
+      # @param new_line [String] the new course loader line
+      # @return [Symbol, nil] the operation (:create|:delete|:update) or nil if
+      #   there are no changes
+      def operation(old_line = nil, new_line = nil)
+        return nil if old_line == new_line
+        return :create if old_line.nil?
+        return :delete if new_line.nil?
+        :update
+      end
+
+      # Process the input files
+      # @param old [Hash<String, String>] the old course loader data
+      # @param new [Hash<String, String>] the new course loader data
+      # @param files [Hash<Symbol, IO>] the output files, indexed by operation
+      #   (:create|:delete|:update)
+      # @param opts [Hash] the diff options
+      # @return [void]
+      def process(old, new, files = nil, opts = {}, &block)
+        # Handle deletions and updates to the old file
+        old.each do |course, line|
+          write(line, new[course], files, opts, &block)
+        end
+        # Handle new additions to the old file
+        new.each do |course, line|
+          write(nil, line, files, opts, &block) unless old.key?(course)
+        end
+      end
+
+      # Returns the course loader file data as a hash: { course => loader line }
+      # @param filename [String] the course loader filename
+      # @return [Hash<String, String>] the course loader data
+      def read(filename)
+        result = {}
+        File.readlines(filename).each do |line|
+          line.chomp!
+          fields = line.split("\t")
+          result[key(fields)] = line
+        end
+        result
+      end
+
+      # Write the diff result to the appropriate output file
+      # @param old_line [String] the old course loader line
+      # @param new_line [String] the new course loader line
+      # @param files [Hash<Symbol, IO>] the output files, indexed by operation
+      #   (:create|:delete|:update)
+      # @param opts [Hash] the diff options
+      # @return [void]
+      def write(old_line = nil, new_line = nil, files = nil, opts = {})
+        # Determine the diff operation
+        op = operation(old_line, new_line)
+        return if op.nil?
+        # Call the block
+        yield(old_line, new_line, op, opts) if block_given?
+        # Write the line to the update file
+        line = op == :delete ? old_line : new_line
+        files[op].write("#{format(line, op, opts)}\n") if files[op]
+      rescue SkipCourse
+        # The block requested that this course is skipped
+      end
+    end
+  end
+end