locabulary 0.3.1 → 0.5.0

data/lib/locabulary/commands/active_hierarchical_roots_command.rb

@@ -0,0 +1,78 @@
+require 'set'
+require 'date'
+require 'locabulary/items'
+require 'locabulary/exceptions'
+
+module Locabulary
+  module Commands
+    # Responsible for transforming the flat data for the given :predicate_name
+    # into a hierarchy.
+    class ActiveHierarchicalRootsCommand
+      def self.cache
+        @cache ||= {}
+      end
+      private_class_method :cache
+
+      # @api private
+      def self.reset_cache!
+        @cache = {}
+      end
+
+      # @api private
+      # @since 0.5.0
+      #
+      # @param options [Hash]
+      # @option options [String] :predicate_name
+      # @option options [Date] :as_of (Date.today)
+      #
+      # @note A concession about the as_of; This is not a live Utility. The data has a
+      #   low churn rate. And while the date is important, I'm not as concerned
+      #   about the local controlled vocabulary exposing a date that has expired.
+      #   When we next deploy the server changes, the deactivated will go away.
+      def self.call(options = {})
+        predicate_name = options.fetch(:predicate_name)
+        cache[predicate_name] ||= new(options).call
+      end
+
+      def initialize(options = {})
+        @predicate_name = options.fetch(:predicate_name)
+        @as_of = options.fetch(:as_of) { Date.today }
+        @builder = Item.builder_for(predicate_name: predicate_name)
+        @utility_service = options.fetch(:utility_service) { default_utility_service }
+      end
+
+      def call
+        items = []
+        hierarchy_graph_keys = {}
+        top_level_slugs = Set.new
+        utility_service.with_active_extraction_for(predicate_name, as_of) do |data|
+          item = builder.call(data.merge('predicate_name' => predicate_name))
+          items << item
+          top_level_slugs << item.root_slug
+          hierarchy_graph_keys[item.term_label] = item
+        end
+        associate_parents_and_childrens_for(hierarchy_graph_keys, items)
+        top_level_slugs.map { |slug| hierarchy_graph_keys.fetch(slug) }
+      end
+
+      private
+
+      attr_reader :predicate_name, :as_of, :builder, :utility_service
+
+      def default_utility_service
+        require 'locabulary/utility'
+        Utility
+      end
+
+      def associate_parents_and_childrens_for(hierarchy_graph_keys, items)
+        items.each do |item|
+          begin
+            hierarchy_graph_keys.fetch(item.parent_term_label).add_child(item) unless item.parent_slugs.empty?
+          rescue KeyError => error
+            raise Exceptions::MissingHierarchicalParentError.new(predicate_name, error)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/locabulary/commands/active_items_for_command.rb

@@ -0,0 +1,58 @@
+require 'date'
+require 'json'
+require 'locabulary/items'
+require 'locabulary/utility'
+
+module Locabulary
+  module Commands
+    # Responsible for extracting a non-hierarchical sorted array of Locabulary::Item for the given predicate_name
+    #
+    # @see Locabulary::Item
+    class ActiveItemsForCommand
+      def self.cache
+        @cache ||= {}
+      end
+      private_class_method :cache
+
+      # @api private
+      # @since 0.5.0
+      def self.reset_cache!
+        @cache = {}
+      end
+
+      # @api private
+      # @since 0.5.0
+      #
+      # @param options [Hash]
+      # @option options [String] :predicate_name
+      # @option options [Date] :as_of (Date.today)
+      #
+      # @note A concession about the as_of; This is not a live Utility. The data has a
+      #   low churn rate. And while the date is important, I'm not as concerned
+      #   about the local controlled vocabulary exposing a date that has expired.
+      #   When we next deploy the server changes, the deactivated will go away.
+      def self.call(options = {})
+        predicate_name = options.fetch(:predicate_name)
+        cache[predicate_name] ||= new(options).call
+      end
+
+      def initialize(options = {})
+        @predicate_name = options.fetch(:predicate_name)
+        @as_of = options.fetch(:as_of) { Date.today }
+        @builder = Item.builder_for(predicate_name: predicate_name)
+      end
+
+      def call
+        collector = []
+        Utility.with_active_extraction_for(predicate_name, as_of) do |data|
+          collector << builder.call(data.merge('predicate_name' => predicate_name))
+        end
+        collector.sort
+      end
+
+      private
+
+      attr_reader :predicate_name, :as_of, :builder
+    end
+  end
+end

data/lib/locabulary/commands/build_ordered_hierarchical_tree_command.rb

@@ -0,0 +1,80 @@
+require 'set'
+require 'locabulary'
+require 'locabulary/exceptions'
+require 'locabulary/item'
+require 'locabulary/facet_wrapper_for_item'
+
+module Locabulary
+  module Commands
+    # Responsible for building a hierarchical tree from faceted items, and ordering the nodes as per the presentation sequence for the
+    # associated predicate_name.
+    class BuildOrderedHierarchicalTreeCommand
+      # @api private
+      # @since 0.5.0
+      #
+      # @param options [Hash]
+      # @option predicate_name [String]
+      # @option faceted_items [Array<#hits, #value>]
+      # @option faceted_item_hierarchy_delimiter [String]
+      #
+      # @return [Array<FacetWrapperForItem>]
+      def self.call(options = {})
+        new(options).call
+      end
+
+      def initialize(options = {})
+        @predicate_name = options.fetch(:predicate_name)
+        @faceted_items = options.fetch(:faceted_items)
+        @faceted_item_hierarchy_delimiter = options.fetch(:faceted_item_hierarchy_delimiter)
+        @builder = Item.builder_for(predicate_name: predicate_name)
+      end
+
+      def call
+        items = []
+        hierarchy_graph_keys = {}
+        top_level_slugs = Set.new
+        faceted_items.each do |faceted_item|
+          item = build_item(faceted_item)
+          items << item
+          top_level_slugs << item.root_slug
+          hierarchy_graph_keys[item.term_label] = item
+        end
+        associate_parents_and_childrens_for(hierarchy_graph_keys, items)
+        top_level_slugs.map { |slug| hierarchy_graph_keys.fetch(slug) }.sort
+      end
+
+      private
+
+      attr_reader :builder, :predicate_name, :faceted_items, :faceted_item_hierarchy_delimiter
+
+      def associate_parents_and_childrens_for(hierarchy_graph_keys, items)
+        items.each do |item|
+          begin
+            hierarchy_graph_keys.fetch(item.parent_term_label).add_child(item) unless item.parent_slugs.empty?
+          rescue KeyError => error
+            raise Exceptions::MissingHierarchicalParentError.new(predicate_name, error)
+          end
+        end
+      end
+
+      def build_item(faceted_node)
+        term_label = faceted_node.value
+        locabulary_item = find_locabulary_item(predicate_name: predicate_name, term_label: term_label)
+        if locabulary_item
+          FacetWrapperForItem.build_for_faceted_node_and_locabulary_item(faceted_node: faceted_node, locabulary_item: locabulary_item)
+        else
+          FacetWrapperForItem.build_for_faceted_node(faceted_node: faceted_node, predicate_name: predicate_name, term_label: term_label)
+        end
+      end
+
+      def find_locabulary_item(*args)
+        Locabulary.item_for(*args)
+      rescue Exceptions::ItemNotFoundError, Exceptions::MissingPredicateNameError
+        # Either the predicate name didn't exist or the item didn't exist for the given predicate name
+        # Given that we are building from an alternate source, this is an acceptable error. It is possible
+        # that we want to consider a developer notification but not abort the whole process.
+        nil
+      end
+    end
+  end
+end

data/lib/locabulary/exceptions.rb

@@ -4,6 +4,17 @@ module Locabulary
     class RuntimeError < ::RuntimeError
     end
 
+    # There was a problem finding an item
+    class ItemNotFoundError < RuntimeError
+      def initialize(predicate_name, label)
+        super("Unable to find label=#{label.inspect} for predicate_name=#{predicate_name.inspect}")
+      end
+    end
+
+    # An error occurred in attempting to find a given predicate_name in the data store
+    class MissingPredicateNameError < RuntimeError
+    end
+
     # There is a problem with the hierarchy; A child is being defined without a defined parent.
     class MissingHierarchicalParentError < RuntimeError
       attr_reader :predicate_name, :error
@@ -13,13 +24,5 @@ module Locabulary
         super("Expected #{predicate_name.inspect} to have a welformed tree. Error: #{error}")
       end
     end
-
-    # There is a problem with the hierarchy; Instead of a tree we have a multitude of trees
-    class TooManyHierarchicalRootsError < RuntimeError
-      attr_reader :predicate_name, :roots
-      def initialize(predicate_name, roots)
-        super("Expected fewer root slugs for #{predicate_name.inspect}. Roots encountered: #{roots.inspect}")
-      end
-    end
   end
 end

data/lib/locabulary/facet_wrapper_for_item.rb

@@ -0,0 +1,58 @@
+require 'forwardable'
+require 'delegate'
+
+module Locabulary
+  # A wrapper for a Locabulary::Items::Base that includes information from
+  # the SOLR Utility.
+  class FacetWrapperForItem < SimpleDelegator
+    # @api public
+    # @since 0.5.0
+    #
+    # In some cases, we may have a facet with a term_label that is not found in the existing data storage.
+    # Instead of throwing an exception, we can make a reasonable approximation for that item based on the given parameters.
+    #
+    # @see Locabulary::FacetedHierarchicalTreeSorter
+    #
+    # @param options [Hash]
+    # @option predicate_name [String]
+    # @option faceted_node [#qvalue, #value, #hits]
+    # @option term_label [String]
+    # @return Locabulary::FacetWrapperForItem
+    def self.build_for_faceted_node(options = {})
+      predicate_name = options.fetch(:predicate_name)
+      faceted_node = options.fetch(:faceted_node)
+      term_label = options.fetch(:term_label)
+      locabulary_item = Locabulary::Item.build(predicate_name: predicate_name, term_label: term_label, default_presentation_sequence: nil)
+      new(faceted_node: faceted_node, locabulary_item: locabulary_item)
+    end
+
+    # @api public
+    # @since 0.5.0
+    #
+    # In some cases, we have a facet and a locabulary item and this is the public method for building the wrapped object.
+    #
+    # @see Locabulary::FacetedHierarchicalTreeSorter
+    # @param options [Hash]
+    # @option predicate_name [String]
+    # @option faceted_node [#qvalue, #value, #hits]
+    # @option term_label [String]
+    # @return Locabulary::FacetWrapperForItem
+    def self.build_for_faceted_node_and_locabulary_item(options = {})
+      new(options)
+    end
+
+    # Don't access .new directly; Use the above builders
+    private_class_method :new
+
+    def initialize(options = {})
+      @__faceted_node__ = options.fetch(:faceted_node)
+      @__locabulary_item__ = options.fetch(:locabulary_item)
+      super(@__locabulary_item__)
+    end
+
+    attr_reader :__faceted_node__, :__locabulary_item__
+
+    extend Forwardable
+    def_delegators :__faceted_node__, :qvalue, :value, :hits
+  end
+end

data/lib/locabulary/item.rb

@@ -0,0 +1,40 @@
+require 'active_support/core_ext/string/inflections'
+require 'locabulary/items'
+
+module Locabulary
+  # A container of builder methods for items
+  module Item
+    # @api public
+    # @since 0.2.1
+    #
+    # A Factory method that is responsible for building the appropriate object given a :predicate_name and additional attributes.
+    #
+    # @param attributes [Hash]
+    # @option predicate_name [String]
+    # @return [Locabulary::Item]
+    # @see Locabulary::Items
+    def self.build(attributes = {})
+      predicate_name = attributes.fetch(:predicate_name) { attributes.fetch('predicate_name') }
+      builder_for(predicate_name: predicate_name).call(attributes)
+    end
+
+    # @api public
+    # @since 0.2.1
+    #
+    # Responsible for finding the appropriate Factory method for building a Locabulary::Item
+    #
+    # @param options [Hash]
+    # @option predicate_name [String] Used for lookup of the correct Locabulary::Item type
+    # @return [#call] A builder method (`.new` for the given constant)
+    def self.builder_for(options = {})
+      predicate_name = options.fetch(:predicate_name)
+      possible_class_name_for_predicate_name = predicate_name.singularize.classify
+      klass = begin
+        Items.const_get(possible_class_name_for_predicate_name)
+      rescue NameError
+        Items::Base
+      end
+      klass.method(:new)
+    end
+  end
+end

data/lib/locabulary/items.rb

@@ -1,32 +1,11 @@
 require 'locabulary/items/base'
-require 'hanami/utils/string'
+require 'locabulary/items/administrative_unit'
 module Locabulary
-  # A container for the various types of Locabulary Items
+  # @since 0.5.0
+  #
+  # A container module for data structures that conform to the Locabulary::Items::Base interface
+  #
+  # @see Locabulary::Item for additional interaction
   module Items
-    module_function
-
-    # @api public
-    # @since 0.2.1
-    def build(options = {})
-      predicate_name = options.fetch(:predicate_name) { options.fetch('predicate_name') }
-      builder_for(predicate_name: predicate_name).call(options)
-    end
-
-    # @api public
-    # @since 0.2.1
-    #
-    # @param options [Hash]
-    # @option predicate_name [String] Used for lookup of the correct Locabulary::Item type
-    def builder_for(options = {})
-      predicate_name = options.fetch(:predicate_name)
-      possible_class_name_for_predicate_name = Hanami::Utils::String.new(predicate_name).singularize.classify
-      klass = begin
-        Items.const_get(possible_class_name_for_predicate_name)
-      rescue NameError
-        Items::Base
-      end
-      klass.method(:new)
-    end
   end
 end
-require 'locabulary/items/administrative_unit'

data/lib/locabulary/items/administrative_unit.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 require 'locabulary/exceptions'
 require 'locabulary/items/base'
 
@@ -27,45 +28,16 @@ module Locabulary
 
       public
 
-      def initialize(*args)
-        super
-        @children = []
-      end
-
-      def children
-        @children.sort
-      end
-
-      def add_child(*input)
-        @children += input
-      end
-
-      HIERARCHY_SEPARATOR = '::'.freeze
-      def slugs
-        term_label.split(HIERARCHY_SEPARATOR)
-      end
-
-      def parent_slugs
-        slugs[0..-2]
-      end
-
-      def parent_term_label
-        parent_slugs.join(HIERARCHY_SEPARATOR)
-      end
-
-      def root_slug
-        slugs[0]
-      end
-
-      def selectable?
-        children.count == 0
-      end
-
+      NON_DEPARTMENTAL_SLUG = "Non-Departmental".freeze
+      # NOTE: The whitespace characters are "thin spaces", U+200A
+      HUMAN_FRIENDLY_HIERARCHY_DELIMITER = ' — '.freeze
       def selectable_label
-        slugs[1..-1].join(HIERARCHY_SEPARATOR)
+        if slugs[-1] == NON_DEPARTMENTAL_SLUG
+          slugs[-2..-1].join(HUMAN_FRIENDLY_HIERARCHY_DELIMITER)
+        else
+          slugs[-1]
+        end
       end
-
-      alias selectable_id id
     end
   end
 end