abstract_mapper 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 805663151f746aef76f5fec0a546289ec9d94f22
+  data.tar.gz: f6f64a22fe401d9a53d09bc10d0555445f41b66d
+SHA512:
+  metadata.gz: 84df16b02fe5e3d555ba1829f2876d97383bee2e1ce6c0ac382b2894339bc429aa0ff5bc39c0b048567e44c7dc1b392a457334dc2e94694692ebbfe967bfc453
+  data.tar.gz: 525f8da10ebddb8f46c6448d2b2c679d5621b5e72632c8a7b3b468ed7c5983513bbb6871e747ac2290a8a22a24667e8a42578230d0953b5cbc814071fda3ec9c

data/.coveralls.yml

@@ -0,0 +1,2 @@
+---
+service_name: travis-ci

data/.gitignore

@@ -0,0 +1,9 @@
+*.gem
+*.lock
+.bundle/
+.yardoc/
+coverage/
+doc/
+log/
+pkg/
+tmp/

data/.metrics

@@ -0,0 +1,9 @@
+# Settings for metric_fu and its packages are collected in the `config/metrics`
+# and loaded by the Hexx::Suit::Metrics::MetricFu.
+
+begin
+  require "hexx-suit"
+  Hexx::Suit::Metrics::MetricFu.load
+rescue LoadError
+  puts "The 'hexx-suit' gem is not installed"
+end

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--color

data/.rubocop.yml

@@ -0,0 +1,2 @@
+---
+inherit_from: "./config/metrics/rubocop.yml"

data/.travis.yml

@@ -0,0 +1,19 @@
+---
+language:     ruby
+cache:        bundler
+bundler_args: --without metrics
+rvm:
+  - '1.9.3'
+  - '2.0'
+  - '2.1'
+  - '2.2'
+  - ruby-head
+  - rbx-2 --1.9
+  - rbx-2 --2.1
+  - jruby-19mode
+  - jruby-20mode
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/.yardopts

@@ -0,0 +1,3 @@
+--asset LICENSE
+--exclude lib/abstract_mapper/version.rb
+--output doc/api

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## v0.0.1 2015-07-04
+
+This is the first published version of the gem.

data/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :metrics do
+  gem "hexx-suit", "~> 2.2" if RUBY_ENGINE == "ruby"
+end
+
+gem "thread_safe" # Why on earth I need this here?!

data/Guardfile

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+guard :rspec, cmd: "bundle exec rspec" do
+
+  watch(%r{^spec/.+_spec\.rb$})
+
+  watch(%r{^lib/abstract_mapper/(.+)\.rb$}) do |m|
+    "spec/unit/abstract_mapper/#{m[1]}_spec.rb"
+  end
+
+  watch("lib/abstract_mapper.rb") { "spec" }
+  watch("spec/spec_helper.rb")    { "spec" }
+
+end # guard :rspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2015 Andrew Kozin (nepalez), andrew.kozin@gmail.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,239 @@
+Abstract Mapper
+===============
+
+[![Gem Version](https://img.shields.io/gem/v/abstract_mapper.svg?style=flat)][gem]
+[![Build Status](https://img.shields.io/travis/nepalez/abstract_mapper/master.svg?style=flat)][travis]
+[![Dependency Status](https://img.shields.io/gemnasium/nepalez/abstract_mapper.svg?style=flat)][gemnasium]
+[![Code Climate](https://img.shields.io/codeclimate/github/nepalez/abstract_mapper.svg?style=flat)][codeclimate]
+[![Coverage](https://img.shields.io/coveralls/nepalez/abstract_mapper.svg?style=flat)][coveralls]
+[![Inline docs](http://inch-ci.org/github/nepalez/abstract_mapper.svg)][inch]
+
+[codeclimate]: https://codeclimate.com/github/nepalez/abstract_mapper
+[coveralls]: https://coveralls.io/r/nepalez/abstract_mapper
+[gem]: https://rubygems.org/gems/abstract_mapper
+[gemnasium]: https://gemnasium.com/nepalez/abstract_mapper
+[travis]: https://travis-ci.org/nepalez/abstract_mapper
+[inch]: https://inch-ci.org/github/nepalez/abstract_mapper
+
+Abstract syntax tree (AST) for domain-specific ruby mappers, based on the [transproc] gem.
+
+No monkey-patching, no mutable instances. 100% [mutant]-covered.
+
+[faceter]: https://github.com/nepalez/faceter
+[mutant]: https://github.com/mbj/mutant
+[transproc]: https://github.com/solnic/transproc
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+```ruby
+# Gemfile
+gem "abstract_mapper"
+```
+
+Then execute:
+
+```
+bundle
+```
+
+Or add it manually:
+
+```
+gem install abstract_mapper
+```
+
+Usage
+-----
+
+The gem provides the metalevel of abstraction for defining specific DSL for mappers.
+
+All you need to provide your own **mapper DSL** is:
+
+* define DSL *commands* as a nodes, inherited from `AbstractMapper::Branch` and `AbstractMapper::Node`
+* define DSL-specific *optimization rules* for merging consecutive nodes into more efficient ones
+
+Let's suppose we need to provide a DSL for mappers, that can rename keys in array of tuples.
+The following example represents an oversimplified version of the [faceter] gem.
+
+### Define transformations (specific nodes of AST)
+
+Every node should implement the `#transproc` method that transforms some input data to the output.
+
+When you need attributes, assign them via initializer:
+
+```ruby
+require "abstract_mapper"
+
+module Faceter
+  # The node to define a transformation of every item of the array from input
+  class List < AbstractMapper::Branch
+    # The `List#super` is already composes subnodes. All you need is to define,
+    # how the list should apply that composition to every item of the list
+    #
+    # Here the transformation from the transproc gem is used
+    def transproc
+      Transproc::ArrayTransformations[:map_array, super]
+    end
+  end
+
+  # The node to define a renaming of key in a tuple
+  class Rename < AbstractMapper::Node
+    def initialize(key, **options)
+      @key = key
+      @new_key = options.fetch(:to)
+      super
+    end
+
+    def transproc
+      Transproc::HashTransformations[:rename_keys, @key => @new_key]
+    end
+  end
+end
+```
+
+### Define optimization rules
+
+AbstractMapper defines 2 rules `AbstractMapper::SoleRule` and `AbstractMapper::PairRule`. The first one is applicable to every single node to check if it can be optimized by itself, the second one takes two consecutive nodes and either return them unchanged, or merges them into more time-efficient node.
+
+For every rule you need to define two methods:
+
+* `#optimize?` that defines if the rule is applicable to given node (or pair of nodes)
+* `#optimize` that returns either array of changed nodes, or one node, or nothing when the node(s) should be removed from the tree
+
+Use `#nodes` method to access nodes to be optimized. Base class `AbstractMapper::SoleRule` also defines the `#node` method, while `AbstractMapper::PairRule` defines `#left` and `#right` for the corresponding parts of the pair.
+
+```ruby
+module Faceter
+  # The empty lists are useless, because they does nothing at all
+  class RemoveEmptyLists < AbstractMapper::SoleRule
+    def optimize?
+      node.is_a?(List) && node.empty?
+    end
+
+    def optimize
+      # returns nothing
+    end
+  end
+
+  # Two consecutive list branches are not a good solution, because they
+  # iterates twice via the same array of items in the mapped data.
+  #
+  # That's why when we meet two consecutive lists, we have to merge them
+  # into the one list, containing subnodes (entries) from both sources.
+  class CompactLists < AbstractMapper::PairRule
+    def optimize?
+      nodes.join(:|) { |n| n.is_a? List }
+    end
+
+    def optimize
+      List.new { nodes.map(:entries).flatten }
+    end
+  end
+end
+```
+
+### Register commands and rules
+
+Now that both the nodes (transformers) and optimization rules are defined, its time to register them for the mapper:
+
+```ruby
+module Faceter
+  class Mapper < AbstractMapper
+    configure do
+      command :list,   List
+      command :rename, Rename
+
+      rule RemoveEmptyLists
+      rule CompactLists
+    end
+  end
+end
+```
+
+### Use the mapper
+
+Now we can create a concrete faceter-based mapper, using its DSL:
+
+```ruby
+require "faceter"
+
+class MyMapper < Faceter::Mapper
+  list do
+    rename :foo, to: :bar
+  end
+
+  list do
+    # this is useless, but we have a rule just for the case
+  end
+
+  list do
+    rename :baz, to: :qux
+  end
+end
+
+my_mapper = MyMapper.new
+
+my_mapper.call [{ foo: :FOO, baz: :FOO }, { foo: :BAZ, baz: :BAZ }]
+# => [{ bar: :FOO, qux: :FOO }, { bar: :BAZ, qux: :BAZ }]
+```
+
+All the rules are applied before initializing `my_mapper`, so the AST will be the following:
+
+```ruby
+my_mapper.tree
+# => <Root <List [<Rename(foo:, to: :bar)>, <Rename(:baz, to: :qux)>]>
+```
+
+Testing
+-------
+
+The gem defines a collection of conventional *shared examples* to make [RSpec] tests simple and verbose.
+
+See the list of available examples and how to use them in a [wiki page](https://github.com/nepalez/abstract_mapper/wiki/Shared-examples).
+
+Links
+-----
+
+* [AbstractMapper API] contains some minor details.
+* [Faceter] is an example of rich mapper.
+* [Transproc] is a small gem that converts methods to pure transformers.
+* [ROM] that heavily uses object mappers in its rich datastore adapters.
+
+[AbstractMapper API]: http://www.rubydoc.info/gems/abstract_mapper
+[Faceter]: https://github.com/nepalez/faceter
+[Transproc]: https://github.com/solnic/transproc
+[ROM]: http://rom-rb.org
+
+Credits
+-------
+
+Many thanks to [Piotr Solnica](https://github.com/solnic) and all the [rom](https://gitter.im/rom-rb/chat) and [transproc](https://gitter.im/transproc/chat) contributors for the implementation of the rich data mapper DSL, and for the idea of even more abstract layer.
+
+Compatibility
+-------------
+
+Tested under rubies [compatible to MRI 1.9.3+](.travis.yml).
+
+Uses [RSpec] 3.0+ for testing and [hexx-suit] for dev/test tools collection.
+
+[RSpec]: http://rspec.info
+[hexx-suit]: https://github.com/nepalez/hexx-suit
+
+Contributing
+------------
+
+* Read the [STYLEGUIDE](config/metrics/STYLEGUIDE)
+* [Fork the project](https://github.com/nepalez/abstract_mapper)
+* Create your feature branch (`git checkout -b my-new-feature`)
+* Add tests for it
+* Commit your changes (`git commit -am '[UPDATE] Add some feature'`)
+* Push to the branch (`git push origin my-new-feature`)
+* Create a new Pull Request
+
+License
+-------
+
+See the [MIT LICENSE](LICENSE).

data/Rakefile

@@ -0,0 +1,34 @@
+# encoding: utf-8
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+  exit
+end
+
+# Loads bundler tasks
+Bundler::GemHelper.install_tasks
+
+# Loads the Hexx::RSpec and its tasks
+begin
+  require "hexx-suit"
+  Hexx::Suit.install_tasks
+rescue LoadError
+  require "hexx-rspec"
+  Hexx::RSpec.install_tasks
+end
+
+# Sets the Hexx::RSpec :test task to default
+task :default do
+  system "bundle exec rspec spec"
+end
+
+desc "Runs mutation metric before the first evil being kept"
+task :exhort do
+  system "mutant -r ./spec/spec_helper --use rspec AbstractMapper* --fail-fast"
+end
+
+desc "Runs mutation metric to view all evils"
+task :mutant do
+  system "mutant -r ./spec/spec_helper --use rspec AbstractMapper*"
+end

data/abstract_mapper.gemspec

@@ -0,0 +1,26 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "abstract_mapper/version"
+
+Gem::Specification.new do |gem|
+
+  gem.name        = "abstract_mapper"
+  gem.version     = AbstractMapper::VERSION.dup
+  gem.author      = "Andrew Kozin"
+  gem.email       = "andrew.kozin@gmail.com"
+  gem.homepage    = "https://github.com/nepalez/abstract_mapper"
+  gem.summary     = "AST for ruby mappers"
+  gem.description = "The abstract syntax tree for ruby mappers"
+  gem.license     = "MIT"
+
+  gem.files            = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  gem.test_files       = Dir["spec/**/*.rb"]
+  gem.extra_rdoc_files = Dir["README.md", "LICENSE"]
+  gem.require_paths    = ["lib"]
+
+  gem.required_ruby_version = ">= 2.1"
+
+  gem.add_runtime_dependency "transproc", "~> 0.2", "> 0.2.3"
+
+  gem.add_development_dependency "hexx-rspec", "~> 0.4"
+
+end # Gem::Specification

data/config/metrics/STYLEGUIDE

@@ -0,0 +1,230 @@
+= Ruby Style Guide
+
+Adapted from Dan Kubb's Ruby Style Guide
+https://github.com/dkubb/styleguide/blob/master/RUBY-STYLE
+
+== Commiting:
+
+* Write descriptive commit messages, following the pattern:
+
+    [TYPE] name
+
+    The message, describing the changes being made
+
+* Use the types below to mark commits:
+
+  - FEATURE - for adding new features, or backward-compatible changes;
+  - CHANGE - for backward-incompatible changes;
+  - BUG FIX - for fixing bugs;
+  - REFACTORING - for other changes of the code not affecting the API;
+  - OTHER - for changes in documentaton, metrics etc, not touching the code;
+  - VERSION - for version changes.
+
+* Always separate commits of different types (such as FEATURE and CHANGE).
+
+* Try to separate various features from each other.
+
+* Include specification to the same commit as the code.
+
+* Run all tests before making a commit.
+  Never commit the code that break unit tests.
+
+* Use metric (run `rake check`) before making a commit.
+
+* Do refactoring before making a commit. Best writing is rewriting.
+
+* Follow semantic versioning.
+
+    http://semver.org/
+
+* For versions name the commit after a version number, following the pattern:
+
+    VERSION 1.0.0-rc2
+
+
+== Formatting:
+
+* Use UTF-8. Declare encoding in the first line of every file.
+
+    # encoding: utf-8
+
+* Use 2 space indent, no tabs.
+
+* Use Unix-style line endings.
+
+* Use spaces around operators, after commas, colons and semicolons,
+  around { and before }.
+
+* No spaces after (, [ and before ], ).
+
+* Align `when` and `else` with `case`.
+
+* Use an empty line before the return value of a method (unless it
+  only has one line), and an empty line between defs.
+
+* Use empty lines to break up a long method into logical paragraphs.
+
+* Keep lines fewer than 80 characters.
+
+* Strip trailing whitespace.
+
+
+== Syntax:
+
+* Write for 2.0.
+
+* Use double quotes
+  
+    http://viget.com/extend/just-use-double-quoted-ruby-strings
+
+* Use def with parentheses when there are arguments.
+
+* Never use for, unless you exactly know why.
+
+* Never use then, except in case statements.
+
+* Use when x then ... for one-line cases.
+
+* Use &&/|| for boolean expressions, and/or for control flow. (Rule
+  of thumb: If you have to use outer parentheses, you are using the
+  wrong operators.)
+
+* Avoid double negation (!!), unless Null Objects are expected.
+  
+    http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness
+
+* Avoid multiline ?:, use if.
+
+* Use {...} when defining blocks on one line. Use do...end for multiline
+  blocks.
+
+* Avoid return where not required.
+
+* Use ||= freely.
+
+* Use OO regexps, and avoid =~ $0-9, $~, $` and $' when possible.
+
+* Do not use Enumerable#inject when the "memo" object does not change between
+  iterations, use Enumerable#each_with_object instead (in ruby 1.9,
+  active_support and backports).
+
+* Prefer ENV.fetch to ENV[] syntax.
+  Prefer block syntax for ENV.fetch to usage of the second argument.
+
+
+== Naming:
+
+* Use snake_case for methods.
+
+* Use CamelCase for classes and modules. (Keep acronyms like HTTP,
+  RFC, XML uppercase.)
+
+* Use SCREAMING_SNAKE_CASE for other constants.
+
+* Do not use single letter variable names. Avoid uncommunicative names.
+
+* Use consistent variable names. Try to keep the variable names close
+  to the object class name.
+
+* Use names prefixed with _ for unused variables.
+
+* When defining a predicate method that compares against another object of
+  a similar type, name the argument "other".
+
+* Prefer map over collect, detect over find, select over find_all.
+
+* Use def self.method to define singleton methods.
+
+* Avoid alias when alias_method will do.
+
+
+== Comments:
+
+* Use YARD and its conventions for API documentation. Don't put an
+  empty line between the comment block and the def.
+
+* Comments longer than a word are capitalized and use punctuation.
+  Use one space after periods.
+
+* Avoid superfluous comments.
+
+
+== Code structuring:
+
+* Break code into packages, decoupled from the environment.
+
+* Wrap packages into gems.
+
+* Inject dependencies explicitly.
+  Leave all outer references on the border of any package. Inside
+  the package use internal references only.
+
+* Follow SOLID principles.
+
+    http://en.wikipedia.org/wiki/SOLID_(object-oriented_design)
+
+* Only give a method one purpose for existing. If you pass in a boolean
+  to a method, what you're saying is that this method has two different
+  behaviours. Just split it into two single purpose methods. If you have
+  to use the words "AND" or "OR" to describe what the method does it
+  probably does too much.
+
+* Avoid long methods.
+  Try to keep them at no more than 6 lines long, and preferably 4 or less.
+
+  If sections of a method are logically separate by blank lines, then
+  that's probably a sign that those sections should be split into separate
+  methods.
+
+* Avoid hashes-as-optional-parameters. Does the method do too much?
+
+* Avoid long parameter lists.
+
+* Add "global" methods to Kernel (if you have to) and make them private.
+
+* Use OptionParser for parsing complex command line options and
+  ruby -s for trivial command line options.
+
+* Avoid needless metaprogramming.
+
+* Always freeze objects assigned to constants.
+
+
+== General:
+
+* Code in a functional way, avoid mutation when it makes sense.
+
+* Try to have methods either return the state of the object and have
+  no side effects, or return self and have side effects. This is
+  otherwise known as Command-query separation (CQS):
+
+    http://en.wikipedia.org/wiki/Command-query_separation
+
+* Do not mutate arguments unless that is the purpose of the method.
+
+* Try following TRUE heuristics by Sandi Metz
+
+    http://designisrefactoring.com/2015/02/08/introducing-sandi-metz-true/
+
+* Do not mess around in core classes when writing libraries.
+  Namespace your code inside the modules, or wrap core classes to
+  decorators of your own.
+
+* Do not program defensively.
+  
+    http://www.erlang.se/doc/programming_rules.shtml#HDR11
+
+* Keep the code simple.
+
+* Don't overdesign.
+
+* Don't underdesign.
+
+* Avoid bugs.
+
+* Read other style guides and apply the parts that don't dissent with
+  this list.
+
+* Be consistent.
+
+* Use common sense.

data/config/metrics/cane.yml

@@ -0,0 +1,5 @@
+---
+abc_max: "10"
+line_length: "80"
+no_doc: "y"
+no_readme: "y"

data/config/metrics/churn.yml

@@ -0,0 +1,6 @@
+---
+ignore_files:
+- spec
+- config
+minimum_churn_count: 0
+start_date: "1 year ago"

data/config/metrics/flay.yml

@@ -0,0 +1,2 @@
+---
+minimum_score: 9

data/config/metrics/metric_fu.yml

@@ -0,0 +1,15 @@
+---
+folders: # The list of folders to be used by any metric.
+- lib/abstract_mapper.rb
+- lib/abstract_mapper
+metrics: # The list of allowed metrics. The other metrics are disabled.
+- cane
+- churn
+- flay
+- flog
+- reek
+- roodi
+- saikuro
+format: html
+output: tmp/metric_fu
+verbose: false

data/config/metrics/reek.yml

@@ -0,0 +1 @@
+---