rom 0.5.0 → 0.6.0.beta1

data/lib/rom/support/array_dataset.rb

@@ -0,0 +1,38 @@
+require 'rom/support/enumerable_dataset'
+
+module ROM
+  # A helper module that adds data-proxy behavior to an array-like object
+  #
+  # @see EnumerableDataset
+  #
+  # @api public
+  module ArrayDataset
+    extend DataProxy::ClassMethods
+    include EnumerableDataset
+
+    # Extends the class with data-proxy behavior
+    #
+    # @api private
+    def self.included(klass)
+      klass.send(:include, DataProxy)
+    end
+
+    forward(
+      :*, :+, :-, :compact, :compact!, :flatten, :flatten!, :length, :pop,
+      :reverse, :reverse!, :sample, :select!, :size, :shift, :shuffle, :shuffle!,
+      :slice, :slice!, :sort!, :sort_by!, :uniq, :uniq!, :unshift, :values_at
+    )
+
+    [
+      :map!, :combination, :cycle, :delete_if, :keep_if, :permutation, :reject!,
+      :select!, :sort_by!
+    ].each do |method|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method}(*args, &block)
+          return to_enum unless block
+          self.class.new(data.send(:#{method}, *args, &block))
+        end
+      RUBY
+    end
+  end
+end

data/lib/rom/support/class_builder.rb

@@ -0,0 +1,44 @@
+module ROM
+  # Internal support class for generating classes
+  #
+  # @private
+  class ClassBuilder
+    include Options
+
+    option :name, type: String, reader: true
+    option :parent, type: Class, reader: true, parent: Object
+
+    # Generate a class based on options
+    #
+    # @example
+    #   builder = ROM::ClasBuilder.new(name: 'MyClass')
+    #
+    #   klass = builder.call
+    #   klass.name # => "MyClass"
+    #
+    # @return [Class]
+    #
+    # @api private
+    def call
+      klass = Class.new(parent)
+
+      klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.name
+          #{name.inspect}
+        end
+
+        def self.inspect
+          name
+        end
+
+        def self.to_s
+          name
+        end
+      RUBY
+
+      yield(klass) if block_given?
+
+      klass
+    end
+  end
+end

data/lib/rom/support/class_macros.rb

@@ -0,0 +1,56 @@
+module ROM
+  # Internal support module for class-level settings
+  #
+  # @private
+  module ClassMacros
+    # Specify what macros a class will use
+    #
+    # @example
+    #   class MyClass
+    #     extend ROM::ClassMacros
+    #
+    #     defines :one, :two
+    #
+    #     one 1
+    #     two 2
+    #   end
+    #
+    #   class OtherClass < MyClass
+    #     two 'two'
+    #   end
+    #
+    #   MyClass.one # => 1
+    #   MyClass.two # => 2
+    #
+    #   OtherClass.one # => 1
+    #   OtherClass.two # => 'two'
+    #
+    # @api private
+    def defines(*args)
+      mod = Module.new
+
+      args.each do |name|
+        mod.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{name}(value = Undefined)
+            if value == Undefined
+              defined?(@#{name}) && @#{name}
+            else
+              @#{name} = value
+            end
+          end
+        RUBY
+      end
+
+      delegates = args.map { |name| "klass.#{name}(#{name})" }.join("\n")
+
+      mod.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def inherited(klass)
+          super
+          #{delegates}
+        end
+      RUBY
+
+      extend(mod)
+    end
+  end
+end

data/lib/rom/support/data_proxy.rb

@@ -0,0 +1,102 @@
+require 'equalizer'
+
+module ROM
+  # Helper module for dataset classes
+  #
+  # It provides a constructor accepting data, header and an optional row_proc.
+  # This module is used internally by EnumerableDataset and ArrayDataset.
+  #
+  # @private
+  module DataProxy
+    NON_FORWARDABLE = [
+      :each, :to_a, :to_ary, :kind_of?, :instance_of?, :is_a?
+    ].freeze
+
+    # @return [Object] Data object for the iterator
+    #
+    # @api private
+    attr_reader :data
+
+    # @return [Proc] tuple processing proc
+    #
+    # @api private
+    attr_reader :row_proc
+
+    # Extends the class with `forward` DSL and Equalizer using `data` attribute
+    #
+    # @see ClassMethods#forward
+    #
+    # @api private
+    def self.included(klass)
+      klass.class_eval do
+        extend ClassMethods
+        include Equalizer.new(:data)
+      end
+    end
+
+    # Constructor for dataset objects
+    #
+    # @param [Object] data
+    # @param [Proc] row_proc processing proc
+    #
+    # @api private
+    def initialize(data, row_proc = self.class.row_proc)
+      @data = data
+      @row_proc = row_proc
+    end
+
+    # Iterate over data using row_proc
+    #
+    # @return [Enumerator] if block is not given
+    #
+    # @api private
+    def each
+      return to_enum unless block_given?
+      data.each { |tuple| yield(row_proc[tuple]) }
+    end
+
+    module ClassMethods
+      # Default no-op tuple proc
+      #
+      # @return [Proc]
+      #
+      # @api private
+      def row_proc
+        -> tuple { tuple }
+      end
+
+      # Forward provided methods to the underlaying data object
+      #
+      # @example
+      #
+      #   class MyDataset
+      #     include DataProxy
+      #
+      #     forward(:find_all, :map)
+      #   end
+      #
+      # @return [undefined]
+      #
+      # @api public
+      def forward(*methods)
+        # FIXME: we should probably raise if one of the non-forwardable methods
+        #       was provided
+        (methods - NON_FORWARDABLE).each do |method_name|
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{method_name}(*args, &block)
+              response = data.public_send(#{method_name.inspect}, *args, &block)
+
+              if response.equal?(data)
+                self
+              elsif response.is_a?(data.class)
+                self.class.new(response)
+              else
+                response
+              end
+            end
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/rom/support/enumerable_dataset.rb

@@ -0,0 +1,58 @@
+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 repositories
+  #
+  # 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
+    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.send(:include, DataProxy)
+    end
+
+    [
+      :chunk, :collect, :collect_concat, :drop_while, :find_all, :flat_map,
+      :grep, :map, :reject, :select, :sort, :sort_by, :take, :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))
+        end
+      RUBY
+    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
+      @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/options.rb

@@ -0,0 +1,188 @@
+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
+    # @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 }
+      end
+
+      def reader?
+        @reader
+      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.none? || 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 validate_options(options)
+        options.each do |name, value|
+          validate_option_value(name, value)
+        end
+      end
+
+      def set_defaults(object, options)
+        each do |name, option|
+          next unless option.default? && !options.key?(name)
+          options[name] = option.default_value(object)
+        end
+      end
+
+      def set_option_values(object, options)
+        each do |name, option|
+          object.instance_variable_set("@#{name}", options[name]) if option.reader?
+        end
+      end
+
+      private
+
+      def each(&block)
+        @options.each(&block)
+      end
+
+      def validate_option_value(name, value)
+        option = @options.fetch(name) do
+          raise InvalidOptionKeyError,
+            "#{name.inspect} is not a valid option"
+        end
+
+        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 : {}
+      definitions = self.class.option_definitions
+      definitions.set_defaults(self, options)
+      definitions.validate_options(options)
+      definitions.set_option_values(self, options)
+      @options = options.freeze
+    end
+  end
+end