abstract_mapper 0.0.1

data/lib/abstract_mapper/optimizer.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # Optimizes the immutable abstract syntax tree (AST) using comfigurable
+  # collection of applicable rules.
+  #
+  # @api private
+  #
+  class Optimizer
+
+    # @!attribute [r] rules
+    #
+    # @return [AbstractMapper::Rules]
+    #   The collection of applicable optimization rules
+    #
+    attr_reader :rules
+
+    # @!scope class
+    # @!method new(rules = Rules.new)
+    # Creates the optimizer
+    #
+    # @param [AbstractMapper::Rules] rules
+    #   The collection of applicable optimization rules
+    #
+    # @return [AbstractMapper::Optimizer]
+
+    # @private
+    def initialize(rules)
+      @rules = rules
+      freeze
+    end
+
+    # Recursively optimizes the AST from root to leafs
+    #
+    # @param [AbstractMapper::Branch] tree
+    #
+    # @return [AbstractMapper::Branch]
+    #
+    def update(tree)
+      return tree unless tree.is_a? Branch
+      new_tree = tree.rebuild { rules[tree] }
+      new_tree.rebuild { new_tree.map(&method(:update)) }
+    end
+
+  end # class Optimizer
+
+end # class AbstractMapper

data/lib/abstract_mapper/pair_rule.rb

@@ -0,0 +1,66 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # The base class for rules to be applied to pairs of nodes.
+  #
+  # The subclass should implement two instance methods:
+  #
+  # * `#optimize?` to check if the optimization should be applied to the nodes
+  # * `#optimize` that should return the merged node
+  #
+  # @example
+  #   class MergeConsecutiveLists < AbstractMapper::PairRule
+  #     def optimize?
+  #       left.is_a?(List) & right.is_a?(List)
+  #     end
+  #
+  #     def optimize
+  #       List.new { left.entries + right.entries }
+  #     end
+  #   end
+  #
+  # @abstract
+  #
+  # @api public
+  #
+  class PairRule < Rule
+
+    # Returns the name of transproc used to compose rules
+    #
+    # @return [Symbol]
+    #
+    def self.composer
+      :compact
+    end
+
+    # @!attribute [r] node
+    #
+    # @return [AbstractMapper::Node] The left node in the pair to be optimized
+    #
+    attr_reader :left
+
+    # @!attribute [r] node
+    #
+    # @return [AbstractMapper::Node] The right node in the pair to be optimized
+    #
+    attr_reader :right
+
+    # @!scope class
+    # @!method new(node)
+    # Creates a rule applied to the sole node
+    #
+    # @param [AbstractMapper::Node] node
+    #
+    # @return [AbstractMapper::Rule]
+
+    # @private
+    def initialize(left, right)
+      @left  = left
+      @right = right
+      super
+    end
+
+  end # class PairRule
+
+end # class AbstractMapper

data/lib/abstract_mapper/rspec.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+
+# Collection of shared examples for testing parts of DSL
+require_relative "../rspec/functions"
+require_relative "../rspec/nodes"
+require_relative "../rspec/rules"
+require_relative "../rspec/mapper"

data/lib/abstract_mapper/rule.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # Base class for nodes optimization rules
+  #
+  # @abstract
+  #
+  # @api private
+  #
+  class Rule
+
+    # The transformation function that applies the rule to the array of nodes
+    #
+    # @return [Transproc::Function]
+    #
+    def self.transproc
+      Functions[composer, proc { |*nodes| new(*nodes).call }]
+    end
+
+    # @!attribute [r] nodes
+    #
+    # @return [Array<AbstractMapper::Node>]
+    #   Either one or two nodes to be optimized
+    #
+    attr_reader :nodes
+
+    # @!scope class
+    # @!method new(*nodes)
+    # Creates the rule for a sole node, or a pair of consecutive nodes
+    #
+    # @param [Array<AbstractMapper::Node>] nodes
+    #
+    # @return [AbstractMapper::Rule]
+
+    # @private
+    def initialize(*nodes)
+      @nodes = nodes.freeze
+      freeze
+    end
+
+    # Returns the result of the rule applied to the initialized [#nodes]
+    #
+    # @return [Array<AbstractMapper::Node>]
+    #
+    def call
+      optimize? ? [optimize].flatten.compact : nodes
+    end
+
+  end # class Rule
+
+end # class AbstractMapper

data/lib/abstract_mapper/rules.rb

@@ -0,0 +1,61 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # Registry of DSL rules applicable to nodes of AST
+  #
+  # @api private
+  #
+  class Rules
+
+    # @!attribute [r] registry
+    #
+    # @return [Array<AbstractMapper::SoleRule>] list of rules applicable to AST
+    #
+    attr_reader :registry
+
+    # @!scope class
+    # @!method new(registry)
+    # Creates a registry with array of rules
+    #
+    # @param [Array<AbstractMapper::SoleRule>] registry Array of rules
+    #
+    # @return [AbstractMapper::Rules]
+
+    # @private
+    def initialize(registry = [])
+      @registry  = registry.dup.freeze
+      @transproc = ordered.map(&:transproc).inject(:>>)
+      freeze
+    end
+
+    # Returns the copy of current registry with the new rule added
+    #
+    # @param [AbstractMapper::SoleRule] other
+    #
+    # @return (see #new)
+    #
+    def <<(other)
+      self.class.new(registry + [other])
+    end
+
+    # Applies all the registered rules to the array of nodes
+    #
+    # @param [Array<AbstractMapper::Node>] nodes
+    #
+    # @return [Array<AbstractMapper::Node>] The optimized array of nodes
+    #
+    def [](nodes)
+      @transproc ? @transproc[nodes] : nodes
+    end
+
+    private
+
+    # Calls all sole rules first
+    def ordered
+      registry.sort_by { |rule| Functions[:subclass?, PairRule][rule].to_s }
+    end
+
+  end # class Rules
+
+end # class AbstractMapper

data/lib/abstract_mapper/settings.rb

@@ -0,0 +1,95 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # The configurable container of domain-specific DSL commands and rules
+  # along with corresponding AST builder and optimizer
+  #
+  # @api private
+  #
+  class Settings
+
+    # @!attribute [r] commands
+    #
+    # @return [AbstractMapper::Commands]
+    #   The collection of registered DSL commands
+    #
+    attr_reader :commands
+
+    # @!attribute [r] rules
+    #
+    # @return [AbstractMapper::Rules]
+    #   The collection of registered optimization rules
+    #
+    attr_reader :rules
+
+    # @!attribute [r] optimizer
+    #
+    # @return [AbstractMapper::Optimizer]
+    #   The optimizer with domain-specific rules
+    #
+    attr_reader :optimizer
+
+    # @!attribute [r] builder
+    #
+    # @return [Class] The builder class with domain-specific commands
+    #
+    attr_reader :builder
+
+    # @!scope class
+    # @!method new(&block)
+    # Creates a domain-specific settings with commands and rules initialized
+    # from inside a block
+    #
+    # @param [Proc] block
+    #
+    # @return [AbstractMapper::Settings]
+
+    # @private
+    def initialize(&block)
+      __set_rules__
+      __set_commands__
+      __configure__(&block)
+      __set_builder__
+      __set_optimizer__
+      freeze
+    end
+
+    private
+
+    def rule(value)
+      fn = Functions[:subclass?, Rule]
+      fail Errors::WrongRule.new(value) unless fn[value]
+      @rules = rules << value
+    end
+
+    def command(name, node)
+      fn = Functions[:subclass?, Node]
+      fail Errors::WrongNode.new(node) unless fn[node]
+      @commands = commands << [name, node]
+    end
+
+    def __set_rules__
+      @rules = Rules.new
+    end
+
+    def __set_commands__
+      @commands = Commands.new
+    end
+
+    def __configure__(&block)
+      instance_eval(&block) if block_given?
+    end
+
+    def __set_builder__
+      @builder = Class.new(Builder)
+      builder.commands = commands
+    end
+
+    def __set_optimizer__
+      @optimizer = Optimizer.new(rules)
+    end
+
+  end # class Settings
+
+end # class AbstractMapper

data/lib/abstract_mapper/sole_rule.rb

@@ -0,0 +1,58 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # The abstract class that describes the rule to be applied to sole nodes.
+  #
+  # The subclass should implement two instance methods:
+  #
+  # * `#optimize?` to check if the optimization should be applied to the node
+  # * `#optimize` that should return the optimized node
+  #
+  # @example
+  #   class RemoveEmptyList < AbstractMapper::SoleRule
+  #     def optimize?
+  #       node.is_a?(List) && node.empty?
+  #     end
+  #
+  #     def optimize
+  #     end
+  #   end
+  #
+  # @abstract
+  #
+  # @api public
+  #
+  class SoleRule < Rule
+
+    # Returns the name of transproc used to compose rules
+    #
+    # @return [Symbol]
+    #
+    def self.composer
+      :filter
+    end
+
+    # @!attribute [r] node
+    #
+    # @return [AbstractMapper::Node] The node to be optimized
+    #
+    attr_reader :node
+
+    # @!scope class
+    # @!method new(node)
+    # Creates a rule applied to the sole node
+    #
+    # @param [AbstractMapper::Node] node
+    #
+    # @return [AbstractMapper::Rule]
+
+    # @private
+    def initialize(node)
+      @node = node
+      super
+    end
+
+  end # class SoleRule
+
+end # class AbstractMapper

data/lib/abstract_mapper/version.rb

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # The semantic version of the module.
+  # @see http://semver.org/ Semantic versioning 2.0
+  VERSION = "0.0.1".freeze
+
+end # class AbstractMapper

data/lib/abstract_mapper.rb

@@ -0,0 +1,82 @@
+# encoding: utf-8
+
+require "transproc"
+
+require_relative "abstract_mapper/functions"
+
+require_relative "abstract_mapper/errors/unknown_command"
+require_relative "abstract_mapper/errors/wrong_node"
+require_relative "abstract_mapper/errors/wrong_rule"
+
+require_relative "abstract_mapper/node"
+require_relative "abstract_mapper/branch"
+require_relative "abstract_mapper/commands"
+require_relative "abstract_mapper/builder"
+
+require_relative "abstract_mapper/rule"
+require_relative "abstract_mapper/sole_rule"
+require_relative "abstract_mapper/pair_rule"
+require_relative "abstract_mapper/rules"
+require_relative "abstract_mapper/optimizer"
+
+require_relative "abstract_mapper/settings"
+require_relative "abstract_mapper/dsl"
+
+# The configurable base class for mappers
+#
+# The mapper DSL is configured by assigning it a specific settings:
+#
+#   class BaseMapper < AbstractMapper::Mapper
+#     configure do
+#       command :list, List     # domain-specific command
+#       command :rename, Rename # domain-specific command
+#
+#       rule MergeLists         # domain-specific rule
+#     end
+#   end
+#
+# Then a configured mapper can use a corresponding DSL commands
+#
+#   class ConcreteMapper < BaseMapper
+#     list do
+#       rename :foo, to: :bar
+#     end
+#   end
+#
+# @api public
+#
+class AbstractMapper
+
+  extend DSL # configurable DSL container
+
+  # @!attribute [r] tree
+  #
+  # @return [AbstractMapper::Branch] AST
+  #
+  attr_reader :tree
+
+  # @!scope class
+  # @!method new
+  # Creates a mapper instance with the optimized AST
+  #
+  # @return [AbstractMapper::Mapper]
+
+  # @private
+  def initialize
+    @tree = self.class.finalize
+    @transproc = @tree.transproc
+    freeze
+  end
+
+  # Maps the input data to some output using the transformation,
+  # described by the optimized [#tree]
+  #
+  # @param [Object] input
+  #
+  # @return [Object]
+  #
+  def call(input)
+    @transproc.call(input)
+  end
+
+end # class AbstractMapper

data/lib/rspec/functions.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+# ==============================================================================
+# Examples for testing transproc functions
+# ==============================================================================
+
+shared_examples :transforming_immutable_data do
+
+  let(:fn) { described_class[*arguments] }
+
+  subject { fn[input.dup.freeze] }
+
+  it do
+    is_expected.to eql(output), <<-REPORT.gsub(/.+\|/, "")
+      |
+      |fn = #{described_class}[{arguments}]
+      |
+      |fn#{Array[*input]}
+      |
+      |  expected: #{output}
+      |       got: #{subject}
+    REPORT
+  end
+
+end # shared examples

data/lib/rspec/mapper.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+# ==============================================================================
+# Examples for testing DSL registry
+# ==============================================================================
+
+shared_examples :defining_rule do
+
+  subject { described_class.settings.rules.registry }
+  it do
+    is_expected.to include(rule), <<-REPORT.gsub(/.+\|/, "")
+      |
+      |#{described_class} optimization rules
+      |
+      |expected to include #{rule.inspect}
+      |     got rules:
+      |#{subject.map { |rule| "#{" " * 9}- #{rule.inspect}" }.join("\n")}
+    REPORT
+  end
+
+end # shared examples
+
+shared_examples :defining_command do
+
+  subject { described_class.settings.commands.registry }
+  it "registers the command" do
+    expect(subject[name]).to eql(node), <<-REPORT.gsub(/.+\|/, "")
+      |
+      |#{described_class} DSL commands
+      |
+      |expected to include '#{name}' adding #{node.inspect}
+      |     got commands:
+      |#{subject
+        .map { |name, node| "#{" " * 9}- #{name}: #{node.inspect}" }
+        .sort
+        .join("\n")}
+    REPORT
+  end
+
+end # shared examples

data/lib/rspec/nodes.rb

@@ -0,0 +1,58 @@
+# encoding: utf-8
+
+# ==============================================================================
+# Examples for testing nodes
+# ==============================================================================
+
+shared_context :node do
+
+  def node
+    attrs__ = defined?(attributes) ? attributes : []
+    block__ = defined?(block) ? block : nil
+    described_class.new(*attrs__, &block__)
+  end
+
+end # shared context
+
+shared_examples :creating_immutable_node do
+
+  include_context :node
+
+  subject { node }
+
+  it { is_expected.to be_kind_of AbstractMapper::Node }
+  it { is_expected.to be_frozen, "expected #{subject.inspect} to be immutable" }
+
+end # shared examples
+
+shared_examples :creating_immutable_branch do
+
+  include_context :node
+
+  subject { node }
+
+  it { is_expected.to be_kind_of AbstractMapper::Branch }
+  it { is_expected.to be_frozen, "expected #{subject.inspect} to be immutable" }
+
+end # shared examples
+
+shared_examples :mapping_immutable_input do
+
+  include_context :node
+
+  subject { node.transproc.call(input.dup.freeze) }
+
+  it do
+    is_expected.to eql(output), <<-REPORT.gsub(/.+\|/, "")
+      |
+      |#{node}
+      |
+      |Input: #{input}
+      |
+      |Output:
+      |  expected: #{output}
+      |       got: #{subject}
+    REPORT
+  end
+
+end # shared examples

data/lib/rspec/rules.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+
+# ==============================================================================
+# Examples for testing rules
+# ==============================================================================
+
+shared_context :rule do
+
+  def nodes
+    defined?(input) ? [input].flatten : []
+  end
+
+  def optimized
+    defined?(output) ? [output].flatten : []
+  end
+
+  let(:rule) { described_class }
+
+  subject { rule.new(*nodes).call.inspect }
+
+end # shared context
+
+shared_examples :skipping_nodes do
+
+  include_context :rule
+
+  it do
+    is_expected.to eql(nodes.inspect), <<-REPORT.gsub(/.+\|/, "")
+      |
+      |#{rule}
+      |
+      |Input: #{nodes.inspect}
+      |
+      |Output:
+      |  expected: #{nodes.inspect}
+      |       got: #{subject}
+    REPORT
+  end
+
+end # shared examples
+
+shared_examples :optimizing_nodes do
+
+  include_context :rule
+
+  it do
+    is_expected.to eql(optimized.inspect), <<-REPORT.gsub(/.+\|/, "")
+      |
+      |#{rule}
+      |
+      |Input: #{nodes.inspect}
+      |
+      |Output:
+      |  expected: #{optimized.inspect}
+      |       got: #{subject}
+    REPORT
+  end
+
+end # shared examples