value_semantics 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e86c0e4467ff36d89870545718de723b0a0b62ff21dc50d30a3f6e1c0766c4c1
-  data.tar.gz: '011313548dfe90ee7b686bc91338b5e0f403ce2dd26f98fd607fdf16ef2c5ce7'
+  metadata.gz: '069ef7cc15f7d9b6eae3af432d486595bfa3f89c0f68ce68ab3eda2fb5d5f9f4'
+  data.tar.gz: f8d1839f7176743cb9d7a144d5452f999048a03a5d1d86d8b86b81b648a7bfd3
 SHA512:
-  metadata.gz: ecd428749dd01e806df9bbd4a361084f1b066298d464fea3a04ff7f66214ba224b99b93c7902f513c1c4f89fc52690779f4a14bb2c7e78106a212456a8f2c14d
-  data.tar.gz: 86c31d6565594493891581dde7feac4f9a9a5c1ff39b86874fd1be74d6bf3827b9a3311369dcaf9a76d9c41ca03be9abc464736ac86d09d316125e9472534554
+  metadata.gz: cea465484d60d6343815072b4e81639e399b20ce528a12ce643be39e3a06051fdaddb4c58037ffac5237f7c62b823b49d888bc8d6fed925b181515751b4cfb46
+  data.tar.gz: 553a990a508956e7a2b6f96ea2ac65ee97737bc6ea5da1ea337f9d0d06b294aa61fb3e10ef1d8ce6ac5fff826b3f1bdbf17b9e805ac38b933308152929335efd

data/CHANGELOG.md

@@ -5,6 +5,13 @@ Notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.5.0] - 2020-08-17
+### Added
+- Square bracket attr reader like `person[:name]`
+- `HashOf` built-in validator, similar to `ArrayOf`
+- `.coercer` class method, to help when composing value objects
+- `ArrayCoercer` DSL method, to help when composing value objects
+
 ## [3.4.0] - 2020-08-01
 ### Added
 - Value objects can be instantiated from any object that responds to `#to_h`.

data/README.md

@@ -19,6 +19,7 @@ See:
 
  - The [announcement blog post][blog post] for some of the rationale behind the gem
  - [RubyTapas episode #584][rubytapas] for an example usage scenario
+ - The [API documentation](https://rubydoc.info/gems/value_semantics)
  - Some [discussion on Reddit][reddit]
 
 [blog post]: https://www.rubypigeon.com/posts/value-semantics-gem-for-making-value-classes/
@@ -49,7 +50,7 @@ Person.new(name: "Tom", birthday: "2020-12-25")
 #=> #<Person name="Tom" birthday=#<Date: 2020-12-25 ((2459209j,0s,0n),+0s,2299161j)>>
 
 Person.new(birthday: Date.today)
-#=> #<Person name="Anon Emous" birthday=#<Date: 2018-09-04 ((2458366j,0s,0n),+0s,2299161j)>>
+#=> #<Person name="Anon Emous" birthday=#<Date: 2020-08-04 ((2459066j,0s,0n),+0s,2299161j)>>
 
 Person.new(birthday: nil)
 #=> #<Person name="Anon Emous" birthday=nil>
@@ -81,19 +82,15 @@ tom = Person.new(name: 'Tom')
 
 
 # Read-only attributes
-tom.name  #=> "Tom"
-tom.age  #=> 31
-
+tom.name    #=> "Tom"
+tom[:name]  #=> "Tom"
 
 # Convert to Hash
-tom.to_h  #=> { :name => "Tom", :age => 31 }
-
+tom.to_h  #=> {:name=>"Tom", :age=>31}
 
 # Non-destructive updates
-old_tom = tom.with(age: 99)
-old_tom  #=> #<Person name="Tom" age=99>
-tom      #=> #<Person name="Tom" age=31> (unchanged)
-
+tom.with(age: 99) #=> #<Person name="Tom" age=99>
+tom # (unchanged) #=> #<Person name="Tom" age=31>
 
 # Equality
 other_tom = Person.new(name: 'Tom', age: 31)
@@ -101,12 +98,12 @@ tom == other_tom  #=> true
 tom.eql?(other_tom)  #=> true
 tom.hash == other_tom.hash  #=> true
 
-
 # Ruby 2.7+ pattern matching
 case tom
 in name: "Tom", age:
-  puts age  # outputs: 31
+  puts age
 end
+# outputs: 31
 ```
 
 
@@ -116,7 +113,9 @@ Convenience (Monkey Patch)
 There is a shorter way to define value attributes:
 
 ```ruby
-  class Person
+  require 'value_semantics/monkey_patched'
+
+  class Monkey
     value_semantics do
       name String
       age Integer
@@ -160,7 +159,7 @@ class Cat
 end
 
 Cat.new
-#=> #<Cat paws=4 born_at=2018-12-21 18:42:01 +1100>
+#=> #<Cat paws=4 born_at=2020-08-04 00:16:35.15632 +1000>
 ```
 
 The `default` option is a single value.
@@ -189,15 +188,13 @@ class Person
   }
 end
 
-Person.new(name: 'Tom', ...)  # works
-Person.new(name: 5, ...)
-#=> ValueSemantics::InvalidValue:
-#=>     Attribute `Person#name` is invalid: 5
+Person.new(name: 'Tom', birthday: '2000-01-01')  # works
+Person.new(name: 5,     birthday: '2000-01-01')
+#=> !!! ValueSemantics::InvalidValue: Attribute `Person#name` is invalid: 5
 
-Person.new(birthday: "1970-01-01", ...)  # works
-Person.new(birthday: "hello", ...)
-#=> ValueSemantics::InvalidValue:
-#=>     Attribute 'Person#birthday' is invalid: "hello"
+Person.new(name: 'Tom', birthday: "1970-01-01")  # works
+Person.new(name: 'Tom', birthday: "hello")
+#=> !!! ValueSemantics::InvalidValue: Attribute `Person#birthday` is invalid: "hello"
 ```
 
 
@@ -209,13 +206,15 @@ for common situations:
 ```ruby
 class LightSwitch
   include ValueSemantics.for_attributes {
-
     # Bool: only allows `true` or `false`
     on? Bool()
 
     # ArrayOf: validates elements in an array
     light_ids ArrayOf(Integer)
 
+    # HashOf: validates keys/values of a homogeneous hash
+    toggle_stats HashOf(Symbol => Integer)
+
     # Either: value must match at least one of a list of validators
     color Either(Integer, String, nil)
 
@@ -227,9 +226,11 @@ end
 LightSwitch.new(
   on?: true,
   light_ids: [11, 12, 13],
+  toggle_stats: { day: 42, night: 69 },
   color: "#FFAABB",
   wierd_attr: [true, false, true, true],
 )
+#=> #<LightSwitch on?=true light_ids=[11, 12, 13] toggle_stats={:day=>42, :night=>69} color="#FFAABB" wierd_attr=[true, false, true, true]>
 ```
 
 
@@ -238,22 +239,25 @@ LightSwitch.new(
 A custom validator might look something like this:
 
 ```ruby
-module Odd
+module DottedQuad
   def self.===(value)
-    value.odd?
+    value.split('.').all? do |part|
+      ('0'..'255').cover?(part)
+    end
   end
 end
 
-class Person
+class Server
   include ValueSemantics.for_attributes {
-    age Odd
+    address DottedQuad
   }
 end
 
-Person.new(age: 9)  # works
-Person.new(age: 8)
-#=> ValueSemantics::InvalidValue:
-#=>     Attribute 'Person#age' is invalid: 8
+Server.new(address: '127.0.0.1')
+#=> #<Server address="127.0.0.1">
+
+Server.new(address: '127.0.0.999')
+#=> !!! ValueSemantics::InvalidValue: Attribute `Server#address` is invalid: "127.0.0.999"
 ```
 
 Default attribute values also pass through validation.
@@ -296,8 +300,7 @@ Document.new(path: Pathname.new('~/Documents/whatever.doc'))
 #=> #<Document path=#<Pathname:~/Documents/whatever.doc>>
 
 Document.new(path: 42)
-#=> ValueSemantics::InvalidValue:
-#=>     Attribute 'Document#path' is invalid: 42
+#=> !!! ValueSemantics::InvalidValue: Attribute `Document#path` is invalid: 42
 ```
 
 You can also use any callable object as a coercer.
@@ -347,6 +350,50 @@ For example, the default value could be a string,
 which would then be coerced into an `Pathname` object.
 
 
+## Nesting
+
+It is fairly common to nest value objects inside each other. This
+works as expected, but coercion is not automatic. For nested coercion,
+use the `.coercer` class method and `ArrayCoercer` DSL method that
+ValueSemantics provides.
+
+```ruby
+class CrabClaw
+  include ValueSemantics.for_attributes {
+    size Either(:big, :small)
+  }
+end
+
+class Crab
+  include ValueSemantics.for_attributes {
+    left_claw CrabClaw, coerce: CrabClaw.coercer
+    right_claw CrabClaw, coerce: CrabClaw.coercer
+  }
+end
+
+class Ocean
+  include ValueSemantics.for_attributes {
+    crabs ArrayOf(Crab), coerce: ArrayCoercer(Crab.coercer)
+  }
+end
+
+ocean = Ocean.new(
+  crabs: [
+    {
+      left_claw: { size: :small },
+      right_claw: { size: :small },
+    }, {
+      left_claw: { size: :big },
+      right_claw: { size: :big },
+    }
+  ]
+)
+
+ocean.crabs.first #=> #<Crab left_claw=#<CrabClaw size=:small> right_claw=#<CrabClaw size=:small>>
+ocean.crabs.first.right_claw.size #=> :small
+```
+
+
 ## ValueSemantics::Struct
 
 This is a convenience for making a new class and including ValueSemantics in
@@ -354,11 +401,41 @@ one step, similar to how `Struct` works from the Ruby standard library. For
 example:
 
 ```ruby
-Cat = ValueSemantics::Struct.new do
-  name String, default: "Mittens"
+Pigeon = ValueSemantics::Struct.new do
+  name String, default: "Jannie"
+end
+
+Pigeon.new.name #=> "Jannie"
+```
+
+
+## Known Issues
+
+Some valid attribute names result in invalid Ruby syntax when using the DSL.
+In these situations, you can use the DSL method `def_attr` instead.
+
+For example, if you want an attribute named `then`:
+
+```ruby
+# Can't do this:
+class Conditional
+  include ValueSemantics.for_attributes {
+    then String
+    else String
+  }
 end
+#=> !!! SyntaxError: README.md:375: syntax error, unexpected `then'
+#=*         then String
+#=*         ^~~~
+
 
-Cat.new.name #=> "Mittens"
+# This will work
+class Conditional
+  include ValueSemantics.for_attributes {
+    def_attr :then, String
+    def_attr :else, String
+  }
+end
 ```
 
 

data/lib/value_semantics.rb

@@ -45,10 +45,9 @@ module ValueSemantics
   end
 
   #
-  # Makes the `.value_semantics` convenience method available to all classes
+  # Makes the +.value_semantics+ convenience method available to all classes
   #
-  # `.value_semantics` is a shortcut for `include ValueSemantics.for_attributes`.
-  # Instead of:
+  # +.value_semantics+ is a shortcut for {.for_attributes}. Instead of:
   #
   #     class Person
   #       include ValueSemantics.for_attributes {
@@ -64,7 +63,7 @@ module ValueSemantics
   #       end
   #     end
   #
-  # Alternatively, you can `require 'value_semantics/monkey_patched'`, which
+  # Alternatively, you can +require 'value_semantics/monkey_patched'+, which
   # will call this method automatically.
   #
   def self.monkey_patch!
@@ -96,6 +95,26 @@ module ValueSemantics
 
       self::VALUE_SEMANTICS_RECIPE__
     end
+
+    #
+    # A coercer object for the value class
+    #
+    # This is mostly useful when nesting value objects inside each other.
+    #
+    # The coercer will coerce hashes into an instance of the value class, using
+    # the hash for attribute values. It will return non-hash values unchanged.
+    #
+    # @return [#call] A callable object that can be used as a coercer
+    #
+    def coercer
+      ->(obj) do
+        if Hash === obj
+          new(obj)
+        else
+          obj
+        end
+      end
+    end
   end
 
   #
@@ -106,14 +125,14 @@ module ValueSemantics
     # Creates a value object based on a hash of attributes
     #
     # @param attributes [#to_h] A hash of attribute values by name. Typically a
-    #   `Hash`, but can be any object that responds to `#to_h`.
+    #   +Hash+, but can be any object that responds to +#to_h+.
     #
     # @raise [UnrecognizedAttributes] if given_attrs contains keys that are not
     #   attributes
     # @raise [MissingAttributes] if given_attrs is missing any attributes that
     #   do not have defaults
     # @raise [InvalidValue] if any attribute values do no pass their validators
-    # @raise [TypeError] if the argument does not respond to `#to_h`
+    # @raise [TypeError] if the argument does not respond to +#to_h+
     #
     def initialize(attributes = nil)
       attributes_hash =
@@ -147,6 +166,26 @@ module ValueSemantics
       end
     end
 
+    #
+    # Returns the value for the given attribute name
+    #
+    # @param attr_name [Symbol] The name of the attribute. Can not be a +String+.
+    # @return The value of the attribute
+    #
+    # @raise [UnrecognizedAttributes] if the attribute does not exist
+    #
+    def [](attr_name)
+      attr = self.class.value_semantics.attributes.find do |attr|
+        attr.name.equal?(attr_name)
+      end
+
+      if attr
+        public_send(attr_name)
+      else
+        raise UnrecognizedAttributes, "`#{self.class}` has no attribute named `#{attr_name.inspect}`"
+      end
+    end
+
     #
     # Creates a copy of this object, with the given attributes changed (non-destructive update)
     #
@@ -307,6 +346,8 @@ module ValueSemantics
   # Contains all the configuration necessary to bake a ValueSemantics module
   #
   # @see ValueSemantics.bake_module
+  # @see ClassMethods#value_semantics
+  # @see DSL.run
   #
   class Recipe
     attr_reader :attributes
@@ -359,6 +400,41 @@ module ValueSemantics
       ArrayOf.new(element_validator)
     end
 
+    def HashOf(key_validator_to_value_validator)
+      unless key_validator_to_value_validator.size.equal?(1)
+        raise ArgumentError, "HashOf() takes a hash with one key and one value"
+      end
+
+      HashOf.new(
+        key_validator_to_value_validator.keys.first,
+        key_validator_to_value_validator.values.first,
+      )
+    end
+
+    def ArrayCoercer(element_coercer)
+      ArrayCoercer.new(element_coercer)
+    end
+
+    #
+    # Defines one attribute.
+    #
+    # This is the method that gets called under the hood, when defining
+    # attributes the typical +#method_missing+ way.
+    #
+    # You can use this method directly if your attribute name results in invalid
+    # Ruby syntax. For example, if you want an attribute named +then+, you
+    # can do:
+    #
+    #     include ValueSemantics.for_attributes {
+    #       # Does not work:
+    #       then String, default: "whatever"
+    #       #=> SyntaxError: syntax error, unexpected `then'
+    #
+    #       # Works:
+    #       def_attr :then, String, default: "whatever"
+    #     }
+    #
+    #
     def def_attr(*args, **kwargs)
       __attributes << Attribute.define(*args, **kwargs)
     end
@@ -431,6 +507,47 @@ module ValueSemantics
     end
   end
 
+  #
+  # Validator that matches +Hash+es with homogeneous keys and values
+  #
+  class HashOf
+    attr_reader :key_validator, :value_validator
+
+    def initialize(key_validator, value_validator)
+      @key_validator, @value_validator = key_validator, value_validator
+      freeze
+    end
+
+    # @return [Boolean]
+    def ===(value)
+      Hash === value && value.all? do |key, value|
+        key_validator === key && value_validator === value
+      end
+    end
+  end
+
+  class ArrayCoercer
+    attr_reader :element_coercer
+
+    def initialize(element_coercer = nil)
+      @element_coercer = element_coercer
+      freeze
+    end
+
+    def call(obj)
+      if obj.respond_to?(:to_a)
+        array = obj.to_a
+        if element_coercer
+          array.map { |element| element_coercer.call(element) }
+        else
+          array
+        end
+      else
+        obj
+      end
+    end
+  end
+
   #
   # ValueSemantics equivalent of the Struct class from the Ruby standard
   # library

data/lib/value_semantics/version.rb

@@ -1,3 +1,3 @@
 module ValueSemantics
-  VERSION = "3.4.0"
+  VERSION = "3.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: value_semantics
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Tom Dalling
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-01 00:00:00.000000000 Z
+date: 2020-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -108,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: eceval
+  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: "\n    Generates modules that provide conventional value semantics for
   a given set of attributes.\n    The behaviour is similar to an immutable `Struct`
   class,\n    plus extensible, lightweight validation and coercion.\n  "
@@ -129,7 +143,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/tomdalling/value_semantics/issues
   changelog_uri: https://github.com/tomdalling/value_semantics/blob/master/CHANGELOG.md
-  documentation_uri: https://github.com/tomdalling/value_semantics/blob/v3.4.0/README.md
+  documentation_uri: https://github.com/tomdalling/value_semantics/blob/v3.5.0/README.md
   source_code_uri: https://github.com/tomdalling/value_semantics
 post_install_message: 
 rdoc_options: []