faceter 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2e033f423bf97c5a01e4a82d0d7cf4b7ed79a7fb
+  data.tar.gz: 1ba016d6090a2221a922dafe55e0149d91eca4f6
+SHA512:
+  metadata.gz: 325f69c325db01ebf36f74c563733d76d01f7cdf662c126a2132baa2fb55d1b1eeb5c7a7a61600e8a30be8b7d01c125c8eb97625a19b79d8b5888c1cda44a17b
+  data.tar.gz: 9e9586cdbdbfb53a59e61638408450bd662e70a491a679fadd1453a0a43485d798f3f4aeee4fd39b32447f203a4b35c3201d9390336678f8e39a8e8806717453

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,18 @@
+---
+language:     ruby
+cache:        bundler
+script:       "bundle exec rake test:coverage:run"
+bundler_args: --without metrics
+env:
+  global:
+    - JRUBY_OPTS='--dev -J-Xmx1024M'
+rvm:
+  - '2.1'
+  - '2.2'
+  - ruby-head
+  - rbx-2 --2.1
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/.yardopts

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

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## version 0.0.1 2015-08-06
+
+This is the first published version

data/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :metrics do
+  gem "hexx-suit", "~> 2.3" if RUBY_ENGINE == "ruby"
+end
+
+gem "thread_safe"

data/Guardfile

@@ -0,0 +1,10 @@
+# encoding: utf-8
+
+guard :rspec, cmd: "bundle exec rspec" do
+
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/faceter/(.+)\.rb$}) { |m| "spec/unit/#{m[1]}_spec.rb" }
+  watch("lib/faceter.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,295 @@
+Faceter
+=======
+
+[![Gem Version](https://img.shields.io/gem/v/faceter.svg?style=flat)][gem]
+[![Build Status](https://img.shields.io/travis/nepalez/faceter/master.svg?style=flat)][travis]
+[![Dependency Status](https://img.shields.io/gemnasium/nepalez/faceter.svg?style=flat)][gemnasium]
+[![Code Climate](https://img.shields.io/codeclimate/github/nepalez/faceter.svg?style=flat)][codeclimate]
+[![Coverage](https://img.shields.io/coveralls/nepalez/faceter.svg?style=flat)][coveralls]
+[![Inline docs](http://inch-ci.org/github/nepalez/faceter.svg)][inch]
+
+[codeclimate]: https://codeclimate.com/github/nepalez/faceter
+[coveralls]: https://coveralls.io/r/nepalez/faceter
+[gem]: https://rubygems.org/gems/faceter
+[gemnasium]: https://gemnasium.com/nepalez/faceter
+[travis]: https://travis-ci.org/nepalez/faceter
+[inch]: https://inch-ci.org/github/nepalez/faceter
+
+Experimental [ROM]-compatible data mapper, based on the [transproc] gem.
+
+No monkey-patching, no mutable instances of any class.
+
+100% [mutant]-covered.
+
+[ROM]: https://github.com/rom-rb/rom
+[transproc]: https://github.com/solnic/transproc
+[mutant]: https://github.com/mbj/mutant
+
+Motivation
+----------
+
+Basicaly the gem does about the same as the ROM mappers do. But its DSL has a different semantics:
+
+* Unlike ROM mappers, that describes the structure of transformed data with *nouns* (`attribute :foo, from: :bar`), the `Faceter` DSL uses *verbs* to describe transformations (`rename :bar, to: :foo`). `Faceter` transformations are either "do this, from: that", or "change this, to: that".
+
+* Unlike ROM, that mixes transformations (`attribute :bar, from: :foo`) with structures (wrap(:foo) { attribute :bar }), the `Faceter` strictly separates them. It uses 2 *nouns*: `list` an `field` (like `embedded` in ROM) to browse the data, and *verbs* to transform them. Only browsing can be nested and should end up with some transformation. Nested transformations are not supported.
+
+* Due to stronger separation between browsing an transforming data, every command in `Faceter` is executed as a single `step` in ROM. The output of every transformation serves the input for the next one. This makes it possible to read mapper DSL as a set of instructions: "go to this level and change data in this way, then go to that level etc.".
+
+* Because `Faceter` uses one-step transformations, it supports inline syntax for the transformations only. Blocks are used either to browse the data, or to provide value for the `create` command.
+
+* When you inherit a mapper, the subclass will do all the transformations from its superclass and then add its own. So the inheritance can be used to deepen transformation as an alternative to chaining mappers.
+
+The `Faceter` is the **experimental** gem. I've wrote it to check whether this "concept" of procedure-like syntax would work fine and not overkill the recipy with too much details.
+
+Synopsis
+--------
+
+To access the data the mapper DSL has two methods, that can be nested deeply:
+
+* `list` - "do something with every element of array"
+* `field` - "do something with a value of hash key"
+
+The mapper also has methods to transform the accessed data (either a field of some tuple or values of some array):
+
+* `rename` to rename fields in a tuple
+* `create` and `exclude` to provide a new field from other ones (while keeping those fields unchanged) or exclude the existing one(s).
+* `add_prefix` and `remove_prefix` to add/remove a prefix to names of field
+* `stringify_keys` and `symbolize_keys` to stringify/symbolize all keys from given layer and deeper
+* `wrap` and `unwrap` to wrap a value to nested tuple or unwrap it from a tuple
+* `group` and `ungroup` to group/ungroup tuples in array by some field(s)
+
+Suppose you need to transform array of nested data:
+
+```ruby
+source = [
+  {
+    id: 1, name: 'Joe', roles: ['admin'],
+    emails: [
+      { address: 'joe@doe.com', type: 'job' },
+      { address: 'joe@job.com', type: 'job' },
+      { address: 'joe@doe.org', type: 'personal' }
+    ]
+  }
+]
+```
+
+To create a mapper, include `Faceter` to the mapper class and define the sequence of transformations. Transformations will be applied step-by-step to data at a corresponding level.
+
+```ruby
+require "faceter"
+
+class Mapper
+  include Faceter
+
+  list do
+    field :roles do
+      list { fold to: :role }
+    end
+
+    rename :emails, to: :contacts
+  end
+
+  # Both `ungroup` and `group` work with arrays as a whole. You haven't
+  # wrap them to the `list` unless your data are not the arrays of arrays.
+  ungroup :role, from: :roles
+
+  group :id, :name, :contacts, to: :user
+
+  list do
+    field :user do
+      field :contacts do
+        list { rename :address, to: :email }
+        group :address, to: :emails
+      end
+    end
+  end
+end
+```
+
+To apply transformation to the source initialize the mapper and send the source array to its `call` instance method:
+
+```ruby
+mapper = Mapper.new
+mapper.call source
+# => [
+#      {
+#        role: 'admin',
+#        users: [
+#          {
+#            id: 1,
+#            name: 'Joe',
+#            contacts: [
+#              { type: 'job',      emails: ['joe@doe.com', 'joe@job.com'] },
+#              { type: 'personal', emails: ['joe@doe.org'] }
+#            ]
+#          }
+#        ]
+#      }
+#    ]
+```
+
+Instantiating Models
+--------------------
+
+You can do any data transformations using `create` method, that does the following:
+
+* takes values from tuple by keys given in `:from` option,
+* sends those values to the block in the same order,
+* assigns the result of the block either to given key, or rewrites the whole tuple with given value.
+
+```ruby
+require "faceter"
+require "ostruct"
+
+class Mapper
+  include Faceter
+
+  list do
+    create from: [:id, :name, :email] do |id, name, email|
+      OpenStruct.new id: id, name: name, email: email
+    end
+  end
+end
+```
+
+Alternatively, you could wrap the necessary keys and then create new value with the same key:
+
+```ruby
+require "faceter"
+require "ostruct"
+
+class Mapper
+  include Faceter
+
+  list do
+    wrap to: :user # wraps all keys in every tuple to the :user key
+
+    create from: :user do |user|
+      OpenStruct.new(user)
+    end
+  end
+end
+```
+
+Both the examples transform the array of tuples:
+
+```ruby
+source = [
+  { id: 1, name: "Joe",  email: "joe@doe.com"  },
+  { id: 2, name: "Jane", email: "jane@doe.com" }
+]
+```
+
+into the array of instances:
+
+```ruby
+mapper = Mapper.new
+mapper.call(source) 
+# => [
+#  #<OpenStruct @id=1, @name="Joe",  @email="joe@doe.com">,
+#  #<OpenStruct @id=2, @name="Jane", @email="jane@doe.com">
+# ]
+```
+
+### Data Serialization
+
+In just the same way you can serialize models at the mapper layer:
+
+```ruby
+source = [
+  OpenStruct.new(id: 1, name: "Joe", email: "joe@doe.com"),
+  OpenStruct.new(id: 2, name: "Jane", email: "jane@doe.com")
+]
+
+class Mapper < Faceter::Mapper
+  list do
+    # take every item in a list, create the value and assign it back to the item
+    create do |item|
+      { id: item.id, name: item.name, email: item.email }
+    end
+  end
+end
+
+mapper = Mapper.new
+mapper.call source
+# => [
+#      { id: 1, name: "Joe", email: "joe@doe.com" },
+#      { id: 2, name: "Jane", email: "jane@doe.com" }
+#    ]
+```
+
+### ROM-compatibility
+
+To use the mapper in [ROM] you can register it as a custom mapper for the corresponding relation:
+
+```ruby
+setup = ROM.setup :memory
+
+setup.relation(:users)
+setup.mappers { register(:users, my_mapper: mapper) }
+
+rom = ROM.finalize.env
+
+rom.relation(:users).as(:my_mapper).to_a
+# => returns the converted data
+```
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+```ruby
+# Gemfile
+gem "faceter"
+```
+
+Then execute:
+
+```
+bundle
+```
+
+Or add it manually:
+
+```
+gem install faceter
+```
+
+Compatibility
+-------------
+
+Tested under rubies [compatible to MRI 2.1+](.travis.yml).
+JRuby is supported from the head version only.
+
+Uses [RSpec] 3.0+ for testing and [hexx-suit] for dev/test tools collection.
+
+[RSpec]: http://rspec.org
+[hexx-suit]: https://github.com/nepalez/hexx-suit
+
+Contributing
+------------
+
+* Read the [STYLEGUIDE](config/metrics/STYLEGUIDE)
+* [Fork the project](https://github.com/nepalez/faceter)
+* 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
+
+Credits
+-------
+
+This project is heavily inspired by and based on gems written by [Piotr Solnica]:
+
+* [ROM] aka Ruby Object Mapper
+* [transproc] Functional-style transformations in Ruby
+
+[Piotr Solnica]: https://github.com/solnic
+
+License
+-------
+
+See the [MIT LICENSE](LICENSE).

data/Rakefile

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+require "rubygems"
+require "bundler/setup"
+
+# 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: "test:coverage:run"
+
+desc "Shows the first evil"
+task :mutant do
+  system "bundle exec mutant -r faceter --use rspec 'Faceter*' --fail-fast"
+end
+
+desc "Shows all evils"
+task :exhort do
+  system "bundle exec mutant -r faceter --use rspec 'Faceter*'"
+end
+
+desc "Runs all the necessary metrics before making a commit"
+task prepare: %w(exhort check:inch check:rubocop check:fu)
+
+desc "Compares faceter to rom mapper"
+task :benchmark do
+  system "ruby benchmark/run.rb"
+end