attr_extras 4.0.0 → 4.1.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    YTEzMGU2ZTk5YTFhZTRkOGRjN2NjMDNkYTU4MDM4NTVkNDExNmVkOQ==
-  data.tar.gz: !binary |-
-    MDZkNDRkNzc2MDMyOGUwMzVjODE1YmE5NGNkODNhMjY4YTM5NzZjYw==
+SHA1:
+  metadata.gz: 08a7329a2b945733d0baf670533dd8801c1880a9
+  data.tar.gz: 7f01ba7e4aadab65bb51ec5cdca127f97be8461e
 SHA512:
-  metadata.gz: !binary |-
-    MWNjNjMyYjQ3ZTMyMDE5MTQwYWIyY2NjYzQxMjJkNTNjNTQxOGZhMzY2NjAw
-    MmZkM2U3NzNiOTBjMWVmYzQyODA4MzBhMWU3ODIyYmZkNjFjODRhYTAzOTlm
-    MGY0NjEzYWIxZjU5MDhlNjRmNDkzYmZlMWVjMmY0ODQ5MWY0YWI=
-  data.tar.gz: !binary |-
-    MWNiMmYwMDI5MDYzZjBjYWY2OGFhNTMyZWIyZjJjZDkzNDRlOWUxY2Q3NzNm
-    ZWJhYWViN2I5NmU1ZWY1OWFhODQ3NGEwOTY1YmE3MGZjNWY5YTU0NTY5YWU2
-    ODgwNjZmOGE2MjQzZmQ0MzE5ZDY5OTYyMzhjNjVlODk2NzMyMGQ=
+  metadata.gz: c3df45d212321d6d1e1046c7439fc9825e047b8b1d769f2b5e2b453f028449dec6bd07034560f821b1e43f3cb6446a13ac5a18edbb1e2725e49c6d44b895863d
+  data.tar.gz: ba8800473f4c53b5b83118bd125fa4212728610f2a65475c92af65ef5611094810c343cdf20ab493b675adfd1b5f9cdbe10bfaaae600a7572c5416c546fc186e

data/README.md

@@ -6,7 +6,7 @@ Takes some boilerplate out of Ruby, lowering the barrier to extracting small foc
 
 Instead of
 
-```
+``` ruby
 class InvoiceBuilder
   def initialize(invoice, employee)
     @invoice, @employee = invoice, employee
@@ -20,7 +20,7 @@ end
 
 you can just do
 
-```
+``` ruby
 class InvoiceBuilder
   pattr_initialize :invoice, :employee
 end
@@ -35,102 +35,146 @@ Also provides conveniences for creating value objects, method objects, query met
 
 ## Usage
 
+* [`pattr_initialize`](#pattr_initialize)
+* [`vattr_initialize`](#vattr_initialize)
+* [`attr_initialize`](#attr_initialize)
+* [`attr_private`](#attr_private)
+* [`attr_value`](#attr_value)
+* [`static_facade`](#static_facade)
+* [`method_object`](#method_object)
+* [`attr_implement`](#attr_implement)
+* [`attr_query`](#attr_query)
+* [`attr_id_query`](#attr_id_query)
 
-### `attr_initialize :foo, :bar`
 
-Defines an initializer that takes two arguments and assigns `@foo` and `@bar`.
 
-`attr_initialize :foo, [:bar, :baz!]` defines an initializer that takes one regular argument, assigning `@foo`, and one hash argument, assigning `@bar` (optional) and `@baz` (required).
+### `pattr_initialize`
 
-`attr_initialize [:bar, :baz!]` defines an initializer that takes one hash argument, assigning `@bar` (optional) and `@baz` (required).
+`pattr_initialize :foo, :bar` defines both initializer and private readers: shortcut for
 
+``` ruby
+attr_initialize :foo, :bar
+attr_private :foo, :bar
+```
 
-`attr_initialize` can also accept a block which will be invoked after initialization. This is useful for calling `super` appropriately in subclasses or initializing private data as necessary.
+Example:
 
-### `attr_private :foo, :bar`
+``` ruby
+class Item
+  pattr_initalize :name, :price
 
-Defines private readers for `@foo` and `@bar`.
+  def price_with_vat
+    price * 1.25
+  end
+end
 
+Item.new("Pug", 100).price_with_vat  # => 125.0
+```
 
-### `attr_value :foo, :bar`
+[The `attr_initialize` notation](#attr_initialize) for hash arguments is also supported: `pattr_initialize :foo, [:bar, :baz!]`
 
-Defines public readers. Does not define writers, as [value objects](http://en.wikipedia.org/wiki/Value_object) are typically immutable.
 
-Defines object equality: two value objects of the same class with the same values are equal.
+### `vattr_initialize`
 
+`vattr_initialize :foo, :bar` defines initializer, public readers and [value object identity](#attr_value): shortcut for
 
-### `pattr_initialize :foo, :bar`
+``` ruby
+attr_initialize :foo, :bar
+attr_value :foo, :bar
+```
 
-Defines both initializer and private readers: shortcut for
+Example:
 
-```
-attr_initialize :foo, :bar
-attr_private :foo, :bar
+``` ruby
+class Country
+  vattr_initialize :code
+end
+
+Country.new("SE") == Country.new("SE")  # => true
+Country.new("SE").code  # => "SE"
 ```
 
-The `attr_initialize` notation for hash arguments is also supported: `pattr_initialize :foo, [:bar, :baz!]`
+[The `attr_initialize` notation](#attr_initialize) for hash arguments is also supported: `vattr_initialize :foo, [:bar, :baz!]`
 
 
-### `vattr_initialize :foo, :bar`
+### `attr_initialize`
 
-Defines initializer, public readers and value object identity: shortcut for
+`attr_initialize :foo, :bar` defines an initializer that takes two arguments and assigns `@foo` and `@bar`.
 
-```
-attr_initialize :foo, :bar
-attr_value :foo, :bar
-```
+`attr_initialize :foo, [:bar, :baz!]` defines an initializer that takes one regular argument, assigning `@foo`, and one hash argument, assigning `@bar` (optional) and `@baz` (required).
 
-The `attr_initialize` notation for hash arguments is also supported: `vattr_initialize :foo, [:bar, :baz!]`
+`attr_initialize [:bar, :baz!]` defines an initializer that takes one hash argument, assigning `@bar` (optional) and `@baz` (required).
 
+`attr_initialize` can also accept a block which will be invoked after initialization. This is useful for calling `super` appropriately in subclasses or initializing private data as necessary.
+
+
+### `attr_private`
+
+`attr_private :foo, :bar` defines private readers for `@foo` and `@bar`.
+
+
+### `attr_value`
+
+`attr_value :foo, :bar` defines public readers for `@foo` and `@bar` and also defines object equality: two value objects of the same class with the same values will be considered equal (with `==` and `eql?`, in `Set`s, as `Hash` keys etc).
+
+It does not define writers, because [value objects](http://en.wikipedia.org/wiki/Value_object) are typically immutable.
 
-### `static_facade :fooable?, :foo`<br>
 
-Defines a `.fooable?` class method that delegates to an instance method by the same name, having first provided `foo` as a private reader.
+### `static_facade`
+
+`static_facade :allow?, :user` defines an `.allow?` class method that delegates to an instance method by the same name, having first provided `user` as a private reader.
 
 This is handy when a class-method API makes sense but you still want [the refactorability of instance methods](http://blog.codeclimate.com/blog/2012/11/14/why-ruby-class-methods-resist-refactoring/).
 
+Example:
+
 ``` ruby
 class PublishingPolicy
   static_facade :allow?, :user
-  static_facade :disallow?, :user
 
   def allow?
-    user.admin? && …
+    user.admin? && complicated_extracted_method
   end
 
-  def disallow?
-    !allow?
+  private
+
+  def complicated_extracted_method
+    # …
   end
 end
 
 PublishingPolicy.allow?(user)
 ```
 
-`static_facade :fooable?, :foo` is a shortcut for
+`static_facade :allow?, :user` is a shortcut for
 
 ``` ruby
-pattr_initialize :foo
+pattr_initialize :user
 
-def self.fooable?(foo)
-  new(foo).fooable?
+def self.allow?(user)
+  new(user).allow?
 end
 ```
 
-The `attr_initialize` notation for hash arguments is also supported: `static_facade :fooable?, :foo, [:bar, :baz!]`
+[The `attr_initialize` notation](#attr_initialize) for hash arguments is also supported: `static_facade :allow?, :user, [:user_agent, :ip!]`
+
+You don't have to specify arguments/readers if you don't want them: just `static_facade :tuesday?` is also valid.
+
+"Static façade" is the least bad name for this pattern we've come up with. Suggestions are welcome.
 
-You don't have to specify arguments/readers if you don't want them: just `static_facade :fooable?` is also valid.
 
+### `method_object`
 
-### `method_object :foo`
+*NOTE: v4.0.0 made a breaking change! [`static_facade`](#static_facade) does exactly what `method_object` used to do; the new `method_object` no longer accepts a method name argument.*
 
-*NOTE: v4.0.0 made a breaking change! `static_facade` does exactly what `method_object` used to do; the new `method_object` no longer accepts a method name argument.*
+`method_object :foo` defines a `.call` class method that delegates to an instance method by the same name, having first provided `foo` as a private reader.
 
-Defines a `.call` class method that delegates to an instance method by the same name, having first provided `foo` as a private reader.
+This is a special case of [`static_facade`](#static_facade) for when you want a [Method Object](http://refactoring.com/catalog/replaceMethodWithMethodObject.html), and the class name itself will communicate the action it performs.
 
-This is a special case of `static_facade` for when you want a [Method Object](http://refactoring.com/catalog/replaceMethodWithMethodObject.html), and the class name itself will communicate the action it performs.
+Example:
 
 ``` ruby
-class PriceCalculator
+class CalculatePrice
   method_object :order
 
   def call
@@ -150,11 +194,13 @@ end
 
 class Order
   def price
-    PriceCalculator.call(self)
+    CalculatePrice.call(self)
   end
 end
 ```
 
+You could even do `CalculatePrice.(self)` if you like, since we're using the [`call` convention](http://www.ruby-doc.org/core-2.2.0/Proc.html#method-i-call).
+
 `method_object :foo` is a shortcut for
 
 ``` ruby
@@ -171,23 +217,14 @@ def self.call(foo)
 end
 ```
 
-The `attr_initialize` notation for hash arguments is also supported: `method_object :foo, [:bar, :baz!]`
+[The `attr_initialize` notation](#attr_initialize) for hash arguments is also supported: `method_object :foo, [:bar, :baz!]`
 
 You don't have to specify arguments/readers if you don't want them: just `method_object` is also valid.
 
 
-### `attr_id_query :foo?, :bar?`<br>
-
-Defines query methods like `foo?`, which is true if (and only if) `foo_id` is truthy. Goes well with Active Record.
-
-
-### `attr_query :foo?, :bar?`<br>
+### `attr_implement`
 
-Defines query methods like `foo?`, which is true if (and only if) `foo` is truthy.
-
-### `attr_implement :foo, :bar`<br>
-
-Defines nullary (0-argument) methods `foo` and `bar` that raise e.g. `"Implement a 'foo()' method"`.
+`attr_implement :foo, :bar` defines nullary (0-argument) methods `foo` and `bar` that raise e.g. `"Implement a 'foo()' method"`.
 
 `attr_implement :foo, [:name, :age]` will define a binary (2-argument) method `foo` that raises `"Implement a 'foo(name, age)' method"`.
 
@@ -204,6 +241,16 @@ end
 though it is shorter, more declarative, gives you a clear message and handles edge cases you might not have thought about (see tests).
 
 
+### `attr_query`
+
+`attr_query :foo?, :bar?` defines query methods like `foo?`, which is true if (and only if) `foo` is truthy.
+
+
+### `attr_id_query`
+
+`attr_id_query :foo?, :bar?` defines query methods like `foo?`, which is true if (and only if) `foo_id` is truthy. Goes well with Active Record.
+
+
 ## Philosophy
 
 Findability is a core value.
@@ -211,14 +258,15 @@ Hence the long name `attr_initialize`, so you see it when scanning for the initi
 and the enforced questionmarks with `attr_id_query :foo?`, so you can search for that method.
 
 
-## Why not use `Struct`?
+## Q & A
 
-See: ["Struct inheritance is overused"](http://thepugautomatic.com/2013/08/struct-inheritance-is-overused/)
 
+### Why not use `Struct` instead of `pattr_initialize`?
+
+See: ["Struct inheritance is overused"](http://thepugautomatic.com/2013/08/struct-inheritance-is-overused/)
 
-## Why not use `private; attr_reader :foo`?
 
-Instead of `attr_private :foo`, you could do `private; attr_reader :foo`.
+### Why not use `private; attr_reader :foo` instead of `attr_private :foo`?
 
 Other than being more to type, declaring `attr_reader` after `private` will actually give you a warning (deserved or not) if you run Ruby with warnings turned on.
 
@@ -242,7 +290,7 @@ Or install it yourself as:
 
 ## Running the tests
 
-Run then with:
+Run them with:
 
 `rake`
 

data/attr_extras.gemspec

@@ -15,10 +15,8 @@ Gem::Specification.new do |gem|
   gem.license       = "MIT"
   gem.version       = AttrExtras::VERSION
 
+  gem.add_development_dependency "minitest", ">= 5"
+
   # For Travis CI.
   gem.add_development_dependency "rake"
-
-  if RUBY_VERSION < "1.9.3"
-    gem.add_development_dependency "minitest"
-  end
 end

data/lib/attr_extras/attr_initialize.rb

@@ -15,7 +15,7 @@ class AttrExtras::AttrInitialize
     set_ivar_from_hash = method(:set_ivar_from_hash)
 
     klass.send(:define_method, :initialize) do |*values|
-      validate_arity.call(values.length)
+      validate_arity.call(values.length, self.class)
 
       names.zip(values).each do |name_or_names, value|
         if name_or_names.is_a?(Array)
@@ -38,13 +38,13 @@ class AttrExtras::AttrInitialize
 
   private
 
-  def validate_arity(provided_arity)
+  def validate_arity(provided_arity, klass)
     arity_without_hashes = names.count { |name| not name.is_a?(Array) }
     arity_with_hashes    = names.length
 
     unless (arity_without_hashes..arity_with_hashes).include?(provided_arity)
       arity_range = [ arity_without_hashes, arity_with_hashes ].uniq.join("..")
-      raise ArgumentError, "wrong number of arguments (#{provided_arity} for #{arity_range})"
+      raise ArgumentError, "wrong number of arguments (#{provided_arity} for #{arity_range}) for #{klass.name} initializer"
     end
   end
 

data/lib/attr_extras/version.rb

@@ -1,3 +1,3 @@
 module AttrExtras
-  VERSION = "4.0.0"
+  VERSION = "4.1.0"
 end

data/spec/attr_initialize_spec.rb

@@ -4,6 +4,10 @@ describe Object, ".attr_initialize" do
   let(:klass) do
     Class.new do
       attr_initialize :foo, :bar
+
+      def self.name
+        "ExampleClass"
+      end
     end
   end
 
@@ -14,7 +18,8 @@ describe Object, ".attr_initialize" do
   end
 
   it "requires all arguments" do
-    lambda { klass.new("Foo") }.must_raise ArgumentError
+    exception = lambda { klass.new("Foo") }.must_raise ArgumentError
+    exception.message.must_equal "wrong number of arguments (1 for 2) for ExampleClass initializer"
   end
 
   it "can set ivars from a hash" do
@@ -51,7 +56,7 @@ describe Object, ".attr_initialize" do
     lambda { klass.new(:optional => "X") }.must_raise KeyError
   end
 
-  it "can accept a block for initialization" do
+  it "accepts a block for initialization" do
     klass = Class.new do
       attr_initialize :value do
         @copy = @value

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: attr_extras
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Henrik Nyh
@@ -10,20 +10,34 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-16 00:00:00.000000000 Z
+date: 2015-02-09 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: 
@@ -33,9 +47,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rvmrc
-- .travis.yml
+- ".gitignore"
+- ".rvmrc"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -69,12 +83,12 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []