attributes_dsl 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: da436a8b36ce35a3c4b4b87b33ed84a03a7dd910
+  data.tar.gz: 8d7edd3acf452eff9b4255a15a16cfee6f1d00d1
+SHA512:
+  metadata.gz: 63ea9addb5f796e1009f0140cc3523b4be461c280811d19b878edb3247ae5e1abe9f1cda60a05c703dfe7c28558bbf2868e2432c0b5957bce0d6ab15b0a8b408
+  data.tar.gz: e2555ba15ad33fbadbded4f29c0936687e23273ca534de57a9af3767a82f0a3372561d39c1145ec0031ca44f6afe4b0168d871173573c1b41b2f27ecc722fe74

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,20 @@
+---
+language:     ruby
+bundler_args: --without metrics --without benchmarks
+cache:        bundler
+script:       bundle exec rake test:coverage:run
+rvm:
+  - '1.9.3'
+  - '2.0'
+  - '2.1'
+  - '2.2'
+  - ruby-head
+  - rbx-2 --1.9
+  - rbx-2 --2.1
+  - jruby-1.7-19mode
+  - jruby-9.0.0.0
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/.yardopts

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

data/CHANGELOG.md

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

data/Gemfile

@@ -0,0 +1,16 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :metrics do
+  gem "hexx-suit", "~> 2.3" if RUBY_ENGINE == "ruby" && RUBY_VERSION >= "2.1"
+end
+
+group :benchmarks do
+  gem "virtus"
+  gem "benchmark-ips"
+  gem "active_attr"
+  gem "fast_attributes"
+  gem "anima"
+  gem "kwattr"
+end

data/Guardfile

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+guard :rspec, cmd: "bundle exec rspec" do
+
+  watch(%r{^spec/.+_spec\.rb$})
+
+  watch(%r{^lib/attributes_dsl/(.+)\.rb}) do |m|
+    "spec/unit/#{m[1]}_spec.rb"
+  end
+
+  watch("lib/attributes_dsl.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,209 @@
+Attributes DSL
+==============
+
+[![Gem Version](https://img.shields.io/gem/v/attributes_dsl.svg?style=flat)][gem]
+[![Build Status](https://img.shields.io/travis/nepalez/attributes_dsl/master.svg?style=flat)][travis]
+[![Dependency Status](https://img.shields.io/gemnasium/nepalez/attributes_dsl.svg?style=flat)][gemnasium]
+[![Code Climate](https://img.shields.io/codeclimate/github/nepalez/attributes_dsl.svg?style=flat)][codeclimate]
+[![Coverage](https://img.shields.io/coveralls/nepalez/attributes_dsl.svg?style=flat)][coveralls]
+[![Inline docs](http://inch-ci.org/github/nepalez/attributes_dsl.svg)][inch]
+
+Lightweight DSL to define PORO attributes.
+
+Uses immutable (deeply frozen) instances via [ice_nine][ice_nine] gem.
+
+Synopsis
+--------
+
+```ruby
+require "attributes_dsl"
+
+class User
+  extend AttributesDSL
+
+  # `name` is required should be symbolized
+  attribute :name, required: true do |value|
+    value.to_s.to_sym
+  end
+
+  # `sex` is optional and set to `:male` by default.
+  # It can be set to either :male or :female
+  attribute :sex, default: :male do |value|
+    (value == :male )? :male : :female
+  end
+
+  # `age` is optional and set to `nil` by default.
+  # Then it is converted to integer
+  attribute :age, &:to_i
+
+  # `position` is optional and set to `nil` by default
+  attribute :position
+
+  # All other attributes are ignored
+end
+
+user = User.new(name: "Jane", sex: :women, age: "26", place: "Moscow")
+user.attributes
+# => { name: :Jane, sex: :female, age: 26, position: nil }
+
+# Aliases for attributes[:some_attribute]
+user.name     # => :Jane
+user.sex      # => :female
+user.age      # => 26
+user.position # => nil
+
+# Required attributes should be assigned:
+user = User.new(sex: :women, age: "26", place: "Moscow")
+# => #<ArgumentError "Undefined attributes: name">
+```
+
+Additional Details
+------------------
+
+The `attribute` class method takes the `name` and 2 options:
+- `:default` for the default value (otherwise `nil`);
+- `:required` to declare the attribute as required. It will be ignored if a default value is provided!
+
+It is also takes the block, used to coerce a value. The coercer is applied to the default value too.
+
+Also notice, that instance methods (like `#name`) are just aliases for the corresponding value of the `#attributes` hash. Instance variables aren't defined for them (to ensure syncronization between `#name` and `#attributes[:name]`):
+
+```ruby
+user = User.new(name: "John")
+user.attributes # => { name: :John, sex: :male, age: 0, position: nil }
+user.name # => :John
+
+# but
+user.instance_variable_get :@name # => nil
+```
+
+You're free to redefine attributes (class settings are used by the initializer only):
+
+```ruby
+user.attributes[:name] = "Jim"
+user.attributes # => { name: "Jim", sex: :male, age: 0, position: nil }
+user.name # => "Jim"
+```
+
+But if you (like me) prefer instance immutability, you can deeply freeze instances safely:
+
+```ruby
+require "ice_nine"
+
+class User
+  # ... staff like before
+
+  def initializer(attributes)
+    super
+    IceNine.deep_freeze(self)
+  end
+end
+
+args = { user: "Joe" }
+
+user = User.new(args)
+user.frozen?            # => true
+user.attributes.frozen? # => true
+
+# "Safely" means:
+args.frozen? # => false
+```
+
+Freezing instances to exclude side effects is a part of my coding style. That's why the gem doesn't (and won't do) care about changing attributes after initialization.
+
+Benchmarks
+----------
+
+The list of gems to compare has been taken from [Idiosyncratic Ruby #18][idiosyncratic_ruby] by Jan Lelis. I've selected only those gems that support initialization from hash.
+
+Look at the [benchmark source][benchmark] for details.
+
+The results are following:
+
+```
+-------------------------------------------------
+               anima    202.863k (± 5.1%) i/s -      1.023M
+              kwattr    171.461k (± 5.3%) i/s -    855.680k
+     fast_attributes    156.596k (± 2.5%) i/s -    785.792k
+      attributes_dsl     58.966k (± 4.6%) i/s -    296.514k
+         active_attr     58.322k (± 2.8%) i/s -    293.205k
+              virtus     45.734k (± 2.7%) i/s -    228.960k
+
+Comparison:
+               anima:   202862.9 i/s
+              kwattr:   171460.9 i/s - 1.18x slower
+     fast_attributes:   156596.3 i/s - 1.30x slower
+      attributes_dsl:    58966.5 i/s - 3.44x slower
+         active_attr:    58321.6 i/s - 3.48x slower
+              virtus:    45734.3 i/s - 4.44x slower
+```
+
+Results above are pretty reasonable.
+
+The gem is faster than `virtus` that has many additional features.
+
+It is as fast as `active_attrs` (but has more customizable coercers).
+
+It is 2 times slower than `fast_attributes` that has no coercer and default values. And it is 3-3.5 times slower than `anima` and `kwattr` that provides only the base settings.
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+```ruby
+# Gemfile
+gem "attributes_dsl"
+```
+
+Then execute:
+
+```
+bundle
+```
+
+Or add it manually:
+
+```
+gem install attributes_dsl
+```
+
+Compatibility
+-------------
+
+Tested under rubies [compatible to MRI 1.9+][versions].
+
+Uses [RSpec][rspec] 3.0+ for testing and [hexx-suit][hexx-suit] for dev/test tools collection.
+
+100% [mutant]-proof covered.
+
+Contributing
+------------
+
+* Read the [STYLEGUIDE](config/metrics/STYLEGUIDE)
+* [Fork the project](https://github.com/nepalez/attributes_dsl)
+* Create your feature branch (`git checkout -b my-new-feature`)
+* Add tests for it
+* Run `rake mutant` or `rake exhort` to ensure 100% [mutant][mutant] coverage
+* 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).
+
+[codeclimate]: https://codeclimate.com/github/nepalez/attributes_dsl
+[coveralls]: https://coveralls.io/r/nepalez/attributes_dsl
+[gem]: https://rubygems.org/gems/attributes_dsl
+[gemnasium]: https://gemnasium.com/nepalez/attributes_dsl
+[travis]: https://travis-ci.org/nepalez/attributes_dsl
+[inch]: https://inch-ci.org/github/nepalez/attributes_dsl
+[versions]: .travis.yml
+[rspec]: http://rspec.org
+[hexx-suit]: https://github.com/hexx-rb/hexx-suit
+[mutant]: https://github.com/mbj/mutant
+[ice_nine]: https://github.com/dkubb/ice_nine
+[idiosyncratic_ruby]: http://idiosyncratic-ruby.com/18-con-struct-attributes.html
+[benchmark]: benchmark/run.rb

data/Rakefile

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+require "bundler/setup"
+require "rubygems"
+
+# 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
+
+desc "Sets the Hexx::RSpec :test task to default"
+task :default do
+  system "bundle exec rake test:coverage:run"
+end
+
+desc "Runs mutation metric for testing"
+task :mutant do
+  system "mutant -r ./spec/spec_helper --use rspec AttributesDSL* --fail-fast"
+end
+
+desc "Exhort all evils"
+task :exhort do
+  system "mutant -r ./spec/spec_helper --use rspec AttributesDSL*"
+end
+
+desc "Runs all the necessary metrics before making a commit"
+task prepare: %w(exhort check:inch check:rubocop check:fu)
+
+desc "Runs benchmarks"
+task :benchmark do
+  system "ruby benchmark/run.rb"
+end

data/attributes_dsl.gemspec

@@ -0,0 +1,26 @@
+$LOAD_PATH.push File.expand_path("../lib", __FILE__)
+require "attributes_dsl/version"
+
+Gem::Specification.new do |gem|
+
+  gem.name        = "attributes_dsl"
+  gem.version     = AttributesDSL::VERSION.dup
+  gem.author      = "Andrew Kozin"
+  gem.email       = "andrew.kozin@gmail.com"
+  gem.homepage    = "https://github.com/nepalez/attributes_dsl"
+  gem.summary     = "Lightweight DSL to define PORO attributes"
+  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 = ">= 1.9.3"
+
+  gem.add_runtime_dependency "ice_nine", "~> 0.11"
+  gem.add_runtime_dependency "equalizer", "~> 0.0", ">= 0.0.11"
+
+  gem.add_development_dependency "hexx-rspec", "~> 0.5", ">= 0.5.2"
+
+end # Gem::Specification

data/benchmark/run.rb

@@ -0,0 +1,122 @@
+require "benchmark/ips"
+
+module AttributesDSLExample
+  require "attributes_dsl"
+
+  class User
+    extend AttributesDSL
+
+    attribute :foo, required: true, &:to_s
+    attribute :bar, default: :BAR, &:to_s
+    attribute :baz, default: :BAZ, &:to_s
+    attribute :qux, &:to_s
+  end
+
+  def self.call
+    User.new(foo: :FOO, bar: :BAR, baz: :BAZ, qux: :QUX)
+  end
+end
+
+module VirtusExample
+  require "virtus"
+
+  class User
+    include Virtus.model
+
+    attribute :foo, String, required: true
+    attribute :bar, String, default: :BAR
+    attribute :baz, String, default: :BAZ
+    attribute :qux, String
+  end
+
+  def self.call
+    User.new(foo: :FOO, bar: :BAR, baz: :BAZ, qux: :QUX)
+  end
+end
+
+module ActiveAttrExample
+  require "active_attr"
+
+  class User
+    include ActiveAttr::MassAssignment
+    attr_accessor :foo, :bar, :baz, :qux
+  end
+
+  def self.call
+    User.new(foo: :FOO, bar: :BAR, baz: :BAZ, qux: :QUX)
+  end
+end
+
+module FastAttributesExample
+  require "fast_attributes"
+
+  class User
+    extend FastAttributes
+
+    define_attributes initialize: true do
+      attribute :foo, String
+      attribute :bar, String
+      attribute :baz, String
+      attribute :qux, String
+    end
+  end
+
+  def self.call
+    User.new(foo: :FOO, bar: :BAR, baz: :BAZ, qux: :QUX)
+  end
+end
+
+module AnimaExample
+  require "anima"
+
+  class User
+    include Anima.new(:foo, :bar, :baz, :qux)
+  end
+
+  def self.call
+    User.new(foo: :FOO, bar: :BAR, baz: :BAZ, qux: :QUX)
+  end
+end
+
+module KwattrExample
+  require "kwattr"
+
+  class User
+    kwattr :foo, :bar, :baz, :qux
+  end
+
+  def self.call
+    User.new(foo: :FOO, bar: :BAR, baz: :BAZ, qux: :QUX)
+  end
+end
+
+# Provide a benchmark
+Benchmark.ips do |x|
+  x.config time: 5, warmup: 5
+
+  x.report("attributes_dsl") do
+    AttributesDSLExample.call
+  end
+
+  x.report("virtus") do
+    VirtusExample.call
+  end
+
+  x.report("active_attr") do
+    AttributesDSLExample.call
+  end
+
+  x.report("fast_attributes") do
+    FastAttributesExample.call
+  end
+
+  x.report("anima") do
+    AnimaExample.call
+  end
+
+  x.report("kwattr") do
+    KwattrExample.call
+  end
+
+  x.compare!
+end