cuprum-collections 0.4.0 → 0.5.0

data/lib/cuprum/collections/scopes/container.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+
+module Cuprum::Collections::Scopes
+  # Functionality for implementing a scope container.
+  module Container
+    # @param scopes [Array<Scope>] the scopes wrapped by the scope.
+    # @param options [Hash] additional options for the scope.
+    def initialize(scopes:, **options)
+      super(**options)
+
+      @scopes = scopes
+    end
+
+    # @return [Array<Scope>] the scopes wrapped by the scope.
+    attr_reader :scopes
+
+    # @param other [Object] the object to compare.
+    #
+    # @return [Boolean] true if the other object is a scope with matching type
+    #   and child scopes; otherwise false.
+    def ==(other)
+      return false unless super
+
+      other.scopes == scopes
+    end
+
+    # (see Cuprum::Collections::Scopes::Base#as_json)
+    def as_json
+      super.merge({ 'scopes' => scopes.map(&:as_json) })
+    end
+
+    # @private
+    def debug
+      # :nocov:
+      message = "#{super} (#{scopes.count})"
+
+      return message if empty?
+
+      scopes.reduce("#{message}:") do |str, scope|
+        str + "\n- #{scope.debug.gsub("\n", "\n  ")}"
+      end
+      # :nocov:
+    end
+
+    # @return [Boolean] true if the scope has no child scopes; otherwise false.
+    def empty?
+      @scopes.empty?
+    end
+
+    # Creates a copy of the scope with the given child scopes.
+    #
+    # @param scopes [Array] the child scopes.
+    #
+    # @return [Scope] the copied scope.
+    def with_scopes(scopes)
+      dup.tap { |copy| copy.scopes = scopes }
+    end
+
+    protected
+
+    attr_writer :scopes
+  end
+end

data/lib/cuprum/collections/scopes/criteria/parser.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'cuprum/collections/scopes/criteria'
+
+module Cuprum::Collections::Scopes::Criteria
+  # Helper for generating criteria from hash or block inputs.
+  class Parser
+    # Utility class for parsing block operators.
+    class BlockParser
+      # @return [BlockParser] a memoized class instance.
+      def self.instance
+        @instance ||= new
+      end
+
+      def equals(value)
+        OperatorExpression.new(
+          Cuprum::Collections::Queries::Operators::EQUAL,
+          value
+        )
+      end
+      alias equal equals
+      alias eq equals
+
+      def greater_than(value)
+        OperatorExpression.new(
+          Cuprum::Collections::Queries::Operators::GREATER_THAN,
+          value
+        )
+      end
+      alias gt greater_than
+
+      def greater_than_or_equal_to(value)
+        OperatorExpression.new(
+          Cuprum::Collections::Queries::Operators::GREATER_THAN_OR_EQUAL_TO,
+          value
+        )
+      end
+      alias gte greater_than_or_equal_to
+
+      def less_than(value)
+        OperatorExpression.new(
+          Cuprum::Collections::Queries::Operators::LESS_THAN,
+          value
+        )
+      end
+      alias lt less_than
+
+      def less_than_or_equal_to(value)
+        OperatorExpression.new(
+          Cuprum::Collections::Queries::Operators::LESS_THAN_OR_EQUAL_TO,
+          value
+        )
+      end
+      alias lte less_than_or_equal_to
+
+      def not_equal(value)
+        OperatorExpression.new(
+          Cuprum::Collections::Queries::Operators::NOT_EQUAL,
+          value
+        )
+      end
+      alias ne not_equal
+
+      def not_one_of(*values)
+        OperatorExpression.new(
+          Cuprum::Collections::Queries::Operators::NOT_ONE_OF,
+          values.flatten
+        )
+      end
+
+      def one_of(*values)
+        OperatorExpression.new(
+          Cuprum::Collections::Queries::Operators::ONE_OF,
+          values.flatten
+        )
+      end
+    end
+
+    # @deprecated v0.5.0 Implicit receivers are deprecated. Remove this class
+    #   when removing the functionality.
+    class ImplicitReceiver
+      ERROR_MESSAGE =
+        'Pass a block with one parameter to #parse: { |scope| { ' \
+        'scope.%s: value } }'
+      private_constant :ERROR_MESSAGE
+
+      OPERATORS = %i[
+        eq
+        equal
+        equals
+        greater_than
+        greater_than_or_equal_to
+        gt
+        gte
+        less_than
+        less_than_or_equal_to
+        lt
+        lte
+        ne
+        not_equal
+        not_one_of
+        one_of
+      ].freeze
+      private_constant :OPERATORS
+
+      OPERATORS.each do |operator|
+        define_method(operator) do |*args, **kwargs, &block|
+          tools.core_tools.deprecate(
+            '#parse with implicit receiver',
+            message: format(ERROR_MESSAGE, operator)
+          )
+
+          BlockParser.instance.send(operator, *args, **kwargs, &block)
+        end
+      end
+
+      private
+
+      def tools
+        SleepingKingStudios::Tools::Toolbelt.instance
+      end
+    end
+
+    OperatorExpression = Struct.new(:operator, :value)
+    private_constant :OperatorExpression
+
+    UNKNOWN = Object.new.freeze
+    private_constant :UNKNOWN
+
+    class << self
+      # @return [Cuprum::Collections::Scopes::Criteria::Parser] a singleton
+      #   instance of the parser class.
+      def instance
+        @instance ||= new
+      end
+
+      # @private
+      def validate_hash(value)
+        return if valid_hash?(value)
+
+        message = 'value must be a Hash with String or Symbol keys'
+
+        raise ArgumentError, message, caller(1..-1)
+      end
+
+      private
+
+      def valid_hash?(value)
+        return false unless value.is_a?(Hash)
+
+        value.each_key.all? do |key|
+          key.is_a?(String) || key.is_a?(Symbol)
+        end
+      end
+    end
+
+    # @overload parse(value = nil, &block)
+    #   Converts a valid query hash and/or block to criteria.
+    #
+    #   The block must return a Hash with String keys. The hash values must
+    #   either be literal values (e.g. a String, an Integer, etc) or a call to
+    #   an operator function.
+    #
+    #   @param value [Hash, nil] the keys and values to parse.
+    #
+    #   @return [Array] the generated criteria.
+    #
+    #   @yield the query block.
+    #
+    #   @yieldreturn [Hash] a Hash with String keys.
+    def parse(value = UNKNOWN, &)
+      if block_given? && value != UNKNOWN
+        parse_hash(value) + parse_block(&)
+      elsif value == UNKNOWN
+        parse_block(&)
+      else
+        parse_hash(value)
+      end
+    end
+
+    # Converts a valid query block to criteria.
+    #
+    # The block must return a Hash with String keys. The hash values must
+    # either be literal values (e.g. a String, an Integer, etc) or a call to
+    # an operator function.
+    #
+    # @return [Array] the generated criteria.
+    #
+    # @yield the query block.
+    #
+    # @yieldreturn [Hash] a Hash with String keys.
+    def parse_block(...) # rubocop:disable Metrics/MethodLength
+      raise ArgumentError, 'no block given' unless block_given?
+
+      value = evaluate_block(...)
+
+      Parser.validate_hash(value)
+
+      value.map do |attribute, filter|
+        if filter.is_a?(OperatorExpression)
+          [attribute.to_s, filter.operator, filter.value]
+        else
+          operator = Cuprum::Collections::Queries::Operators::EQUAL
+
+          [attribute.to_s, operator, filter]
+        end
+      end
+    rescue NameError => exception
+      raise Cuprum::Collections::Queries::UnknownOperatorException,
+        %(unknown operator "#{exception.name}")
+    end
+
+    # Converts a hash of expected keys and values to criteria.
+    #
+    # @param value [Hash] the keys and values to parse.
+    #
+    # @return [Array] the generated criteria.
+    def parse_hash(value)
+      Parser.validate_hash(value)
+
+      operator = Cuprum::Collections::Queries::Operators::EQUAL
+
+      value.map do |attribute, filter|
+        [attribute.to_s, operator, filter]
+      end
+    end
+
+    private
+
+    # @deprecated v0.5.0 Implicit receivers are deprecated.
+    def evaluate_block(&block)
+      receiver = ImplicitReceiver.new
+
+      return receiver.instance_exec(&block) if block.arity.zero?
+
+      receiver.instance_exec(BlockParser.instance, &block)
+    end
+  end
+end

data/lib/cuprum/collections/scopes/criteria.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/queries'
+require 'cuprum/collections/scopes'
+
+module Cuprum::Collections::Scopes
+  # Functionality for implementing a criteria scope.
+  module Criteria # rubocop:disable Metrics/ModuleLength
+    # Class methods to extend when including the module.
+    module ClassMethods
+      # @overload build(value = nil, &block)
+      #   Initializes a new criteria scope with the parsed criteria.
+      #
+      #   @param value [Hash, nil] the keys and values to parse.
+      #
+      #   @return [Criteria] the scope with the generated criteria.
+      #
+      #   @yield the query block.
+      #
+      #   @yieldreturn [Hash] a Hash with String keys.
+      def build(...)
+        criteria = parse(...)
+
+        new(criteria:)
+      end
+
+      # @overload parse(value = nil, &block)
+      #   (see Cuprum::Collections::Scopes::Criteria::Parser#parse)
+      def parse(*args, &)
+        parser = Cuprum::Collections::Scopes::Criteria::Parser.instance
+
+        args.empty? ? parser.parse(&) : parser.parse(args.first, &)
+      end
+    end
+
+    class << self
+      private
+
+      def included(other)
+        super
+
+        other.extend(ClassMethods)
+      end
+    end
+
+    # @param criteria [Array] the criteria used for filtering query data.
+    # @param inverted [Boolean] if true, the criteria are inverted and should
+    #   match on any criterion (per DeMorgan's Laws).
+    # @param options [Hash] additional options for the scope.
+    def initialize(criteria:, inverted: false, **options)
+      super(**options)
+
+      @criteria = criteria
+      @inverted = inverted
+    end
+
+    # @return [Array] the criteria used for filtering query data.
+    attr_reader :criteria
+
+    # @param other [Object] the object to compare.
+    #
+    # @return [Boolean] true if the other object is a scope with matching type
+    #   and criteria; otherwise false.
+    def ==(other)
+      return false unless super
+
+      other.criteria == criteria && other.inverted? == inverted?
+    end
+
+    # (see Cuprum::Collections::Scopes::Composition#and)
+    def and(*args, &)
+      return super if scope?(args.first)
+
+      return self.class.build(*args, &) if empty?
+
+      return super if inverted?
+
+      with_criteria([*criteria, *self.class.parse(*args, &)])
+    end
+    alias where and
+
+    # (see Cuprum::Collections::Scopes::Base#as_json)
+    def as_json
+      super.merge({ 'criteria' => criteria, 'inverted' => inverted? })
+    end
+
+    # @private
+    def debug
+      # :nocov:
+      message = "#{super} (#{criteria.count})"
+      message += ' (inverted)' if inverted?
+
+      return message if empty?
+
+      criteria.reduce("#{message}:") do |str, (attribute, operator, value)|
+        str + "\n- #{attribute.inspect} #{operator} #{value.inspect}"
+      end
+      # :nocov:
+    end
+
+    # @return [Boolean] true if the scope has no criteria; otherwise false.
+    def empty?
+      @criteria.empty?
+    end
+
+    # @return [Cuprum::Collections::Criteria] a copy of the scope with the
+    #   #inverted? predicate flipped and the individual criteria negated.
+    def invert
+      with_criteria(invert_criteria).tap { |copy| copy.inverted = !inverted? }
+    end
+
+    # @return [Boolean] true if the scope is inverted; otherwise false.
+    def inverted?
+      @inverted
+    end
+
+    # (see Cuprum::Collections::Scopes::Composition#or)
+    def or(*args, &)
+      return super if scope?(args.first)
+
+      return self.class.build(*args, &) if empty?
+
+      builder.build_disjunction_scope(
+        safe:   false,
+        scopes: [self, self.class.build(*args, &)]
+      )
+    end
+
+    # (see Cuprum::Collections::Scopes::Base#type)
+    def type
+      :criteria
+    end
+
+    # Creates a copy of the scope with the given criteria.
+    #
+    # @param criteria [Array] the criteria used for filtering query data.
+    #
+    # @return [Scope] the copied scope.
+    def with_criteria(criteria)
+      dup.tap { |copy| copy.criteria = criteria }
+    end
+
+    protected
+
+    attr_writer :criteria
+
+    attr_writer :inverted
+
+    private
+
+    def and_all_scope(scope)
+      return builder.transform_scope(scope:) if empty?
+
+      super
+    end
+
+    def and_conjunction_scope(scope)
+      return builder.transform_scope(scope:) if empty?
+
+      super
+    end
+
+    def and_criteria_scope(scope)
+      return builder.transform_scope(scope:) if empty?
+
+      unless inverted? || scope.inverted?
+        return with_criteria([*criteria, *scope.criteria])
+      end
+
+      super
+    end
+
+    def and_generic_scope(scope)
+      return builder.transform_scope(scope:) if empty?
+
+      super
+    end
+
+    def invert_criteria
+      criteria.map do |(attribute, operator, value)|
+        [attribute, invert_operator(operator), value]
+      end
+    end
+
+    def invert_operator(operator)
+      Cuprum::Collections::Queries::INVERTIBLE_OPERATORS.fetch(operator) do
+        raise Cuprum::Collections::Queries::UninvertibleOperatorException,
+          "uninvertible operator #{operator.inspect}"
+      end
+    end
+
+    def or_disjunction_scope(scope)
+      return builder.transform_scope(scope:) if empty?
+
+      super
+    end
+
+    def or_generic_scope(scope)
+      return builder.transform_scope(scope:) if empty?
+
+      super
+    end
+  end
+end
+
+require 'cuprum/collections/scopes/criteria/parser'

data/lib/cuprum/collections/scopes/criteria_scope.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+require 'cuprum/collections/scopes/base'
+require 'cuprum/collections/scopes/criteria'
+
+module Cuprum::Collections::Scopes
+  # Generic scope class for defining criteria scopes.
+  class CriteriaScope < Cuprum::Collections::Scopes::Base
+    include Cuprum::Collections::Scopes::Criteria
+  end
+end

data/lib/cuprum/collections/scopes/disjunction.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+require 'cuprum/collections/scopes/container'
+
+module Cuprum::Collections::Scopes
+  # Functionality for implementing a logical OR scope.
+  module Disjunction
+    include Cuprum::Collections::Scopes::Container
+
+    # @return [Cuprum::Collections::Disjunction] a logical AND scope with the
+    #   constituent scopes inverted.
+    def invert
+      builder.build_conjunction_scope(scopes: scopes.map(&:invert))
+    end
+
+    # (see Cuprum::Collections::Scopes::Composition#or)
+    def or(*args, &)
+      return super if scope?(args.first)
+
+      scope = builder.build(*args, &)
+
+      with_scopes([*scopes, scope])
+    end
+
+    # (see Cuprum::Collections::Scopes::Base#type)
+    def type
+      :disjunction
+    end
+
+    private
+
+    def or_disjunction_scope(scope)
+      scopes = scope.scopes.map do |inner|
+        builder.transform_scope(scope: inner)
+      end
+
+      with_scopes([*self.scopes, *scopes])
+    end
+
+    def or_generic_scope(scope)
+      with_scopes([*scopes, builder.transform_scope(scope:)])
+    end
+  end
+end

data/lib/cuprum/collections/scopes/disjunction_scope.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+require 'cuprum/collections/scopes/base'
+require 'cuprum/collections/scopes/disjunction'
+
+module Cuprum::Collections::Scopes
+  # Generic scope class for defining collection-independent logical OR scopes.
+  class DisjunctionScope < Cuprum::Collections::Scopes::Base
+    include Cuprum::Collections::Scopes::Disjunction
+  end
+end

data/lib/cuprum/collections/scopes/none.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+
+module Cuprum::Collections::Scopes
+  # Functionality for implementing a none scope, which returns no data.
+  module None
+    # @overload and(hash = nil, &block)
+    #   Returns the none scope.
+    #
+    # @overload and(scope)
+    #   Returns the none scope.
+    def and(*, &)
+      self
+    end
+    alias where and
+
+    # @return [Boolean] false.
+    def empty?
+      false
+    end
+
+    # @return [Cuprum::Collections::Scopes::All] an all scope for the current
+    #   collection.
+    def invert
+      builder.build_all_scope
+    end
+
+    # @overload or(hash = nil, &block)
+    #   Returns the none scope.
+    #
+    # @overload or(scope)
+    #   Returns the none scope.
+    def or(*args, &)
+      return super if scope?(args.first)
+
+      builder.build(*args, &)
+    end
+
+    # @overload not(hash = nil, &block)
+    #   Returns the none scope.
+    #
+    # @overload not(scope)
+    #   Returns the none scope.
+    def not(*, &)
+      self
+    end
+
+    # (see Cuprum::Collections::Scopes::Base#type)
+    def type
+      :none
+    end
+
+    private
+
+    def or_scope(scope)
+      return self if scope.empty?
+
+      builder.transform_scope(scope:)
+    end
+  end
+end

data/lib/cuprum/collections/scopes/none_scope.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections/scopes'
+require 'cuprum/collections/scopes/base'
+require 'cuprum/collections/scopes/none'
+
+module Cuprum::Collections::Scopes
+  # Generic scope class for defining collection-independent none scopes.
+  class NoneScope < Cuprum::Collections::Scopes::Base
+    include Cuprum::Collections::Scopes::None
+
+    # @return [Cuprum::Collections::Scopes::NoneScope] a cached instance of the
+    #   none scope.
+    def self.instance
+      @instance ||= new
+    end
+  end
+end

data/lib/cuprum/collections/scopes.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'cuprum/collections'
+
+module Cuprum::Collections
+  # Namespace for scope functionality, which filters query data.
+  module Scopes
+    autoload :All,              'cuprum/collections/scopes/all'
+    autoload :AllScope,         'cuprum/collections/scopes/all_scope'
+    autoload :Base,             'cuprum/collections/scopes/base'
+    autoload :Builder,          'cuprum/collections/scopes/builder'
+    autoload :Collection,       'cuprum/collections/scopes/collection'
+    autoload :Composition,      'cuprum/collections/scopes/composition'
+    autoload :Conjunction,      'cuprum/collections/scopes/conjunction'
+    autoload :ConjunctionScope, 'cuprum/collections/scopes/conjunction_scope'
+    autoload :Criteria,         'cuprum/collections/scopes/criteria'
+    autoload :CriteriaScope,    'cuprum/collections/scopes/criteria_scope'
+    autoload :Disjunction,      'cuprum/collections/scopes/disjunction'
+    autoload :DisjunctionScope, 'cuprum/collections/scopes/disjunction_scope'
+    autoload :None,             'cuprum/collections/scopes/none'
+    autoload :NoneScope,        'cuprum/collections/scopes/none_scope'
+  end
+end

data/lib/cuprum/collections/version.rb

@@ -11,7 +11,7 @@ module Cuprum
       # Major version.
       MAJOR = 0
       # Minor version.
-      MINOR = 4
+      MINOR = 5
       # Patch version.
       PATCH = 0
       # Prerelease version.
@@ -28,7 +28,7 @@ module Cuprum
         #
         # @see SleepingKingStudios::Tools::SemanticVersion#to_gem_version
         def to_gem_version
-          str = +"#{MAJOR}.#{MINOR}.#{PATCH}"
+          str = "#{MAJOR}.#{MINOR}.#{PATCH}"
 
           prerelease = value_of(:PRERELEASE)
           str << ".#{prerelease}" if prerelease