abstract_mapper 0.0.1

data/config/metrics/roodi.yml

@@ -0,0 +1,24 @@
+---
+AssignmentInConditionalCheck:
+CaseMissingElseCheck:
+ClassLineCountCheck:
+  line_count: 100
+ClassNameCheck:
+  pattern: !ruby/regexp /^[A-Z][a-zA-Z0-9]*$/
+ClassVariableCheck:
+CyclomaticComplexityBlockCheck:
+  complexity: 3
+CyclomaticComplexityMethodCheck:
+  complexity: 3
+EmptyRescueBodyCheck:
+ForLoopCheck:
+MethodLineCountCheck:
+  line_count: 7
+MethodNameCheck:
+  pattern: !ruby/regexp /^[\||\^|\&|\!]$|^[_a-z<>=\[|+-\/\*`]+[_a-z0-9_<>=~@\[\]]*[=!\?]?$/
+ModuleLineCountCheck:
+  line_count: 100
+ModuleNameCheck:
+  pattern: !ruby/regexp /^[A-Z][a-zA-Z0-9]*$/
+ParameterNumberCheck:
+  parameter_count: 3

data/config/metrics/rubocop.yml

@@ -0,0 +1,76 @@
+---
+# settings added by the 'hexx-suit' module
+# output: "tmp/rubocop"
+# format: "html"
+
+AllCops:
+  Exclude:
+    - '**/db/schema.rb'
+
+Lint/HandleExceptions:
+  Exclude:
+    - '**/*_spec.rb'
+
+Lint/RescueException:
+  Exclude:
+    - '**/*_spec.rb'
+
+Metrics/LineLength:
+  Exclude:
+    - '**/integration/*_spec.rb'
+
+Style/AccessorMethodName:
+  Exclude:
+    - '**/*_spec.rb'
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+Style/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Style/EmptyLinesAroundMethodBody:
+  Enabled: false
+
+Style/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+Style/EmptyLineBetweenDefs:
+  Enabled: false
+
+Style/FileName:
+  Enabled: false
+
+Style/RaiseArgs:
+  EnforcedStyle: compact
+
+Style/SingleLineMethods:
+  Exclude:
+    - '**/*_spec.rb'
+
+Style/SingleSpaceBeforeFirstArg:
+  Enabled: false
+
+Style/SpecialGlobalVars:
+  Exclude:
+    - '**/Gemfile'
+    - '**/*.gemspec'
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/TrivialAccessors:
+  Exclude:
+    - '**/*_spec.rb'

data/config/metrics/saikuro.yml

@@ -0,0 +1,3 @@
+---
+warn_cyclo:  2
+error_cyclo: 3

data/config/metrics/simplecov.yml

@@ -0,0 +1,6 @@
+---
+output: tmp/coverage
+filters: # The list of paths to be excluded from coverage checkup
+- "spec/"
+- "config/"
+groups: []

data/config/metrics/yardstick.yml

@@ -0,0 +1,37 @@
+---
+# Settings added by the 'hexx-suit' gem
+output: "tmp/yardstick/output.log"
+path: "lib/**/*.rb"
+rules:
+  ApiTag::Presence:
+    enabled: true
+    exclude: []
+  ApiTag::Inclusion:
+    enabled: true
+    exclude: []
+  ApiTag::ProtectedMethod:
+    enabled: true
+    exclude: []
+  ApiTag::PrivateMethod:
+    enabled: false
+    exclude: []
+  ExampleTag:
+    enabled: true
+    exclude: []
+  ReturnTag:
+    enabled: true
+    exclude: []
+  Summary::Presence:
+    enabled: true
+    exclude: []
+  Summary::Length:
+    enabled: true
+    exclude: []
+  Summary::Delimiter:
+    enabled: true
+    exclude: []
+  Summary::SingleLine:
+    enabled: true
+    exclude: []
+threshold: 100
+verbose: false

data/lib/abstract_mapper/branch.rb

@@ -0,0 +1,110 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # A special type of the composed node, that describes transformation,
+  # applied to some level of nested input.
+  #
+  # Unlike the simple node, describing a transformation of data, the
+  # branch carries a collection of subnodes along with methods to [#rebuild]
+  # itself with the same attributes and different subnodes.
+  #
+  # Tne branch only stores subnodes and composes transformations.
+  # Its has no access to DSL and knows neither how to build a tree
+  # (see [AbstractMapper::Builder]), nor how to optimize it later
+  # (see [AbstractMapper::Optimizer]).
+  #
+  # @api public
+  #
+  class Branch < Node
+
+    include Enumerable
+
+    # @!scope class
+    # @!method new(*attributes, &block)
+    # Creates a new branch
+    #
+    # @param [Object, Array<Object>] attributes
+    #   The list of type-specific attributes of the branch
+    # @param [Proc] block
+    #   The block that returns an array of subnodes for the branch
+    #
+    # @return [Branch::Node]
+
+    # @private
+    def initialize(*attributes)
+      @subnodes = block_given? ? yield : []
+      super(*attributes, &nil)
+    end
+
+    # Returns a new branch of the same type, with the same attributes,
+    # but with a different collection of subnodes, transmitted by the block.
+    #
+    # @example
+    #   branch = Branch.new(:foo)
+    #   # => <Branch(:foo) []>
+    #   branch.rebuild { Node.new(:bar) }
+    #   # => <Branch(:foo) [<Node(:bar)>]>
+    #
+    # @param [Proc] block
+    #   The block that should return an array of subnodes for the branch
+    #
+    # @return [AbstractMapper::Branch]
+    #
+    # @yield block
+    #
+    def rebuild(&block)
+      self.class.new(*attributes, &block)
+    end
+
+    # @!method each
+    # Returns the enumerator for subnodes
+    #
+    # @return [Enumerator]
+    #
+    def each(&block)
+      @subnodes.each(&block)
+    end
+
+    # Returns a new branch with the other node added to its subnodes
+    #
+    # @param [AbstractMapper::Node] other
+    #
+    # @return [AbstractMapper::Branch]
+    #
+    def <<(other)
+      rebuild { entries << other }
+    end
+
+    # The composition of transformations from all subnodes of the branch
+    #
+    # To be reloaded by the subclasses to apply the composition to
+    # a corresponding level of nested data.
+    #
+    # @return [Transproc::Function]
+    #
+    # @abstract
+    #
+    def transproc
+      map(&:transproc).inject(:>>)
+    end
+
+    # Adds subnodes to the default description of the branch
+    #
+    # @return [String]
+    #
+    def to_s
+      "#{super} [#{map(&:inspect).join(", ")}]"
+    end
+
+    private
+
+    # Substitutes the name of the class by the special name "Root"
+    # to describe the root node of AST.
+    def __name__
+      instance_of?(Branch) ? "Root" : super
+    end
+
+  end # class Branch
+
+end # class AbstractMapper

data/lib/abstract_mapper/builder.rb

@@ -0,0 +1,84 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # Builds the immutable abstract syntax tree (AST) using DSL commands.
+  #
+  # @example
+  #   Builder.update do
+  #     field :user do     # DSL method
+  #       add_prefix :user # DSL method for subtree
+  #     end
+  #   end
+  #   # => <Root() [<Field(:user) [<AddPrefix(:user)>]>]>
+  #
+  # @api private
+  #
+  class Builder
+
+    class << self
+
+      # @!attribute [rw] commands
+      #
+      # @return [AbstractMapper::Commands] The registry of DSL commands
+      #
+      attr_accessor :commands
+
+    end # eigenclass
+
+    # Updates given node by adding its subnode from the block
+    #
+    # @param [AbstractMapper::Branch] node
+    #   The root of the tree to be updated
+    # @param [Proc] block
+    #   The block with DSL commands for adding subnodes
+    #
+    # @return (see #tree)
+    #
+    def self.update(node = Branch.new, &block)
+      new(node, &block).tree
+    end
+
+    # @!attribute [r] tree
+    #
+    # @return [AbstractMapper::Branch] The updated tree
+    #
+    attr_reader :tree
+
+    # @!scope class
+    # @!method new(node, &block)
+    # Builds the AST by recursively adding new nodes, using the commands
+    #
+    # @param [AbstractMapper::Branch] node
+    #   The root of the tree to be updated
+    # @param [Proc] block
+    #   The block with DSL commands for adding subnodes
+    #
+    # @return [AbstractMapper::Builder]
+
+    # @private
+    def initialize(node, &block)
+      @tree     = node
+      @commands = self.class.commands
+      instance_eval(&block) if block_given?
+      freeze
+    end
+
+    private # DSL commands
+
+    def method_missing(name, *args, &block)
+      node  = @commands[name, *args, &block]
+      @tree = tree << (node.is_a?(Branch) ? update(node, &block) : node)
+    end
+
+    def respond_to_missing?(*)
+      true
+    end
+
+    def update(node, &block)
+      self.class.update(node, &block)
+    end
+
+  end # class Builder
+
+end # class AbstractMapper

data/lib/abstract_mapper/commands.rb

@@ -0,0 +1,71 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # Registry of DSL commands used by the builder
+  #
+  # @api private
+  #
+  class Commands
+
+    # @!attribute [r] registry
+    #
+    # @return [Hash<Symbol => Class>]
+    #   The registry of command names, pointing to types of the nodes,
+    #   that should be built for adding to AST
+    #
+    attr_reader :registry
+
+    # @!scope class
+    # @!method new(registry = {})
+    # Creates an immutable collection of commands
+    #
+    # @param [Hash] registry
+    #
+    # @return [Faceter::Commands]
+
+    # @private
+    def initialize(registry = {})
+      @registry = registry.dup.freeze
+      freeze
+    end
+
+    # Returns a new immutable registry with added command name and type
+    #
+    # @param [Array<Symbol, Class>] other
+    #
+    # @return [undefined]
+    #
+    def <<(other)
+      name = other[0]
+      node = other[1]
+      self.class.new registry.merge(name.to_sym => node)
+    end
+
+    # Builds a node by the name of DSL command
+    #
+    # Skips the block if a registered node is a branch
+    #
+    # @param [#to_sym] name The name of the command
+    # @param [Object, Array] args The command's arguments
+    # @param [Proc] block
+    #   The block to be passed to the constructor of the simple node
+    #
+    # @raise [AbstractMapper::Errors::UnknownCommand]
+    #   When unknown command is called
+    #
+    def [](name, *args, &block)
+      type   = get(name)
+      branch = Functions[:subclass?, Branch][type]
+      branch ? type.new(*args) : type.new(*args, &block)
+    end
+
+    private
+
+    def get(name)
+      registry.fetch(name.to_sym) { fail(Errors::UnknownCommand.new name) }
+    end
+
+  end # class Commands
+
+end # class AbstractMapper

data/lib/abstract_mapper/dsl.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # Provides features to configure mappers
+  #
+  # @api private
+  #
+  module DSL
+
+    # @private
+    def inherited(klass)
+      klass.instance_variable_set :@settings, settings
+    end
+
+    # @!attribute [r] settings
+    #
+    # @return [AbstractMapper::Settings]
+    #   The configurable container of domain-specific settings
+    #   (DSL commands and optimization rules along with corresponding
+    #   AST builder and optimizer).
+    #
+    attr_reader :settings
+
+    # Configures domain-specific settings
+    #
+    # @param [Proc] block The block where rules and commands to be registered
+    #
+    # @return [self] itself
+    #
+    # @yield a block
+    #
+    def configure(&block)
+      @settings = Settings.new(&block)
+      self
+    end
+
+    # Returns the optimized AST
+    #
+    # @return [AbstractMapper::Branch]
+    #
+    def finalize
+      settings.optimizer.update(tree)
+    end
+
+    private # DSL commands
+
+    def tree
+      @tree ||= Branch.new
+    end
+
+    def respond_to_missing?(*)
+      true
+    end
+
+    def method_missing(name, *args, &block)
+      @tree = settings.builder.update(tree) { public_send(name, *args, &block) }
+    end
+
+  end # module DSL
+
+end # class AbstractMapper

data/lib/abstract_mapper/errors/unknown_command.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # The collection of gem-specific errors
+  #
+  module Errors
+
+    # An exception to be raised when unknown DSL methods is used
+    #
+    # @api public
+    #
+    class UnknownCommand < NameError
+
+      # @private
+      def initialize(name)
+        super "'#{name}' is not a registered DSL command"
+        freeze
+      end
+
+    end # class UnknownCommand
+
+  end # module Errors
+
+end # class AbstractMapper

data/lib/abstract_mapper/errors/wrong_node.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  module Errors
+
+    # An exception to be raised when wrong node is registered as a DSL command
+    #
+    # @api public
+    #
+    class WrongNode < TypeError
+
+      # @private
+      def initialize(node)
+        super "#{node} is not a subclass of AbstractMapper::Node"
+        freeze
+      end
+
+    end # class WrongNode
+
+  end # module Errors
+
+end # class AbstractMapper

data/lib/abstract_mapper/errors/wrong_rule.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  module Errors
+
+    # An exception to be raised when wrong node is registered as a DSL command
+    #
+    # @api public
+    #
+    class WrongRule < TypeError
+
+      # @private
+      def initialize(node)
+        super "#{node} is not a subclass of AbstractMapper::SoleRule"
+        freeze
+      end
+
+    end # class WrongRule
+
+  end # module Errors
+
+end # class AbstractMapper

data/lib/abstract_mapper/functions.rb

@@ -0,0 +1,76 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # The collection of gem-specific pure functions (transproc)
+  #
+  # @api private
+  #
+  module Functions
+
+    extend Transproc::Registry
+
+    uses :map_array, from: Transproc::ArrayTransformations
+
+    # Applies the function to every element of array and removes empty values
+    #
+    # @example
+    #   fn = Functions[:filter, -> v { v - 1 if v > 3 }]
+    #   fn[[1, 4, 5, 3, 2, 5, 9]]
+    #   # => [3, 4, 4, 8]
+    #
+    # @param [Array] array
+    # @param [Proc] fn
+    #
+    # @return [Array]
+    #
+    def filter(array, fn)
+      map_array(array, fn).compact.flatten
+    end
+
+    # Applies the function to every consecutive pair of array elements,
+    # and removes empty values
+    #
+    # @example
+    #   function = -> a, b { (a == b) ? [a + b] : [a, b] }
+    #   fn = Functions[:compact, function]
+    #   fn[[1, 1, 2]] # => [4]
+    #   fn[[1, 2, 2]] # => [1, 4]
+    #
+    # @param [Array] array
+    # @param [Proc] fn
+    #   Anonymous function (proc, lambda), that takes two arguments
+    #   and returns an array
+    #
+    # @return [Array]
+    #
+    def compact(array, fn)
+      array.each_with_object([]) do |i, a|
+        if a.empty?
+          a << i
+        else
+          a[-1] = fn.call(a.last, i)
+          a.flatten!
+        end
+      end
+    end
+
+    # Checks whether the class or module has given ancestor
+    #
+    # @example
+    #   fn = Functions[:subclass?, Module]
+    #   fn[Class]  # => true
+    #   fn[Object] # => false
+    #
+    # @param [Module] subling
+    # @param [Module] ancestor
+    #
+    # @return [Boolean]
+    #
+    def subclass?(subling, ancestor)
+      subling.ancestors.include?(ancestor)
+    end
+
+  end # module Functions
+
+end # class AbstractMapper

data/lib/abstract_mapper/node.rb

@@ -0,0 +1,76 @@
+# encoding: utf-8
+
+class AbstractMapper
+
+  # An immutable node of the abstract syntax tree (AST), that describes
+  # either some "end-up" transformation, or a level of nested input data.
+  #
+  # Every node is expected to accept attributes and (possibly) block, and
+  # implement `#transproc` that implements the `#call` method to
+  # transform input data to the output.
+  #
+  # Nodes describe only the structure of AST, they know
+  # neither how to build the tree with DSL (see [AbstractMapper::Builder]),
+  # nor how to optimize it later (see [AbstractMapper::Optimizer]).
+  #
+  # @api public
+  #
+  class Node
+
+    # @!attribute [r] attributes
+    #
+    # @return [Array] The list of node-specific attributes
+    #
+    attr_reader :attributes
+
+    # @!attribute [r] block
+    #
+    # @return [Proc] The block given to initializer
+    #
+    attr_reader :block
+
+    # @private
+    def initialize(*attributes, &block)
+      @attributes = attributes.freeze
+      @block      = block
+      freeze
+    end
+
+    # @!method transproc
+    # The transformation function for the branch
+    #
+    # @abstract
+    #
+    def transproc
+      Transproc::Function.new(-> v { v }, {})
+    end
+
+    # Returns a human-readable string representating the node
+    #
+    # @return [String]
+    #
+    def inspect
+      "<#{self}>"
+    end
+
+    # Converts the node into string with its name and attributes
+    #
+    # @return [String]
+    #
+    def to_s
+      "#{__name__}#{__attributes__}"
+    end
+
+    private
+
+    def __name__
+      self.class.name.split("::").last
+    end
+
+    def __attributes__
+      "(#{attributes.map(&:inspect).join(", ")})" if attributes.any?
+    end
+
+  end # class Node
+
+end # class AbstractMapper