chain_options 0.1.0

data/lib/chain_options/builder.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ChainOptions
+  #
+  # A simple helper class to set multiple chain options after another
+  # by using a `set NAME, VALUE` syntax instead of having to
+  # use constructs like
+  #   instance = instance.NAME(VALUE)
+  #   instance = instance.NAME2(VALUE2) if XY
+  #   ...
+  #
+  class Builder
+    def initialize(initial_instance, &block)
+      @instance = initial_instance
+      ChainOptions::Util.instance_eval_or_call(self, &block)
+      result
+    end
+
+    def result
+      @instance
+    end
+
+    def set(option_name, *value, &block)
+      @instance = @instance.send(option_name, *value, &block)
+    end
+  end
+end

data/lib/chain_options/integration.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module ChainOptions
+  module Integration
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      #
+      # Generates a combined getter and setter method for the
+      # option with the given name.
+      #
+      # @param [String, Symbol] name
+      #
+      # @param [Hash] options
+      # @option options [Object, Proc] :default (nil)
+      #   Sets the value which should be used whenever no custom value was set for this option
+      #
+      # @option options [Symbol] :invalid (:raise)
+      #   Sets the behaviour when an invalid value is given.
+      #   If set to `:raise`, an ArgumentError is raised if an option validation fails,
+      #   if set to `:default`, the default value is used instead of the invalid value
+      #
+      # @option options [Proc] :validate (nil)
+      #   Sets up a validation proc for the option value.
+      #   See :invalid for information about what happens when a validation fails
+      #
+      # @option options [Proc, Symbol] :filter (nil)
+      #   An optional filter method to reject certain values.
+      #   See ChainOptions::OptionSet#filter_value for more information
+      #
+      # @option options [Proc, Symbol] :transform (nil)
+      #   An optional transformation that transforms the given value.
+      #   See ChainOptions::OptionSet#transform_value for more information.
+      #
+      # @option options [Boolean] :incremental (false)
+      #   If set to +true+, overriding an option value will no longer be possible.
+      #   Instead, the whole option value is treated as an Array with each new value simply being
+      #   appended to it.
+      #     user.favourite_books('Momo', 'Neverending Story').favourite_books('Lord of the Rings', 'The Hobbit')
+      #     => [["Momo", "Neverending Story"], ["Lord of the Rings", "The Hobbit"]]
+      #
+      # @option options [Boolean] :allow_block (false)
+      #   Sets whether the option value may be a proc object given through a block.
+      #   If set to +true+, the following statement would result in `block` being saved as option value:
+      #     instance.my_option(&block)
+      #
+      def chain_option(name, **options)
+        available_chain_options[name.to_sym] = options
+
+        ChainOptions::OptionSet.handle_warnings(name, **options)
+
+        define_method(name) do |*args, &block|
+          chain_option_set.handle_option_call(name, *args, &block)
+        end
+      end
+
+      def available_chain_options
+        @available_chain_options ||= {}
+      end
+    end
+
+    def initialize(**options)
+      @chain_option_values = options
+    end
+
+    #
+    # Allows setting multiple options in a block. This makes long option chains easier to read.
+    #
+    # @example The following expressions are equivalent
+    #   instance.option1(value).option2(value).option3 { value3 }
+    #   instance.build_options do
+    #     set :option1, value
+    #     set :option2, value2
+    #     set(:option3) { value3 }
+    #
+    def build_options(&block)
+      ChainOptions::Builder.new(self, &block).result
+    end
+
+    private
+
+    def chain_option_set
+      @chain_option_set ||= OptionSet.new(self, self.class.available_chain_options, chain_option_values)
+    end
+
+    #
+    # @return [Hash] the currently set options for the current instance.
+    #
+    def chain_option_values
+      @chain_option_values ||= {}
+    end
+  end
+end

data/lib/chain_options/option.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module ChainOptions
+  #
+  # This class represents an Option from a ChainOptions::OptionSet and is
+  # mainly responsible for handling option state.
+  #
+  class Option
+    # The Parameters that need to be turned into instance methods, if they are symbols.
+    METHOD_SYMBOLS = %i[filter validate].freeze
+    PARAMETERS     = %i[incremental default transform filter validate invalid allow_block].freeze
+
+    (PARAMETERS - [:allow_block]).each do |param|
+      define_method(param) { options[param] }
+      private param
+    end
+
+    def allow_block
+      options[:allow_block]
+    end
+
+    #
+    # Extracts options and sets all the parameters.
+    #
+    def initialize(options)
+      self.options = options
+      @dirty = false
+    end
+
+    #
+    # Builds a new value for the option.
+    # It automatically applies transformations and filters and validates the
+    # resulting value, raising an exception if the value is not valid.
+    #
+    def new_value(*args, &block)
+      value = value_from_args(args, &block)
+
+      value = if incremental
+                incremental_value(value)
+              else
+                filter_value(transformed_value(value))
+              end
+
+      if value_valid?(value)
+        self.custom_value = value
+      elsif invalid.to_s == 'default' && !incremental
+        default_value
+      else
+        fail ArgumentError, "The value #{value.inspect} is not valid."
+      end
+    end
+
+    #
+    # The current value if there is one. Otherwise returns the default value.
+    #
+    def current_value
+      return custom_value if dirty?
+
+      default_value
+    end
+
+    #
+    # Circumvents the normal value process to set an initial_value. Only works on a
+    #   clean option.
+    #
+    def initial_value(value)
+      raise ArgumentError, "The initial_value was already set to #{custom_value.inspect}." if dirty?
+
+      self.custom_value = value
+    end
+
+    #
+    # Looks through the parameters and returns the non-nil values as a hash
+    #
+    def to_h
+      PARAMETERS.each_with_object({}) do |param, hash|
+        next if send(param).nil?
+
+        hash[param] = send(param)
+      end
+    end
+
+    private
+
+    attr_accessor :options
+
+    # A value that has been set by a user. Overrides default_value.
+    attr_reader :custom_value
+
+    #
+    # Sets the current value and marks the option as dirty.
+    #
+    def custom_value=(value)
+      @dirty = true
+      @custom_value = value
+    end
+
+    #
+    # Returns the block if nothing else if given and blocks are allowed to be
+    #   values.
+    #
+    def value_from_args(args, &block)
+      return block if ChainOptions::Util.blank?(args) && block && allow_block
+
+      flat_value(args)
+    end
+
+    #
+    # Reverses the auto-cast to Array that is applied at `new_value`.
+    #
+    def flat_value(args)
+      return args.first if args.is_a?(Enumerable) && args.count == 1
+
+      args
+    end
+
+    #
+    # Incremental values assume 2d arrays. Here the current_value is only
+    #   prepended if the option is dirty.
+    #
+    def incremental_value(value)
+      dirty? ? [*current_value, Array(value)] : [Array(value)]
+    end
+
+    #
+    # Describes whether the default value has already been replaced.
+    #
+    def dirty?
+      !!@dirty
+    end
+
+    #
+    # Checks whether a new chain option value is valid or not using the `validate` values
+    # used when setting up `chain_option`s.
+    #
+    # Please note that the value passed to this function already went through
+    # the chain option's filters - if any. This means that it will always be a collection
+    # if a filter was defined.
+    #
+    # If no validation was set up, the new value will always be accepted
+    #
+    # @return [Boolean] +true+ if the new value is valid.
+    #
+    def value_valid?(value)
+      return true unless validate
+
+      validate.call(value)
+    end
+
+    #
+    # Applies a transformation to the given value.
+    #
+    # @param [Object] value
+    #   The new value to be transformed
+    #
+    # If a `transform` was set up for the given option, it is used
+    # as `to_proc` target when iterating over the value.
+    # The value is always treated as a collection during this phase.
+    #
+    def transformed_value(value)
+      return value unless transform
+
+      transformed = Array(value).map(&transform)
+      value.is_a?(Enumerable) ? transformed : transformed.first
+    end
+
+    #
+    # Applies a filter to the given value.
+    # Expects the value to be some kind of collection. If it isn't, it is treated
+    # as an array with one element.
+    #
+    # @param [Object] value
+    #   The new value to be filtered
+    #
+    # @example using a filter proc
+    #   filter_value [1, 2, 3, 4, 5] # with filter: ->(entry) { entry.even? }
+    #   #=> [2, 4]
+    #
+    def filter_value(value)
+      return value unless filter
+
+      Array(value).select(&filter)
+    end
+
+    #
+    # @return [Object] the default value which was set for the given option name.
+    #   If a proc is given, the result of `proc.call` will be returned.
+    #
+    def default_value
+      return default unless default.respond_to?(:call)
+
+      default.call
+    end
+  end
+end

data/lib/chain_options/option_set.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module ChainOptions
+  class OptionSet
+
+    class << self
+
+      #
+      # Warns of incompatible options for a chain_option.
+      # This does not necessarily mean that an error will be raised.
+      #
+      def warn_incompatible_options(option_name, *options)
+        STDERR.puts "The options #{options.join(', ')} are incompatible for the chain_option #{option_name}."
+      end
+
+      #
+      # Prints warnings for incompatible options which were used as arguments in `chain_option`
+      #
+      def handle_warnings(name, incremental: false, invalid: :raise, filter: nil, transform: nil, **)
+        if incremental
+          warn_incompatible_options(name, 'invalid: :default', 'incremental: true') if invalid.to_s == 'default'
+          warn_incompatible_options(name, 'incremental: true', 'filter:') if filter
+          warn_incompatible_options(name, 'incremental: true', 'transform:') if transform
+        end
+      end
+    end
+
+    #
+    # @param [Object] instance the object that uses the chain_option set.
+    # @param [Hash] chain_options a hash of `{name: config_hash}` to initialize
+    #   options from a config hash.
+    # @param [Hash] values a hash of `{name: value}` with initial values for the
+    #   named options.
+    #
+    def initialize(instance, chain_options = {}, values = {})
+      @instance      = instance
+      @values        = values
+      @chain_options = chain_options.inject({}) do |options, (name, config)|
+        options.merge(name => config.merge(instance_method_hash(config)))
+      end
+    end
+
+    attr_reader :instance
+
+    #
+    # Checks the given option-parameters for incompatibilities and registers a
+    #   new option.
+    #
+    def add_option(name, parameters)
+      self.class.handle_warnings(name, **parameters.dup)
+      chain_options.merge(name => parameters.merge(method_hash(parameters)))
+    end
+
+    #
+    # Returns the current_value of an option.
+    #
+    def current_value(name)
+      option(name).current_value
+    end
+
+    #
+    # Returns an option registered under `name`.
+    #
+    def option(name)
+      config = chain_options[name] || raise_no_option_error(name)
+      Option.new(config).tap { |o| o.initial_value(values[name]) if values.key?(name) }
+    end
+
+    #
+    # Builds a new value for the given chain option.
+    # It automatically applies transformations and filters and validates the
+    # resulting value, raising an exception if the value is not valid.
+    #
+    def new_value(name, *args, &block)
+      option(name).new_value(*args, &block)
+    end
+
+    #
+    # Handles a call of #option_name.
+    # Determines whether the call was meant to be a setter or a getter and
+    # acts accordingly.
+    #
+    def handle_option_call(option_name, *args, &block)
+      if getter?(option_name, *args, &block)
+        current_value(option_name)
+      else
+        new_value = new_value(option_name, *args, &block)
+        instance.class.new(@values.merge(option_name.to_sym => new_value))
+      end
+    end
+
+    private
+
+    attr_reader :values, :chain_options
+
+    #
+    # @return [Boolean] +true+ if a call to the corresponding option method with the given args / block
+    #   can be handled as a getter (no args / no block usage)
+    #
+    def getter?(option_name, *args, &block)
+      args.empty? && (block.nil? || !option(option_name).allow_block)
+    end
+
+    # no-doc
+    def raise_no_option_error(name)
+      fail ArgumentError, "There is no option registered called #{name}."
+    end
+
+    #
+    # Checks the given options and transforms certain options into closures,
+    #   if they are symbols before.
+    # The keys that are being transformed can be seen at `Option::METHOD_SYMBOLS`.
+    # @return [Hash] a set of parameters and closures.
+    #
+    def instance_method_hash(options)
+      ChainOptions::Util.slice(options, Option::METHOD_SYMBOLS).each_with_object({}) do |(meth, value), h|
+        next h[meth] = value if value.respond_to?(:call)
+
+        h[meth] = instance.public_method(value)
+      end
+    end
+  end
+end

data/lib/chain_options/test_integration/rspec.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+
+#
+# Custom matcher to test for chain option behaviour.
+#
+# Every matcher call starts with `have_chain_option` which ensures the the given
+# object actually has access to a chain option with the given name.
+#
+# ## Value Acceptance
+#
+# To test for values which should raise an exception when being set as a chain option value,
+# continue the matcher as follows:
+#   it { is_expected.to have_chain_option(:my_option).which_takes(42).and_raises_an_exception }
+#
+# ## Value Filters / Transformations
+#
+# To test whether the option is actually set to the correct value after passing an object to it,
+# continue the matcher as follows:
+#   it { is_expected.to have_chain_option(:my_option).which_takes(42).and_sets_it_as_value }
+#
+# If you expect the option to perform a filtering and/or transformation, you can also
+# specify the actual value you expect to be set:
+#   it { is_expected.to have_chain_option(:my_option).which_takes(42).and_sets("42").as_value }
+#
+# ## Default Value
+#
+# To test whether the option has a certain default value, continue the matcher as follows:
+#   it { is_expected.to have_chain_option(:my_option).with_the_default_value(21) }
+#
+module ChainOptions
+  module TestIntegration
+    module Rspec
+      extend ::RSpec::Matchers::DSL
+
+      matcher :have_chain_option do |option_name|
+        match do |instance|
+          unless chain_option?(instance)
+            error_lines "Expected the class `#{instance.class}`",
+                        "to define the chain option `:#{option_name}`,",
+                        "but it didn't."
+            next false
+          end
+
+          if instance_variable_defined?('@expected_default_value')
+            next false unless correct_default_value?(instance)
+          end
+
+          if instance_variable_defined?('@given_value')
+            if @exception_expected
+              check_for_exception(instance)
+            elsif instance_variable_defined?('@expected_value')
+              check_for_expected_value(instance)
+            end
+          end
+
+          @error.nil?
+        end
+
+        def error_lines(*lines)
+          @error = lines[1..-1].reduce(lines.first) do |error_string, line|
+            error_string + "\n  #{line}"
+          end
+        end
+
+        define_method :chain_option? do |instance|
+          instance.class.available_chain_options.key?(option_name.to_sym)
+        end
+
+        define_method :correct_default_value? do |instance|
+          actual_default_value = instance.send(option_name)
+          next true if actual_default_value == @expected_default_value
+
+          error_lines "Expected the chain option `:#{option_name}`",
+                      "of the class `#{instance.class}`",
+                      "to have the default value `#{@expected_default_value.inspect}`",
+                      "but the actual default value is `#{actual_default_value.inspect}`"
+        end
+
+        define_method :check_for_exception do |instance|
+          begin
+            instance.send(option_name, @given_value)
+            error_lines "Expected the chain option `:#{option_name}`",
+                        "not to accept the value `#{@given_value.inspect}`,",
+                        'but it did.'
+          rescue ArgumentError => e
+            raise unless e.message.include?('not valid')
+          end
+        end
+
+        define_method :check_for_expected_value do |instance|
+          actual_value = instance.send(option_name, @given_value).send(option_name)
+          if actual_value != @expected_value
+            error_lines "Expected the chain option `:#{option_name}`",
+                        "of the class `#{instance.class}`",
+                        "to accept the value `#{@given_value.inspect}`",
+                        "and set the option value to `#{@expected_value.inspect}`,",
+                        "but it was set to `#{actual_value.inspect}`"
+          end
+        end
+
+        chain :with_the_default_value do |expected_default_value|
+          @expected_default_value = expected_default_value
+        end
+
+        chain :which_takes do |value|
+          @given_value = value
+        end
+
+        chain :and_sets do |expected_value|
+          @expected_value = expected_value
+        end
+
+        chain :and_sets_it_as_value do
+          @expected_value = @given_value
+        end
+
+        chain :and_raises_an_exception do
+          @exception_expected = true
+        end
+
+        chain(:as_value) {}
+
+        failure_message do
+          @error.to_s
+        end
+      end
+    end
+  end
+end

data/lib/chain_options/util.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module ChainOptions
+  module Util
+
+    def self.blank?(obj)
+      (obj.is_a?(Enumerable) && obj.empty?) || obj.nil? || obj == ''
+    end
+
+    def self.slice(hash, keys)
+      keys.each_with_object({}) do |key, h|
+        h[key] = hash[key] if hash[key]
+      end
+    end
+
+    #
+    # Evaluate the given proc in the context of the given object if the
+    # block's arity is non-positive, or by passing the given object as an
+    # argument if it is negative.
+    #
+    # ==== Parameters
+    #
+    # object<Object>:: Object to pass to the proc
+    #
+    def self.instance_eval_or_call(object, &block)
+      if block.arity.positive?
+        block.call(object)
+      else
+        ContextBoundDelegate.instance_eval_with_context(object, &block)
+      end
+    end
+
+    #
+    # Shamelessly copied from sunspot/sunspot with some alterations
+    #
+    class ContextBoundDelegate
+      class << self
+        def instance_eval_with_context(receiver, &block)
+          calling_context = eval('self', block.binding, __FILE__, __LINE__)
+
+          parent_calling_context = calling_context.instance_eval do
+            @__calling_context__ if defined?(@__calling_context__)
+          end
+
+          calling_context = parent_calling_context if parent_calling_context
+          new(receiver, calling_context).instance_eval(&block)
+        end
+
+        private :new
+      end
+
+      BASIC_METHODS = Set[:==, :equal?, :"!", :"!=", :instance_eval,
+                          :object_id, :__send__, :__id__]
+
+      instance_methods.each do |method|
+        unless BASIC_METHODS.include?(method.to_sym)
+          undef_method(method)
+        end
+      end
+
+      def initialize(receiver, calling_context)
+        @__receiver__, @__calling_context__ = receiver, calling_context
+      end
+
+      def id
+        @__calling_context__.__send__(:id)
+      rescue ::NoMethodError => e
+        begin
+          @__receiver__.__send__(:id)
+        rescue ::NoMethodError
+          raise(e)
+        end
+      end
+
+      # Special case due to `Kernel#sub`'s existence
+      def sub(*args, &block)
+        __proxy_method__(:sub, *args, &block)
+      end
+
+      def method_missing(method, *args, &block)
+        __proxy_method__(method, *args, &block)
+      end
+
+      def respond_to_missing?(meth)
+        @__receiver__.respond_to?(meth) || @__calling_context__.respond_to?(meth)
+      end
+
+      def __proxy_method__(method, *args, &block)
+        @__receiver__.__send__(method.to_sym, *args, &block)
+      rescue ::NoMethodError => e
+        begin
+          @__calling_context__.__send__(method.to_sym, *args, &block)
+        rescue ::NoMethodError
+          raise(e)
+        end
+      end
+    end
+  end
+end

data/lib/chain_options/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ChainOptions
+  VERSION = '0.1.0'
+end

data/lib/chain_options.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'chain_options/version'
+
+require 'chain_options/util'
+require 'chain_options/option_set'
+require 'chain_options/option'
+require 'chain_options/integration'
+require 'chain_options/builder'
+
+module ChainOptions
+end