attestor 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 30d3fe02039b7df2f24461bd4eb4387deda2e93c
+  data.tar.gz: f1ec4731ded236180c094171dff71d10fad448db
+SHA512:
+  metadata.gz: 595eaa79f730fdf98e8119e5d98c30f0711278ada88dde24b87dc3ea770a8206fef0d0a2c899714504299b530f4eeb93898f1666fb2d61601e01954a76ed6436
+  data.tar.gz: 47078bc23acc2749312d84e9b343ae9236b300b099bafbb7a4554a5c4b34a7c0f7579716597ccdd736d7b3e05edc2956f7b8ad7d353cb226aafbe31e844933d2

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
+  false
+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,10 @@
+---
+language: ruby
+bundler_args: --without metrics
+script: rake test:coverage:run
+rvm:
+  - '2.0'
+  - ruby-head
+  - rbx-2 --2.0
+  - jruby-head-20mode
+  - jruby-head-21mode

data/.yardopts

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

data/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "hexx-suit", "~> 2.1", group: :metrics if RUBY_ENGINE == "ruby"

data/Guardfile

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+guard :rspec, cmd: "bundle exec rspec" do
+
+  watch(%r{^lib/attestor/(.+)\.rb$}) do |m|
+    "spec/tests/#{ m[1] }_spec.rb"
+  end
+
+  watch(%r{^spec/tests/.+_spec.rb})
+
+  watch("lib/*.rb")             { "spec" }
+  watch("spec/spec_helper.rb")  { "spec" }
+  watch("spec/support/**/*.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,308 @@
+Attestor
+=====
+
+Validations and policies for immutable Ruby objects
+
+[![Gem Version](https://img.shields.io/gem/v/attestor.svg?style=flat)][gem]
+[![Build Status](https://img.shields.io/travis/nepalez/attestor/master.svg?style=flat)][travis]
+[![Dependency Status](https://img.shields.io/gemnasium/nepalez/attestor.svg?style=flat)][gemnasium]
+[![Code Climate](https://img.shields.io/codeclimate/github/nepalez/attestor.svg?style=flat)][codeclimate]
+[![Coverage](https://img.shields.io/coveralls/nepalez/attestor.svg?style=flat)][coveralls]
+[![Inline docs](http://inch-ci.org/github/nepalez/attestor.svg)][inch]
+
+[codeclimate]: https://codeclimate.com/github/nepalez/attestor
+[coveralls]: https://coveralls.io/r/nepalez/attestor
+[gem]: https://rubygems.org/gems/attestor
+[gemnasium]: https://gemnasium.com/nepalez/attestor
+[travis]: https://travis-ci.org/nepalez/attestor
+[inch]: https://inch-ci.org/github/nepalez/attestor
+
+Motivation
+----------
+
+I like the [ActiveModel::Validations] more than any other part of the whole [Rails]. The more I like it the more painful the problem that **it mutates validated objects**.
+
+Every time you run validations, the collection of object's `#errors` is cleared and populated with new messages. So you can't validate frozen (immutable) objects without magic tricks.
+
+To solve the problem, the `attestor` gem:
+
+* Provides a simplest API for validating immutable objects.
+* Makes it possible to isolate validators (as [policy objects]) from their targets.
+* Allows policy objects to be composed by logical operations to provide complex policies.
+
+[ActiveModel::Validations]: http://apidock.com/rails/ActiveModel/Validations
+[Rails]: http://rubyonrails.org/
+[policy objects]: http://blog.codeclimate.com/blog/2012/10/17/7-ways-to-decompose-fat-activerecord-models/
+
+Approach
+--------
+
+Instead of collecting errors inside the object, the module's `validate` instance method just raises an exception (`Attestor::InvalidError`), that carries errors outside of the object. The object stays untouched (and can be made immutable).
+
+So to speak, validation just attests at the object and complains loudly when things goes wrong.
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+```ruby
+# Gemfile
+gem "attestor"
+```
+
+Then execute:
+
+```
+bundle
+```
+
+Or add it manually:
+
+```
+gem install attestor
+```
+
+Basic Use
+----------
+
+`Attestor::Validations` API consists of 1 class method `.validate` and 2 instance methods (`validate` and `invalid`).
+
+Declare validation in the same way as ActiveModel's `.validate` method does:
+
+```ruby
+class Transfer < Struct.new(:debet, :credit)
+  include Attestor::Validations
+
+  validate :consistent
+end
+```
+
+You have to define an instance validator method (that can be private):
+
+```ruby
+class Transfer < Struct.new(:debet, :credit)
+  # ...
+
+  private
+
+  def consistent
+    fraud = credit.sum - debet.sum
+    invalid :inconsistent, fraud: fraud if fraud != 0
+  end
+end
+```
+
+The `#invalid` method translates its argument in a current class scope and raises an exception.
+
+```ruby
+# config/locales/en.yml
+en:
+  attestor:
+    validations:
+      transfer:
+        inconsistent: "Credit differs from debet by %{fraud}"
+```
+
+To run validations use the `#validate` instance method:
+
+```ruby
+debet  = OpenStruct.new(sum: 100)
+credit = OpenStruct.new(sum: 90)
+fraud_transfer = Transfer.new(debet, credit)
+
+begin
+  transfer.validate
+rescue => error
+  error.object == transfer # => true
+  error.messages
+  # => ["Credit differs from debet by 10"]
+end
+```
+
+Adding Contexts
+---------------
+
+Sometimes you need to validate the object agaist the subset of validations, not all of them.
+
+To do this use `:except` and `:only` options of the `.validate` class method.
+
+```ruby
+class Transfer < Struct.new(:debet, :credit)
+  include Attestor::Validations
+
+  validate :consistent, except: :steal_of_money
+end
+```
+
+Then call a validate method with that context:
+
+```ruby
+fraud_transfer.validate                 # => InvalidError
+fraud_transfer.validate :steal_of_money # => PASSES!
+```
+
+Just as the `:except` option blacklists validations, the `:only` method whitelists them:
+
+```ruby
+class Transfer < Struct.new(:debet, :credit)
+  include Attestor::Validations
+
+  validate :consistent, only: :fair_trade
+end
+
+fraud_transfer.validate             # => PASSES
+fraud_transfer.validate :fair_trade # => InvalidError
+```
+
+Policy Objects
+--------------
+
+Extract a validator to the separate object (policy). Basically the policy includes `Attestor::Validations` with additional methods.
+
+```ruby
+class ConsistencyPolicy < Struct.new(:debet, :credit)
+  include Attestor::Policy
+
+  validate :consistent
+
+  private
+
+  def consistent
+    fraud = credit - debet
+    invalid :inconsistent, fraud: fraud if fraud != 0
+  end
+end
+```
+
+This looks mainly the same as before. But the policy's debet and credit are numbers, not the transactions. **The policy knows nothing about the nature of its attributes** - whether they are sums of transactions, or anything else.
+
+This is the core part of the [Policy Object design pattern] - it isolates the rule from unsignificant details of the target.
+
+From the other hand, the target needs to know nothing about how the policy works with data:
+
+```ruby
+class Transfer < Struct.new(:debet, :credit)
+  include Attestor::Validations
+
+  validate :constistent
+
+  private
+
+  def consistent
+    policy = ConsistencyPolicy.new(debet.sum, credit.sum)
+    invalid :inconsistent if policy.invalid?
+  end
+end
+```
+
+The "new" method `valid?` just returns true or false, trowing error messages out as unsignificant details.
+
+If you need messages from policy, you can use `validate` method and capture its exception. But should you?! Instead you'd better to provie the message, that makes sense in the Transfer context.
+
+[Policy Object design pattern]: http://blog.codeclimate.com/blog/2012/10/17/7-ways-to-decompose-fat-activerecord-models/
+
+Complex Policies
+----------------
+
+Now that we isolated policies, we can provide complex policies from simpler ones.
+
+Suppose we have two policy objects:
+
+```ruby
+valid_policy.valid?   # => true
+invalid_policy.valid? # => false
+```
+
+Use `Policy` factory methods to provide compositions:
+
+```ruby
+complex_policy = valid_policy.not
+complex_policy.validate # => fails
+
+complex_policy = valid_policy.and(valid_policy, invalid_policy)
+complex_policy.validate # => fails
+
+complex_policy = invalid_policy.or(invalid_policy, valid_policy)
+complex_policy.validate # => passes
+
+complex_policy = valid_policy.xor(valid_poicy, valid_policy)
+complex_policy.validate # => fails
+
+complex_policy = valid_policy.xor(valid_poicy, invalid_policy)
+complex_policy.validate # => passes
+```
+
+The `or`, `and` and `xor` methods, called without argument(s), don't provide a policy object. They return lazy composer, expecting `#not` method.
+
+```ruby
+complex_policy = valid_policy.and.not(invalid_policy, invalid_policy)
+# this is the same as:
+valid_policy.and(invalid_policy.not, invalid_policy.not)
+```
+
+If you prefer wrapping to chaining, use the `Policy` factory methods instead:
+
+```ruby
+Policy.and(valid_policy, invalid_policy)
+# this is the same as: valid_policy.and invalid_policy
+
+Policy.or(valid_policy, invalid_policy)
+# this is the same as: valid_policy.or invalid_policy
+
+Policy.xor(valid_policy, invalid_policy)
+# this is the same as: valid_policy.xor invalid_policy
+
+Policy.not(valid_policy)
+# this is the same as: valid_policy.not
+```
+
+As before, you can use any number of policies (except for negation of a single policy) at any number of nesting.
+
+This can be used either in targets or in complex policies. In the later case do it like this:
+
+```ruby
+class ComplexPolicy < Struct.new(:a, :b, :c)
+  include Attestor::Policy
+
+  validate :complex_rule
+
+  private
+
+  def complex_rule
+    first_policy  = FirstPolicy.new(a, b)
+    second_policy = SecondPolicy.new(b, c)
+
+    invalid :base unless first_policy.xor(second_policy).valid?
+  end
+end
+```
+
+Compatibility
+-------------
+
+Tested under rubies compatible to rubies with API 2.0+:
+
+* MRI 2.0+
+* Rubinius-2 (mode 2.0)
+* JRuby 9000+ (mode 2.0+)
+
+Uses [RSpec] 3.0+ for testing and [hexx-suit] for dev/test tools collection.
+
+Contributing
+------------
+
+* Fork the project.
+* Read the [STYLEGUIDE](config/metrics/STYLEGUIDE).
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with Rakefile or version
+  (if you want to have your own version, that is fine but bump version
+  in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+License
+-------
+
+See the [MIT LICENSE](LICENSE).

data/Rakefile

@@ -0,0 +1,22 @@
+# 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: "test:coverage:run"

data/attestor.gemspec

@@ -0,0 +1,24 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "attestor/version"
+
+Gem::Specification.new do |gem|
+
+  gem.name        = "attestor"
+  gem.version     = Attestor::VERSION.dup
+  gem.author      = "Andrew Kozin"
+  gem.email       = "andrew.kozin@gmail.com"
+  gem.homepage    = "https://github.com/nepalez/attestor"
+  gem.summary     = "Validations for immutable Ruby objects"
+  gem.description = gem.summary
+  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.0"
+  gem.add_runtime_dependency "extlib", "~> 0.9"
+  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"