rom-support 0.1.0

data/lib/rom/support/deprecations.rb

@@ -0,0 +1,36 @@
+module ROM
+  module Deprecations
+    # @api private
+    def deprecate(old_name, new_name, msg = nil)
+      class_eval do
+        define_method(old_name) do |*args, &block|
+          ROM::Deprecations.announce "#{self.class}##{old_name} is", <<-MSG
+            Please use #{self.class}##{new_name} instead.
+            #{msg}
+          MSG
+          __send__(new_name, *args, &block)
+        end
+      end
+    end
+
+    def deprecate_class_method(old_name, new_name, msg = nil)
+      class_eval do
+        define_singleton_method(old_name) do |*args, &block|
+          ROM::Deprecations.announce"#{self}.#{old_name} is", <<-MSG
+            Please use #{self}.#{new_name} instead.
+            #{msg}
+          MSG
+          __send__(new_name, *args, &block)
+        end
+      end
+    end
+
+    def self.announce(name, msg)
+      warn <<-MSG.gsub(/^\s+/, '')
+        #{name} deprecated and will be removed in 1.0.0.
+        #{msg}
+        #{caller.detect { |l| !l.include?('lib/rom')}}
+      MSG
+    end
+  end
+end

data/lib/rom/support/enumerable_dataset.rb

@@ -0,0 +1,65 @@
+require 'rom/support/data_proxy'
+
+module ROM
+  # A helper module that adds data-proxy behavior to an enumerable object
+  #
+  # This module is intended to be used by gateways
+  #
+  # Class that includes this module can define `row_proc` class method which
+  # must return a proc-like object which will be used to process each element
+  # in the enumerable
+  #
+  # @example
+  #   class MyDataset
+  #     include ROM::EnumerableDataset
+  #
+  #     def self.row_proc
+  #       -> tuple { tuple.each_with_object({}) { |(k,v), h| h[k.to_sym] = v } }
+  #     end
+  #   end
+  #
+  #   ds = MyDataset.new([{ 'name' => 'Jane' }, [:name])
+  #   ds.to_a # => { :name => 'Jane' }
+  #
+  # @api public
+  module EnumerableDataset
+    extend DataProxy::ClassMethods
+    include Enumerable
+
+    # Coerce a dataset to an array
+    #
+    # @return [Array]
+    #
+    # @api public
+    alias_method :to_ary, :to_a
+
+    # Included hook which extends a class with DataProxy behavior
+    #
+    # This module can also be included into other modules so we apply the
+    # extension only for classes
+    #
+    # @api private
+    def self.included(klass)
+      return unless klass.is_a?(Class)
+
+      klass.class_eval do
+        include Options
+        include DataProxy
+      end
+    end
+
+    forward :take
+
+    [
+      :chunk, :collect, :collect_concat, :drop_while, :find_all, :flat_map,
+      :grep, :map, :reject, :select, :sort, :sort_by, :take_while
+    ].each do |method|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method}(*args, &block)
+          return to_enum unless block
+          self.class.new(super(*args, &block), options)
+        end
+      RUBY
+    end
+  end
+end

data/lib/rom/support/guarded_inheritance_hook.rb

@@ -0,0 +1,21 @@
+require 'rom/support/publisher'
+
+module ROM
+  module Support
+    module GuardedInheritanceHook
+      def self.extended(base)
+        base.class_eval <<-RUBY
+          class << self
+            include ROM::Support::Publisher
+
+            def inherited(klass)
+              super
+              return if klass.superclass == #{base}
+              #{base}.__send__(:broadcast, :inherited, klass)
+            end
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/rom/support/inflector.rb

@@ -0,0 +1,73 @@
+module ROM
+  # Helper module providing thin interface around an inflection backend.
+  #
+  # @private
+  module Inflector
+    BACKENDS = {
+      activesupport: [
+        'active_support/inflector',
+        proc { ::ActiveSupport::Inflector }
+      ],
+      inflecto: [
+        'inflecto',
+        proc { ::Inflecto }
+      ]
+    }.freeze
+
+    def self.realize_backend(path, inflector_backend_factory)
+      require path
+      inflector_backend_factory.call
+    rescue LoadError
+      nil
+    end
+
+    def self.detect_backend
+      BACKENDS.find do |_, (path, inflector_class)|
+        backend = realize_backend(path, inflector_class)
+        break backend if backend
+      end ||
+        raise(LoadError,
+              "No inflector library could be found: "\
+              "please install either the `inflecto` or `activesupport` gem.")
+    end
+
+    def self.select_backend(name = nil)
+      if name && !BACKENDS.key?(name)
+        raise NameError, "Invalid inflector library selection: '#{name}'"
+      end
+      @inflector = name ? realize_backend(*BACKENDS[name]) : detect_backend
+    end
+
+    def self.inflector
+      defined?(@inflector) && @inflector || select_backend
+    end
+
+    def self.camelize(input)
+      inflector.camelize(input)
+    end
+
+    def self.underscore(input)
+      inflector.underscore(input)
+    end
+
+    def self.singularize(input)
+      inflector.singularize(input)
+    end
+
+    def self.pluralize(input)
+      inflector.pluralize(input)
+    end
+
+    def self.demodulize(input)
+      inflector.demodulize(input)
+    end
+
+    def self.constantize(input)
+      inflector.constantize(input)
+    end
+
+    def self.classify(input)
+      inflector.classify(input)
+    end
+  end
+end

data/lib/rom/support/inheritance_hook.rb

@@ -0,0 +1,20 @@
+require 'rom/support/publisher'
+
+module ROM
+  module Support
+    module InheritanceHook
+      def self.extended(base)
+        base.class_eval <<-RUBY
+          class << self
+            include ROM::Support::Publisher
+
+            def inherited(klass)
+              super
+              #{base}.__send__(:broadcast, :inherited, klass)
+            end
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/rom/support/options.rb

@@ -0,0 +1,198 @@
+module ROM
+  # Helper module for classes with a constructor accepting option hash
+  #
+  # This allows us to DRY up code as option hash is a very common pattern used
+  # across the codebase. It is an internal implementation detail not meant to
+  # be used outside of ROM
+  #
+  # @example
+  #   class User
+  #     include Options
+  #
+  #     option :name, type: String, reader: true
+  #     option :admin, allow: [true, false], reader: true, default: false
+  #
+  #     def initialize(options={})
+  #       super
+  #     end
+  #   end
+  #
+  #   user = User.new(name: 'Piotr')
+  #   user.name # => "Piotr"
+  #   user.admin # => false
+  #
+  # @api public
+  module Options
+    InvalidOptionValueError = Class.new(StandardError)
+    InvalidOptionKeyError = Class.new(StandardError)
+
+    # @return [Hash<Option>] Option definitions
+    #
+    # @api public
+    attr_reader :options
+
+    def self.included(klass)
+      klass.extend ClassMethods
+      klass.option_definitions = Definitions.new
+    end
+
+    # Defines a single option
+    #
+    # @api private
+    class Option
+      attr_reader :name, :type, :allow, :default
+
+      def initialize(name, options = {})
+        @name = name
+        @type = options.fetch(:type) { Object }
+        @reader = options.fetch(:reader) { false }
+        @allow = options.fetch(:allow) { [] }
+        @default = options.fetch(:default) { Undefined }
+        @ivar = :"@#{name}" if @reader
+      end
+
+      def reader?
+        @reader
+      end
+
+      def assign_reader_value(object, value)
+        object.instance_variable_set(@ivar, value)
+      end
+
+      def default?
+        @default != Undefined
+      end
+
+      def default_value(object)
+        default.is_a?(Proc) ? default.call(object) : default
+      end
+
+      def type_matches?(value)
+        value.is_a?(type)
+      end
+
+      def allow?(value)
+        allow.empty? || allow.include?(value)
+      end
+    end
+
+    # Manage all available options
+    #
+    # @api private
+    class Definitions
+      def initialize
+        @options = {}
+      end
+
+      def initialize_copy(source)
+        super
+        @options = @options.dup
+      end
+
+      def define(option)
+        @options[option.name] = option
+      end
+
+      def process(object, options)
+        ensure_known_options(options)
+
+        each do |name, option|
+          if option.default? && !options.key?(name)
+            options[name] = option.default_value(object)
+          end
+
+          if options.key?(name)
+            validate_option_value(option, name, options[name])
+          end
+
+          option.assign_reader_value(object, options[name]) if option.reader?
+        end
+      end
+
+      def names
+        @options.keys
+      end
+
+      private
+
+      def each(&block)
+        @options.each(&block)
+      end
+
+      def ensure_known_options(options)
+        options.each_key do |name|
+          @options.fetch(name) do
+            raise InvalidOptionKeyError,
+              "#{name.inspect} is not a valid option"
+          end
+        end
+      end
+
+      def validate_option_value(option, name, value)
+        unless option.type_matches?(value)
+          raise InvalidOptionValueError,
+            "#{name.inspect}:#{value.inspect} has incorrect type"
+        end
+
+        unless option.allow?(value)
+          raise InvalidOptionValueError,
+            "#{name.inspect}:#{value.inspect} has incorrect value"
+        end
+      end
+    end
+
+    # @api private
+    module ClassMethods
+      # Available options
+      #
+      # @return [Definitions]
+      #
+      # @api private
+      attr_accessor :option_definitions
+
+      # Defines an option
+      #
+      # @param [Symbol] name option name
+      #
+      # @param [Hash] settings option settings
+      # @option settings [Class] :type Restrict option type. Default: +Object+
+      # @option settings [Boolean] :reader Define a reader? Default: +false+
+      # @option settings [Array] :allow Allow certain values. Default: Allow anything
+      # @option settings [Object] :default Set default value for missing option
+      #
+      # @api public
+      def option(name, settings = {})
+        option = Option.new(name, settings)
+        option_definitions.define(option)
+        attr_reader(name) if option.reader?
+      end
+
+      # @api private
+      def inherited(descendant)
+        descendant.option_definitions = option_definitions.dup
+        super
+      end
+    end
+
+    # Initialize options provided as optional last argument hash
+    #
+    # @example
+    #   class Commands
+    #     include Options
+    #
+    #     # ...
+    #
+    #     def initialize(relations, options={})
+    #       @relation = relation
+    #       super
+    #     end
+    #   end
+    #
+    # @param [Array] args
+    def initialize(*args)
+      options = args.last ? args.last.dup : {}
+      self.class.option_definitions.process(self, options)
+      @options = options.freeze
+    end
+  end
+end

data/lib/rom/support/publisher.rb

@@ -0,0 +1,11 @@
+require 'wisper'
+
+module ROM
+  module Support
+    module Publisher
+      def self.included(klass)
+        klass.__send__(:include, Wisper::Publisher)
+      end
+    end
+  end
+end

data/lib/rom/support/registry.rb

@@ -0,0 +1,43 @@
+module ROM
+  # @api private
+  class Registry
+    include Enumerable
+    include Equalizer.new(:elements)
+
+    class ElementNotFoundError < KeyError
+      def initialize(key, name)
+        super("#{key.inspect} doesn't exist in #{name} registry")
+      end
+    end
+
+    attr_reader :elements, :name
+
+    def initialize(elements = {}, name = self.class.name)
+      @elements = elements
+      @name = name
+    end
+
+    def each(&block)
+      return to_enum unless block
+      elements.each { |element| yield(element) }
+    end
+
+    def key?(name)
+      elements.key?(name)
+    end
+
+    def [](key)
+      elements.fetch(key) { raise ElementNotFoundError.new(key, name) }
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      elements.key?(name) || super
+    end
+
+    private
+
+    def method_missing(name, *)
+      elements.fetch(name) { super }
+    end
+  end
+end