anima 0.1.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8829390b1d9de51fddff518775263b3d349298bc
-  data.tar.gz: b7cfafb8c2c03195da23c1cfe3a26be3d20c93fb
+SHA256:
+  metadata.gz: 56e64bf9fa6d98eacb6fbee0c76efd33a60e7493bff45d1672ae5c2f16dcb69d
+  data.tar.gz: 560ecd27777601ad003518606d67031875c8cf58f337054d39d89ae1eb5815ee
 SHA512:
-  metadata.gz: 9ef1d565f8abe13a9914af0439b2bae68a3350819b240a1dbedf565d50a5c1639696282b676db17ede25d8d82a82aa2355fe7ad2584fbcdd502ee0cddc602769
-  data.tar.gz: cef667e63a0f638bd8ed31474fce8dde15df03922b1f3d069a4829b328a795e5d906267e09ca1c999cc675084beb77deb556412d784c485d865820cb141e435a
+  metadata.gz: 69d90b65d31f7214b28a9b2b70dd6f9f9248adca8c95438d41b172971548fca719bc8421e227a4c21dcb7472c51edecf79103c2bbb9c0f05195bfd8bf44c4d6f
+  data.tar.gz: 7cfdcef4ca9bbc3f82e43530885643af1a9c5ea87cc77014c883714aead23ff47091c8265ea3b626914d439e3b5b37417eb01d5051c8c44f436324c154f4d469

data/README.md

@@ -1,11 +1,9 @@
 anima
 =====
 
-[![Build Status](https://secure.travis-ci.org/mbj/anima.png?branch=master)](http://travis-ci.org/mbj/anima)
-[![Dependency Status](https://gemnasium.com/mbj/anima.png)](https://gemnasium.com/mbj/anima)
-[![Code Climate](https://codeclimate.com/github/mbj/anima.png)](https://codeclimate.com/github/mbj/anima)
+![CI](https://github.com/mbj/anima/workflows/CI/badge.svg)
 
-Simple library to declare read only attributes on value-objects that are initialized via attributes hash. 
+Simple library to declare read only attributes on value-objects that are initialized via attributes hash.
 
 Installation
 ------------
@@ -15,7 +13,9 @@ Install the gem `anima` via your preferred method.
 Examples
 --------
 
-```
+```ruby
+require 'anima'
+
 # Definition
 class Person
   include Anima.new(:salutation, :firstname, :lastname)
@@ -23,28 +23,30 @@ end
 
 # Every day operation
 a = Person.new(
-  :salutation => 'Mr',
-  :firstname  => 'Markus',
-  :lastname   => 'Schirp'
+  salutation: 'Mr',
+  firstname:  'Markus',
+  lastname:   'Schirp'
 )
 
+# Returns expected values
 a.salutation # => "Mr"
 a.firstname  # => "Markus"
 a.lastname   # => "Schirp"
-a.frozen?    # => true
+a.frozen?    # => false
 
 b = Person.new(
-  :salutation => 'Mr',
-  :firstname  => 'John',
-  :lastname   => 'Doe'
+  salutation: 'Mr',
+  firstname:  'John',
+  lastname:   'Doe'
 )
 
-a = Person.new(
-  :salutation => 'Mr',
-  :firstname  => 'Markus',
-  :lastname   => 'Schirp'
+c = Person.new(
+  salutation: 'Mr',
+  firstname:  'Markus',
+  lastname:   'Schirp'
 )
 
+# Equality based on attributes
 a == b      # => false
 a.eql?(b)   # => false
 a.equal?(b) # => false
@@ -53,19 +55,25 @@ a == c      # => true
 a.eql?(c)   # => true
 a.equal?(c) # => false
 
-# Functional updates
-class Person
-  include Anima::Update
-end
-
-d = b.update(
-  :salutation => 'Mrs', 
-  :firstname  => 'Sue',
+# Functional-style updates
+d = b.with(
+  salutation: 'Mrs',
+  firstname:  'Sue',
 )
 
 # It returns copies, no inplace modification
 d.equal?(b) # => false
 
+# Hash representation
+d.to_h # => { salutation: 'Mrs', firstname: 'Sue', lastname: 'Doe' }
+
+# Disallows initialization with incompatible attributes
+
+Person.new(
+  # :saluatation key missing
+  "firstname" => "Markus", # does NOT coerce this by intention
+  :lastname   => "Schirp"
+) # raises Anima::Error with message "Person attributes missing: [:salutation, :firstname], unknown: ["firstname"]
 ```
 
 Credits

data/lib/anima.rb

@@ -1,45 +1,37 @@
-require 'backports'
 require 'adamantium'
 require 'equalizer'
 require 'abstract_type'
 
 # Main library namespace and mixin
+# @api private
 class Anima < Module
   include Adamantium::Flat, Equalizer.new(:attributes)
 
   # Return names
   #
-  # @return [AttriuteSet]
-  #
-  # @api private
-  #
+  # @return [AttributeSet]
   attr_reader :attributes
 
   # Initialize object
   #
   # @return [undefined]
-  #
-  # @api private
-  #
   def initialize(*names)
-    @attributes = names.uniq.map { |name| Attribute.new(name) }.freeze
+    @attributes = names.uniq.map(&Attribute.method(:new)).freeze
   end
 
-  # Return new anima with attributes removed
+  # Return new anima with attributes added
   #
   # @return [Anima]
   #
   # @example
   #   anima = Anima.new(:foo)
-  #   anima.add(:foo) # equals Anima.new(:foo, :bar)
+  #   anima.add(:bar) # equals Anima.new(:foo, :bar)
   #
-  # @api public
-  #
-  def remove(*names)
-    new(attribute_names - names)
+  def add(*names)
+    new(attribute_names + names)
   end
 
-  # Return new anima with attributes added
+  # Return new anima with attributes removed
   #
   # @return [Anima]
   #
@@ -47,10 +39,8 @@ class Anima < Module
   #   anima = Anima.new(:foo, :bar)
   #   anima.remove(:bar) # equals Anima.new(:foo)
   #
-  # @api private
-  #
-  def add(*names)
-    new(attribute_names + names)
+  def remove(*names)
+    new(attribute_names - names)
   end
 
   # Return attributes hash for instance
@@ -58,9 +48,6 @@ class Anima < Module
   # @param [Object] object
   #
   # @return [Hash]
-  #
-  # @api private
-  #
   def attributes_hash(object)
     attributes.each_with_object({}) do |attribute, attributes_hash|
       attributes_hash[attribute.name] = attribute.get(object)
@@ -70,9 +57,6 @@ class Anima < Module
   # Return attribute names
   #
   # @return [Enumerable<Symbol>]
-  #
-  # @api private
-  #
   def attribute_names
     attributes.map(&:name)
   end
@@ -85,124 +69,114 @@ class Anima < Module
   # @param [Hash] attribute_hash
   #
   # @return [self]
-  #
-  # @api private
-  #
   def initialize_instance(object, attribute_hash)
+    assert_known_attributes(object.class, attribute_hash)
     attributes.each do |attribute|
       attribute.load(object, attribute_hash)
     end
+    self
+  end
 
-    overflow = attribute_hash.keys - attribute_names
+  # Static instance methods for anima infected classes
+  module InstanceMethods
+    # Initialize an anima infected object
+    #
+    # @param [#to_h] attributes
+    #   a hash that matches anima defined attributes
+    #
+    # @return [undefined]
+    def initialize(attributes)
+      self.class.anima.initialize_instance(self, attributes)
+    end
 
-    unless overflow.empty?
-      raise Error::Unknown.new(object.class, overflow)
+    # Return a hash representation of an anima infected object
+    #
+    # @example
+    #   anima.to_h # => { :foo => : bar }
+    #
+    # @return [Hash]
+    #
+    # @api public
+    def to_h
+      self.class.anima.attributes_hash(self)
     end
 
-    self
-  end
+    # Return updated instance
+    #
+    # @example
+    #   klass = Class.new do
+    #     include Anima.new(:foo, :bar)
+    #   end
+    #
+    #   foo = klass.new(:foo => 1, :bar => 2)
+    #   updated = foo.with(:foo => 3)
+    #   updated.foo # => 3
+    #   updated.bar # => 2
+    #
+    # @param [Hash] attributes
+    #
+    # @return [Anima]
+    #
+    # @api public
+    def with(attributes)
+      self.class.new(to_h.update(attributes))
+    end
+  end # InstanceMethods
 
-private
+  private
 
-  # Hook called when module is included
+  # Infect the instance with anima
   #
   # @param [Class, Module] scope
   #
   # @return [undefined]
-  #
-  # @api private
-  #
-  def included(scope)
-    define_anima_method(scope)
-    define_initializer(scope)
-    define_attribute_readers(scope)
-    define_attribute_hash_reader(scope)
-    define_equalizer(scope)
-  end
+  def included(descendant)
+    descendant.instance_exec(self, attribute_names) do |anima, names|
+      # Define anima method
+      define_singleton_method(:anima) { anima }
 
-  # Return new instance
-  #
-  # @param [Enumerable<Symbol>] attributes
-  #
-  # @return [Anima]
-  #
-  # @api private
-  #
-  def new(attributes)
-    self.class.new(*attributes)
-  end
+      # Define instance methods
+      include InstanceMethods
 
-  # Define anima method on scope
-  #
-  # @param [Class, Module] scope
-  #
-  # @return [undefined]
-  #
-  # @api private
-  #
-  def define_anima_method(scope)
-    anima = self
+      # Define attribute readers
+      attr_reader(*names)
 
-    scope.define_singleton_method(:anima) do
-      anima
+      # Define equalizer
+      include Equalizer.new(*names)
     end
   end
 
-  # Define equalizer on scope
-  #
-  # @param [Class, Module] scope
-  #
-  # @return [undefined]
+  # Fail unless keys in +attribute_hash+ matches #attribute_names
   #
-  # @api private
-  #
-  def define_equalizer(scope)
-    scope.send(:include, Equalizer.new(*attribute_names))
-  end
-
-  # Define attribute readers
+  # @param [Class] klass
+  #   the class being initialized
   #
-  # @param [Class, Module] scope
+  # @param [Hash] attribute_hash
+  #   the attributes to initialize +object+ with
   #
   # @return [undefined]
   #
-  # @api private
-  #
-  def define_attribute_readers(scope)
-    attributes.each do |attribute|
-      attribute.define_reader(scope)
-    end
-  end
+  # @raise [Error]
+  def assert_known_attributes(klass, attribute_hash)
+    keys = attribute_hash.keys
 
-  # Define initializer
-  #
-  # @param [Class, Module] scope
-  #
-  # @return [undefined]
-  #
-  # @api private
-  #
-  def define_initializer(scope)
-    scope.send(:define_method, :initialize) do |attributes|
-      self.class.anima.initialize_instance(self, attributes)
+    unknown = keys - attribute_names
+    missing = attribute_names - keys
+
+    unless unknown.empty? && missing.empty?
+      fail Error.new(klass, missing, unknown)
     end
   end
 
-  # Define attribute hash reader
-  #
-  # @param [Class, Module] scope
-  #
-  # @return [undefined]
+  # Return new instance
   #
-  # @api private
+  # @param [Enumerable<Symbol>] attributes
   #
-  def define_attribute_hash_reader(scope)
-    scope.define_singleton_method(:attributes_hash) do |object|
-      anima.attributes_hash(object)
-    end
+  # @return [Anima]
+  def new(attributes)
+    self.class.new(*attributes)
   end
-end
+end # Anima
 
 require 'anima/error'
 require 'anima/attribute'
-require 'anima/update'

data/lib/anima/attribute.rb

@@ -1,5 +1,4 @@
 class Anima
-
   # An attribute
   class Attribute
     include Adamantium::Flat, Equalizer.new(:name)
@@ -7,38 +6,28 @@ class Anima
     # Initialize attribute
     #
     # @param [Symbol] name
-    #
-    # @api private
-    #
     def initialize(name)
-      @name = name
+      @name, @instance_variable_name = name, :"@#{name}"
     end
 
     # Return attribute name
     #
     # @return [Symbol]
-    #
-    # @api private
-    #
     attr_reader :name
 
+    # Return instance variable name
+    #
+    # @return [Symbol]
+    attr_reader :instance_variable_name
+
     # Load attribute
     #
     # @param [Object] object
     # @param [Hash] attributes
     #
     # @return [self]
-    #
-    # @api private
-    #
     def load(object, attributes)
-      attribute_name = name
-
-      value = attributes.fetch(attribute_name) do
-        raise Error::Missing.new(object.class, attribute_name)
-      end
-
-      set(object, value)
+      set(object, attributes.fetch(name))
     end
 
     # Get attribute value from object
@@ -46,9 +35,6 @@ class Anima
     # @param [Object] object
     #
     # @return [Object]
-    #
-    # @api private
-    #
     def get(object)
       object.public_send(name)
     end
@@ -59,39 +45,10 @@ class Anima
     # @param [Object] value
     #
     # @return [self]
-    #
-    # @api private
-    #
     def set(object, value)
       object.instance_variable_set(instance_variable_name, value)
 
       self
     end
-
-    # Return instance variable name
-    #
-    # @return [Symbol]
-    #   returns @ prefixed name
-    #
-    # @api private
-    #
-    def instance_variable_name
-      :"@#{name}"
-    end
-    memoize :instance_variable_name
-
-    # Define reader
-    #
-    # @param [Class, Module] scope
-    #
-    # @return [self]
-    #
-    # @api private
-    #
-    def define_reader(scope)
-      scope.send(:attr_reader, name)
-      self
-    end
-
   end # Attribute
 end # Anima