hashing 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 58fbbbe8dddf5ac8299796af0123035abba17b68
-  data.tar.gz: 142748d477848bc270bdd7fc4c74be5bcd6335ab
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YWJiN2EwYTk5Y2MyNDQzZjQ1MGQxYzcyMjE0YTE1MjRlMmRlZDIyMQ==
+  data.tar.gz: !binary |-
+    M2NkMjcxOThkMGI2ZWVkY2JhZjY4YTMwYjEzMGY0YTliYjVhOWQ2OA==
 SHA512:
-  metadata.gz: a5488323cd2dc9d7d53b2f2c53eeb091b7283b7f3d37be183d2311e67fd2cc5484ce7c02a070051d40ae7e30db87c718ee97f276dd332f9034321ae9f3600dbb
-  data.tar.gz: bbfa91cdfcacc250f95b9a9a1ff66986cb281db6007b8f95dac0198641f446c3fd10a7ad8681a07c455e4f3299952aadea8332cf2b06eb30e4878715dec8e7ab
+  metadata.gz: !binary |-
+    M2I3ODUxM2UxZWRkZWQxNmM2NjcxMDc5NDQwNTU5ZmM3YzViZWRjMDQyMGY5
+    NDZlNDYyMTdmNTU3YmYwYWI0NGNhYjgyMGExZDcxZDNhZjA0NTljNGMxMmJm
+    MzkyM2FkNGYyZjJlN2FlMGJiZjZlNDJlMmFlNWM2OTQ0Mjk2YmY=
+  data.tar.gz: !binary |-
+    MWQ2ZjMyYjQxMDMyNmYwMWUzOTRkZDJhMjVhMDQ0YmUzNTY0NmZiMTA1MzZi
+    ZGQxM2U0NWQ5NjQyYmExYzAyOTlhY2IyYTBlOTYxZDQ0ZDNiODM5ZWVmNDZj
+    ZGZkMzJlZjRlYmI2NDZlYzRkZDdhOWNmZmJlOWM1NTA5ZDI2ZTM=

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# v0.1.0 2014-05-23
+
+## better api naming and conventions
+
+  * removes the Hash as last parameters, introducing a well established api
+
+# v0.0.1 2014-05-02
+
+## first public release :heartpulse:
+
+  * module `Hashing` and class methods `hasherize` and `loading`
+  * class (module) `Hasherize` to sugar the `ivars` declaration
+  * nested `Hashing` for collections

data/README.md

@@ -6,9 +6,9 @@ method. Also gives you a `YourClass::from_hash` to reconstruct the instances.
 
 ## Status
 [![Gem Version](https://badge.fury.io/rb/hashing.svg)](http://badge.fury.io/rb/hashing)
-[![Build Status](https://travis-ci.org/ricardovaleriano/hashing.png?branch=master)](http://travis-ci.org/ricardovaleriano/hashing?branch=master)
+[![Build Status](https://travis-ci.org/ricardovaleriano/hashing.svg?branch=master)](http://travis-ci.org/ricardovaleriano/hashing?branch=master)
 [![Code Climate](https://codeclimate.com/github/ricardovaleriano/hashing.png)](https://codeclimate.com/github/ricardovaleriano/hashing)
-[![Inline docs](http://inch-pages.github.io/github/ricardovaleriano/hashing.png)](http://inch-pages.github.io/github/ricardovaleriano/hashing)
+[![Inline docs](http://inch-pages.github.io/github/ricardovaleriano/hashing.svg)](http://inch-pages.github.io/github/ricardovaleriano/hashing)
 
 ## Installation
 
@@ -24,6 +24,12 @@ Or install it yourself as:
 
     $ gem install hashing
 
+## Contact
+
+* API Doc: http://rdoc.info/gems/hashing
+* Bugs, issues and feature requests: https://github.com/ricardovaleriano/hashing/issues
+* Support: http://stackoverflow.com/questions/tagged/hashing-ruby
+
 ## Usage
 
 Given a `File` class like this:
@@ -82,11 +88,8 @@ valid `Hash` like the one created by a `#to_h` call:
 ```ruby
 class File
   include Hashing
-  hasherize :path, :commit, :content
-
-  loading ->(hash) {
-    new hash[:path], hash[:commit], hash[:content]
-  }
+  hasherize(:path, :commit, :content).
+    loading ->(hash) { new hash[:path], hash[:commit], hash[:content] }
 
   # ...
 end
@@ -101,36 +104,58 @@ should call them whatever you need in your programs. But the `::from_hash`
 method will be called by `Hashing` when building your instances from hashes (more
 about this: [nested hasherizing](#nested-hasherized-objects)).
 
-#### Hasherize
+### Custom "hasherizing" and loading strategies
 
-`Hashing` comes with an alternative way to indicate what fields should be used to
-represent your objects as a `Hash`. This can be done by the `Hasherize` class.
-The previous example can be writen like this:
+Many times you will need apply some computation over the contents of your
+`ivars` transform them in a primitive that can be stored as a `Hash`.
+
+Following the `File` class example, maybe you want to store the `@content` as a
+`Base64` enconded string.
+
+`Hashing` allows you to specify the strategy of serialization and loading when
+indicating which `ivars` should be part of the final `Hash`:
 
 ```ruby
+require 'base64'
+
 class File
-  include Hasherize.new :path, :commit, :content
+  include Hashing
+
+  hasherize :path, :commit
 
-  loading ->(hash) {
-    new hash[:path], hash[:commit], hash[:content]
-  }
+  hasherize(:content).
+    to(->(content) { Base64.encode64 content }).
+    from(->(content_string) { Base64.decode64 content_string }).
+    loading ->(hash) { new hash[:path], hash[:commit], hash[:content] }
 
   # ...
 end
 ```
 
-It's just a matter of taste. Use the one that is more appealing to you.
+But I will recomend this approach only if your strategy for serialization is
+more complex than just call a method in an object passing the raw value. If your
+need is exactly like this, you can just indicate the object and the methods that
+should be called in what moment:
 
-### Custom "hasherizing" and loading strategies
+```ruby
+require 'base64'
 
-Many times you will need apply some computation over the contents of your
-`ivars` transform them in a primitive that can be stored as a `Hash`.
+class File
+  include Hashing
 
-Following the `File` class example, maybe you want to store the `@content` as a
-`Base64` enconded string.
+  hasherize(:path, :commit).
+    loading ->(hash) { new hash[:path], hash[:commit], hash[:content] }
 
-`Hashing` allows you to specify the strategy of serialization and loading when
-indicating which `ivars` should be part of the final `Hash`:
+  hasherize(:content).using(Base64).to(:encode64).from(:decode64)
+
+  # ...
+end
+```
+
+And finally, if the your serialization logic is worth a method on it's own, you
+can indicate this by passing the method names via symbol to the `:to` and
+`:from` options. Since those methods don't necessarily make sense as part of
+your public api, so you can even make then private:
 
 ```ruby
 require 'base64'
@@ -138,15 +163,21 @@ require 'base64'
 class File
   include Hashing
 
-  hasherize :path, :commit
+  hasherize(:path, :commit).
+    loading ->(hash) { new hash[:path], hash[:commit], hash[:content] }
+
+  hasherize(:content).to(:encode).from(:decode)
 
-  hasherize :content,
-    to_hash: ->(content) { Base64.encode64 content },
-    from_hash: ->(content_string) { Base64.decode64 content_string }
+  # ...
 
-  loading ->(hash) {
-    new hash[:path], hash[:commit], hash[:content]
-  }
+  private
+  def encode(content)
+    Base64.encode64 content
+  end
+
+  def decode(content)
+    Base64.decode64 content
+  end
 
   # ...
 end
@@ -161,12 +192,16 @@ multiple `ivars` if it makes sense to your program:
 class File
   include Hashing
 
-  hasherize :path, :commit,
-    to_hash: ->(value) { value.downcase },
-    from_hash: ->(value) { value.downcase }
+  hasherize(:path, :commit).
+    to(->(value) { value.downcase }).
+    from(->(value) { value.upcase })
 end
 ```
 
+This will guarantees that the final `Hash` has the `path` and the `commit`
+values "downcased" when your object is serialized, and "upcased" when the
+instance is reconstructed.
+
 #### Nested hasherized objects
 
 But if your transformations are a little more complicated than a simple `Base64`
@@ -206,13 +241,14 @@ end
 
 So in this case, if you wants a file to be `hasherized®` with it's internall
 `@annotations` preserved, you just indicate this in the `File` class. The
-example now can be rewriten as:
+example now can be rewritten as:
 
 ```ruby
 class File
   include Hashing
 
-  hasherize :path, :commit, :annotations
+  hasherize :path, :commit
+  hasherize(:annotations).collection Annotation
 
   # ...
 end
@@ -221,9 +257,34 @@ end
 Since the `Annotation` class has it's own notion of `#to_h` and `::from_hash`,
 this is all that `Hashing` needs to build a `File` instances from a valid `Hash`.
 
+#### Defining `attr_reader` within the `.hasherize` invocation
+
+If you want to define `readers` for the `ivars` passed to `.hasherize`, you can
+do this with the option `attr: true` (defaults to `false`).
+
+So, the following example:
+
+```ruby
+class File
+  include Hashing
+  hasherize :path, :commit, :content
+
+  attr_reader :path, :commit, :content
+end
+```
+
+Can be written as:
+
+```ruby
+class File
+  include Hashing
+  hasherize(:path, :commit, :content).reader true
+end
+```
+
 ## Contributing
 
-This was a rapid "scratch your own itch" kind of project. It will make me real
+This is a rapid "scratch your own itch" kind of project. It will make me really
 happy if it can be used used in your software anyhow. If you need something
 different than what is in it, or can solve us some bugs or add documentation, it
 will be very well received!

data/hashing.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = Hashing::VERSION
   spec.authors       = ["Ricardo Valeriano"]
   spec.email         = ["ricardo.valeriano@gmail.com"]
-  spec.summary       = %q{Serialize your objects as Hashes}
-  spec.description   = %q{Gives you an easy way to specify which instances vars of your objects should be used as `key => value` to serialize it into a hash returned by the `#to_h` method. Also gives you a `YourClass::from_hash` to reconstruct the instances.}
+  spec.summary       = %q{Serialize your objects into Hashes}
+  spec.description   = %q{Provides an easy way to specify which instances vars of your objects should be used as `key` in a Hash returned by the `#to_h` method. Also gives you a `YourClass::from_hash` to reconstruct the instances.}
   spec.homepage      = "http://github.com/ricardovaleriano/hashing"
   spec.license       = "MIT"
 

data/lib/hashing.rb

@@ -1,49 +1,40 @@
-require 'hashing/version'
-require 'hashing/ivar'
-require 'hasherize'
-
+require 'hashing/macros'
+
+# Inject the public api into the host class, and it's instances.
+# By "public api" we understand the class methods
+#
+# - {Hashing::Macros#hasherize}
+# - {Hashing::Macros#from_hash}
+# - {Hashing::Macros#__hasher}
+#
+# And the instance method:
+#
+# - {Hashing#to_h}
+#
+# @since 0.0.1
+#
+# @example including Hashing
+#   require 'hashing'
+#
+#   class File
+#     include Hashing
+#     hasherize :path, :commit
+#
+#     def initialize(path, commit)
+#       @path, @commit = path, commit
+#     end
+#   end
+#
+# When `Hashing` is included, the host class will gain the `.from_hash({})`
+# method and the `#to_h` instance method.
+# Another method that will be added is the private class method `.hasherize`
+# will be added so you can indicate what ivars do you want in your sarialized
+# objects.
 module Hashing
-  # Inform the user about an attempt to create an instance, using a `Hash` with
-  # keys that does not correspond to the mape made using `.hasherize`
-  class UnconfiguredIvar < StandardError
-    def initialize(ivar_name, class_name)
-      super "The Hash has a :#{ivar_name} key, "+
-        "but no @#{ivar_name} was configured in #{class_name}"
-    end
-  end
-
-  # Inject the public api into the client class.
-  #
-  # @since 0.0.1
-  #
-  # @example including Hashing
-  #   require 'hashing'
-  #
-  #   class File
-  #     include Hashing
-  #     hasherize :path, :commit
-  #
-  #     def initialize(path, commit)
-  #       @path, @commit = path, commit
-  #     end
-  #   end
-  #
-  # When `Hashing` is included, the host class will gain the `.from_hash({})`
-  # method and the `#to_h` instance method.
-  # Another method that will be added is the private class method `.hasherize`
-  # will be added so you can indicate what ivars do you want in your sarialized
-  # objects.
   def self.included(client_class)
-    client_class.extend Hasherizer
+    client_class.extend Macros
   end
 
-  def meta_data(name, value)
-    @_hashing_meta_data ||= { __hashing__: { types: {} } }
-    @_hashing_meta_data[:__hashing__][:types][name] = value
-    @_hashing_meta_data
-  end
-
-  #
   # The `Hash` returned by `#to_h` will be formed by keys based on the ivars
   # names passed to `hasherize` method.
   #
@@ -53,118 +44,6 @@ module Hashing
   #   file.to_h
   #   # => { path: 'README.md', commit: 'cfe9aacbc02528b' }
   def to_h
-    hash_pairs = self.class.ivars.map { |ivar|
-      value = instance_variable_get "@#{ivar}"
-      if value.respond_to? :map
-        meta_data ivar.to_sym, value.first.class
-      end
-      [ivar.to_sym, ivar.to_h(value)]
-    }
-    Hash[hash_pairs].merge(@_hashing_meta_data || {})
-  end
-
-  # Define the class methods that should be available in a 'hasherized ®' class
-  # (a class that include `Hashing`).
-  module Hasherizer
-    # Configures which instance variables will be used to compose the `Hash`
-    # generated by `#to_h`
-    #
-    # @api
-    # @param ivars_and_options [*arguments]
-    def hasherize(*ivars_and_options)
-      @ivars ||= []
-      ivars = extract_ivars ivars_and_options
-      to_strategy = strategy_for_key :to_hash, ivars_and_options
-      from_strategy = strategy_for_key :from_hash, ivars_and_options
-      @ivars += ivars.map { |ivar| Ivar.new ivar, to_strategy, from_strategy }
-    end
-
-    # Configures the strategy to (re)create an instance of the 'hasherized ®'
-    # class based on a `Hash` instance. This strategy will be used by the
-    # `.from_hash({})` method.
-    #
-    # This configuration is optional, if it's not called, then the strategy will
-    # be just repassing the `Hash` to the initializer.
-    #
-    # @param strategy [#call]
-    # @return void
-    def loading(strategy)
-      @strategy = strategy
-    end
-
-    # Provides the default strategy for recreate objects from hashes (which is
-    # just call .new passing the `Hash` as is.
-    #
-    # @return the result of calling the strategy
-    def strategy
-      @strategy || ->(h) { new h }
-    end
-
-    # those methods are private but part of the class api (macros).
-    # #TODO: there is a way to document the 'macros' for a class in YARD?
-    private :hasherize, :loading, :strategy
-
-    # provides access to the current configuration on what `ivars` should be
-    # used to generate a `Hash` representation of instances of the client class.
-    #
-    # @return [Array] ivars that should be included in the final Hash
-    def ivars
-      @ivars ||= []
-    end
-
-    # Receives a `Hash` and uses the strategy configured by `.loading` to
-    # (re)create an instance of the 'hasherized ®' class.
-    #
-    # @param pairs [Hash] in a valid form defined by `.hasherize`
-    # @return new object
-    def from_hash(pairs)
-      metadata = pairs.delete(:__hashing__) || {}
-      hash_to_load = pairs.map do |ivar_name, value|
-        ivar = ivar_by_name ivar_name.to_sym
-        [ivar.to_sym, ivar.from_hash(value, metadata)]
-      end
-      strategy.call Hash[hash_to_load]
-    end
-
-    private
-    # Cleanup the arguments received by `.hasherize` so only the `ivar` names
-    # are returned. This is necessarey since the `.hasherize` can receive a
-    # `Hash` with strategies `:from_hash` and `:to_hash` as the last argument.
-    #
-    # @param ivars_and_options [Array] arguments received by `.serialize`
-    # @return [Array[:Symbol]] ivar names that should be used in the `Hash` serialization
-    def extract_ivars(ivars_and_options)
-      ivars = ivars_and_options.dup
-      if ivars.last.is_a? Hash
-        ivars.pop
-      end
-      ivars
-    end
-
-    # Fetches the strategy to serialize or deserialize (defined by the first
-    # param `strategy`) the `ivars` passed as second parameter
-    #
-    # @param hash_key [Symbol] (:to_hash || :from_hash) type of strategy to fetch
-    # @param ivars_and_options [*args | *args, Hash]
-    # @return [#call] strategy to be used
-    def strategy_for_key(strategy, ivars_and_options)
-      default_strategy_just_returns = ->(ivar_value) { ivar_value }
-      strategies = { strategy => default_strategy_just_returns }
-      strategies = ivars_and_options.last if ivars_and_options.last.is_a? Hash
-      strategies[strategy]
-    end
-
-    # Search an `ivar` by it's name in the class ivars collection
-    #
-    # #TODO: Can be enhanced since now the ivars doesn't have a sense of
-    # equality.
-    #
-    # @param ivar_name [Symbol] `ivar` name
-    # @return [Ivar]
-    def ivar_by_name(ivar_name)
-      ivar = ivars.select { |ivar| ivar.to_sym == ivar_name }.first
-      raise UnconfiguredIvar.new ivar_name, name unless ivar
-      ivar
-    end
+    self.class.__hasher.to_h self
   end
 end

data/lib/hashing/hasher.rb

@@ -0,0 +1,184 @@
+require "hashing/ivar"
+require "hashing/unconfigured_ivar_error"
+
+module Hashing
+  # This class contains the interface "exported" by a call to the `.hasherize`
+  # method in any class that includes the module [Hashing].
+  class Hasher
+    attr_reader :ivars
+
+    # @param host_class [Class] the class whose ivars will be used to serialize
+    # @param ivars [Array<Symbol>] the ivars that will be serialized
+    def initialize(host_class, ivars = nil)
+      @host_class = host_class
+      add ivars
+    end
+
+    # --- api {{{
+
+    # Provides the api to configure the strategy to serialize an instance of a
+    # class that includes {Hashing} into a hash object.
+    #
+    # @since 0.1.0
+    #
+    # @param strategy [#call] the logic to convert some value to a [Hash]
+    # @return [Hasher]
+    def to(strategy)
+      logic_for :to_h, strategy
+    end
+
+    # Provides the api to configure the logic to serialize an instance of a
+    # class that includes {Hashing} into a hash object.
+    #
+    # @since 0.1.0
+    #
+    # @param strategy [#call] the logic to convert some value to a [Hash]
+    # @return [Hasher]
+    def from(strategy)
+      logic_for :from_hash, strategy
+    end
+
+    # Provides the api to create attr_readers in the host class for the current
+    # configured ivars (those passed to {#add}).
+    #
+    # @since 0.1.0
+    #
+    # @example: creating attr_reader from :path and :commit
+    #   hasherize(:path, :commit).reader true
+    #
+    # The example above will create accessors for :path and :commit
+    #
+    # @return [Hasher]
+    def reader(should_create_attr_reader = true)
+      if should_create_attr_reader
+        @current_ivars.each { |ivar| @host_class.send :attr_reader, ivar.to_sym }
+      end
+      self
+    end
+
+    # Provides the api to indicate an object with the serialization and
+    # unserialization logic.
+    #
+    # @example: using Base64 to serialize and unserialize some ivar:
+    #   hahserize(:content).unsing(Base64).to(:encode64).from(:decode64)
+    #
+    # Note: any object can be passe to {#using}, and the methods in these object
+    # passed as arguments to {#to} and {#from} need to be public.
+    #
+    # @since 0.1.0
+    #
+    # @return [Hasher]
+    def using(serializator)
+      @serializator = serializator
+      self
+    end
+
+    # Provides the api to say if an ivar is a collection (#map) of instances of
+    # a class that includes {Hashing}.
+    # The idea here is just to be able to restore nested {Hashing} objects.
+    #
+    # @since 0.1.0
+    #
+    # @return [Hasher]
+    def collection(type)
+      # replace current ivar for it's collection version...
+      collections = @current_ivars.map { |ivar| IvarCollection.new ivar, type }
+      @current_ivars.each { |ivar| @ivars.delete ivar }
+      @ivars += collections
+      self
+    end
+
+    # Configures the strategy to (re)create an instance of the 'hasherized ®'
+    # class based on a `Hash` instance. This strategy will be used by the
+    # `.from_hash({})` method.
+    #
+    # This configuration is optional, if it's not called, then the strategy will
+    # be just repassing the `Hash` to the initializer.
+    #
+    # @param strategy [#call]
+    # @return [Hasher] (fluent interface)
+    def loading(strategy)
+      @loading = strategy
+      self
+    end
+
+    # }}} api
+
+    # This method can be called to define which ivars will be used as keys in
+    # the final hash.
+    # Ivar names passed as arguments to this method will be used to create
+    # instances of [Ivar]. Those have the real logic of serialization and
+    # unserialization of an [Ivar].
+    # This method also keeps a reference to the last ivars passed as parameter.
+    # This is necessary to allow us to do the following call:
+    #
+    #   hasherize(:ivar1, :ivar2).to(->(value){})
+    #
+    # The previous call will configure the `:to` strategy for `:ivar1` and
+    # `:ivar2`.
+    #
+    # @param ivar_names [Array<Symbol>] ivars to be used to hasherize the instance
+    # @return [Hasher]
+    def add(ivar_names)
+      ivar_names = Array(ivar_names)
+      @current_ivars = ivar_names.map { |ivar_name| Ivar.new ivar_name }
+      @ivars ||= []
+      @ivars += @current_ivars
+      self
+    end
+
+    # Provides the logic to transform an instance of a {Hashing} class into an
+    # hash object.
+    #
+    # @return [Hash] a new hash in which keys are the ivar names and values the string value for those ivars.
+    def to_h(instance)
+      pairs = @ivars.map { |ivar|
+        ivar_value = instance.instance_variable_get :"@#{ivar.to_sym}"
+        [ivar.to_sym, ivar.to_h(ivar_value)]
+      }
+      Hash[pairs]
+    end
+
+    # This method will be called to reconstruct an instance of the type which
+    # includes {Hashing}.
+    # The `loader` in which `#call` will be called here is the one passed to the
+    # {Hashing::Hasher#loading}. If none was passed, this method will just call
+    # `.new` in the host class passing the [Hash] as argument.
+    #
+    # @param [Hash] hash serialized by a call to {Hashing::Hasher#to_h}
+    def load(hash)
+      check_for_unconfigured_keys hash
+      loader = @loading || ->(serialized) { @host_class.new serialized }
+      loader.call process_hash_values hash
+    end
+
+    private
+
+    # @since 0.1.0
+    #
+    # @param way [Symbol] :from_hash or :to_h strategy
+    # @param strategy [#call] the strategy to convert some value to or from a [Hash]
+    # @return [Hasher]
+    def logic_for(way, strategy)
+      if @serializator
+        strategy = @serializator.method strategy
+      end
+      @current_ivars.each { |ivar| ivar.send :"#{way}=", strategy }
+      self
+    end
+
+    def check_for_unconfigured_keys(hash)
+      unrecognized_keys = hash.keys - @ivars.map(&:to_sym)
+      if unrecognized_keys.count > 0
+        raise Hashing::UnconfiguredIvarError.new unrecognized_keys, @host_class
+      end
+    end
+
+    def process_hash_values(hash)
+      transformed_hash = @ivars.map { |ivar|
+        [ivar.to_sym, ivar.from_hash(hash[ivar.to_sym])]
+      }
+      Hash[transformed_hash]
+    end
+  end
+end

data/lib/hashing/ivar.rb

@@ -1,8 +1,11 @@
+require_relative 'ivar_collection'
+
 module Hashing
   # Represents each one of the instance variables in a class that should be used
   # to represent an object in a `Hash` form (serialization).
   class Ivar
     attr_reader :name
+    attr_writer :to_h, :from_hash
 
     # Configure the name of an `ivar` and the 'callable' objects thath will be
     # used to prepare the `ivar` value for serialization, and to load the object
@@ -28,10 +31,6 @@ module Hashing
     # @return the value that will be stored in the `Hash`
     def to_h(value)
       return value unless @to_h
-
-      if value.respond_to? :map
-        value = hasherize value
-      end
       @to_h.call value
     end
 
@@ -56,39 +55,5 @@ module Hashing
     def to_s
       @name.to_s
     end
-
-    private
-    # Is an object descendent of {Hashing}?
-    #
-    # @param value [Object]
-    def hashing?(value)
-      value.class.ancestors.include? Hashing
-    end
-
-    # Hasherize a value when it has {Hashing} in it's method lookup or return
-    # the value. Util when a collection of {Hashing} objects is given and need
-    # to be "hasherized"
-    #
-    # @param value [#map] the value to be verified as a {Hashing} (or not)
-    # @return [#map] collection of hashes
-    def hasherize(collection)
-      collection.map { |item| hashing?(item) ? item.to_h : item }
-    end
-
-    # If a collection of {Hashing} objects is given, we have to reconstruct all
-    # collections members before while reconstructing the collection itself.
-    # This method provides that
-    #
-    # TODO: (need?) recursion to reconstruct collections of collections
-    #
-    # @param value [#map] the collection of {Hashing} objects
-    # @param metadata [Hash] containing serialized data about the original object
-    # @return [#map] collection of {Hashing} instances
-    def normalize(collection, metadata)
-      elements_class = metadata.fetch(:types, {}).fetch(@name, nil)
-      return collection unless elements_class.respond_to? :from_hash
-
-      collection.map { |element| elements_class.from_hash element }
-    end
   end
 end

data/lib/hashing/ivar_collection.rb

@@ -0,0 +1,23 @@
+module Hashing
+  # Represents an ivar in a class that includes {Hashing} which contains a
+  # collection of other {Hashing} instances.
+  class IvarCollection
+    extend Forwardable
+    def_delegators :@holder, :to_sym, :to_s, :name, :to_h=, :from_hash=
+
+    def initialize(collection_holder_ivar, type)
+      @holder = collection_holder_ivar
+      @type = type
+    end
+
+    def to_h(value)
+      @holder.to_h value.map { |item|
+        item.respond_to?(:to_h) ? item.to_h : item
+      }
+    end
+
+    def from_hash(value)
+      @holder.from_hash value.map { |item| @type.from_hash item }
+    end
+  end
+end

data/lib/hashing/macros.rb

@@ -0,0 +1,38 @@
+require "hashing/hasher"
+
+module Hashing
+  # Define the class methods that should be available in a 'hasherized ®' class
+  # (a class that include {Hashing}).
+  module Macros
+    # Configures which instance variables will be used to compose the `Hash`
+    # generated by `#to_h`
+    #
+    # @api
+    # @param ivars [Array<Symbol>]
+    def hasherize(*ivars)
+      __hasher.add ivars
+    end
+
+    # those methods are private but part of the class api (macros).
+    # #TODO: there is a way to document the 'macros' for a class in YARD?
+    private :hasherize
+
+    # Receives a `Hash` and uses the strategy configured by `.loading` to
+    # (re)create an instance of the 'hasherized ®' class.
+    #
+    # @param hash [Hash] in a valid form defined by `.hasherize`
+    # @return new object
+    def from_hash(hash)
+      __hasher.load hash
+    end
+
+    # Provides the entry point to the object that has the actual logic of
+    # serialization/unserialization for {Hashing} instances.
+    # The ideia here is to not polute the host class with a bunch of methods
+    # included by the {Hashing}. Instead, we just inject the api method
+    # {#hasherize}, {#from_hash} and the internally used {#__hasher} method.
+    def __hasher
+      @__hasher ||= Hasher.new self
+    end
+  end
+end

data/lib/hashing/unconfigured_ivar_error.rb

@@ -0,0 +1,13 @@
+module Hashing
+  # Inform the user about an attempt to create an instance, using a `Hash` with
+  # keys that does not correspond to the mape made using `.hasherize`
+  class UnconfiguredIvarError < StandardError
+    def initialize(ivar_names, class_name)
+      super [
+        "The hash passed to #{class_name}.from_hash has the following ",
+        "keys that aren't configured by the .hasherize method: ",
+        "#{ivar_names.join ","}."
+      ].join
+    end
+  end
+end

data/lib/hashing/version.rb

@@ -1,3 +1,3 @@
 module Hashing
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/test/hashing/hasher_test.rb

@@ -0,0 +1,35 @@
+describe Hashing::Hasher do
+  before do
+    class WowSuchClass
+      include Hashing
+      def initialize(so_ivar = nil)
+        @so_ivar = so_ivar
+      end
+    end
+  end
+
+  let(:hasher) { Hashing::Hasher.new WowSuchClass }
+
+  describe "#attr" do
+    it "with true, provides attr_readers for the current ivars" do
+      hasher.add(:very_ivar).reader true
+      WowSuchClass.new.respond_to?(:very_ivar).must_be :==, true
+    end
+  end
+
+  describe "#using" do
+    require 'base64'
+
+    it "stores an object with methods to transform the current ivar" do
+      class WowSuchClass
+        hasherize(:so_ivar).reader(true).
+          using(Base64).to(:encode64).from(:decode64).
+          loading ->(hash) { new hash[:so_ivar] }
+      end
+
+      wow = WowSuchClass.new "borba"
+      wow.to_h.must_be :==, {so_ivar: Base64.encode64("borba")}
+      WowSuchClass.from_hash({so_ivar: Base64.encode64("borba")}).so_ivar.must_be :==, 'borba'
+    end
+  end
+end

data/test/hashing/nested_test.rb

@@ -1,29 +1,31 @@
 describe Hashing do
   describe 'when one of the ivars is an `Array` of hasherized objects' do
-    class HashingCollectionOwner
-      attr_reader :file, :commit, :annotations
-      include Hasherize.new :file, :commit, :annotations
-
-      loading ->(hash) { new hash[:file], hash[:commit], hash[:annotations] }
-
-      def initialize(file, commit, annotations)
-        @file, @commit, @annotations = file, commit, annotations
-      end
-    end
-
     class HashingCollectionMember
       attr_reader :annotation
-      include Hasherize.new :annotation,
-        to_hash: ->(value) { "--#{value}" },
-        from_hash: ->(value) { "#{value}--" }
-
-      loading ->(hash) { new hash[:annotation] }
+      include Hashing
+      hasherize(:annotation).
+        to(->(value) { "--#{value}" }).
+        from(->(value) { "#{value}--" }).
+        loading(->(hash) { new hash[:annotation] })
 
       def initialize(annotation)
         @annotation = annotation
       end
     end
 
+    class HashingCollectionOwner
+      attr_reader :file, :commit, :annotations
+      include Hashing
+      hasherize :file, :commit
+      hasherize(:annotations).
+        collection(HashingCollectionMember).
+        loading ->(hash) { new hash[:file], hash[:commit], hash[:annotations] }
+
+      def initialize(file, commit, annotations)
+        @file, @commit, @annotations = file, commit, annotations
+      end
+    end
+
     describe '#to_h' do
       it 'calls #to_h for each array item when hashifying the object' do
         owner = HashingCollectionOwner.new 'README.md', 'cfe9aacbc02528b', [
@@ -36,17 +38,24 @@ describe Hashing do
           annotations: [
             { annotation: '--first' },
             { annotation: '--second' },
-          ],
-          __hashing__: {
-            types: {
-              annotations: HashingCollectionMember
-            }
-          }
+          ]
         }
-        p owner.to_h
       end
 
-      it "don't call the #to_h on inner object that don't include `Hashing`"
+      it "don't call the #to_h on inner object that don't include `Hashing`" do
+        owner = HashingCollectionOwner.new 'README.md', 'cfe9aacbc02528b', [
+          HashingCollectionMember.new('first'),
+          "xpto",
+        ]
+        owner.to_h.must_be :==, {
+          file: 'README.md',
+          commit: 'cfe9aacbc02528b',
+          annotations: [
+            { annotation: '--first' },
+            'xpto',
+          ]
+        }
+      end
     end
 
     describe '#from_h' do
@@ -57,16 +66,11 @@ describe Hashing do
           annotations: [
             {annotation: "first"},
             {annotation: "second"}
-          ],
-          __hashing__: {
-            types: {
-              annotations: HashingCollectionMember
-            }
-          }
+          ]
         }
       end
 
-      it 'calls #from_h for each on an yaml array that contains hasherized objects' do
+      it 'calls #from_hash for each element on an yaml array that contains hasherized objects' do
         owner = HashingCollectionOwner.from_hash hash_values
         owner.annotations.first.annotation.must_be :==, 'first--'
         owner.annotations.last.annotation.must_be :==, 'second--'

data/test/hashing_test.rb

@@ -3,14 +3,9 @@ require "base64"
 describe Hashing do
   describe 'interface' do
     let(:hasherized) do
-      # if in doubt about the absense of assertions in this test, please
-      # refer to:
-      # - http://blog.zenspider.com/blog/2012/01/assert_nothing_tested.html
-      # and https://github.com/seattlerb/minitest/issues/159
       Class.new do
         include Hashing
-        hasherize :ivar
-        loading ->() {}
+        hasherize(:ivar)
       end
     end
 
@@ -24,48 +19,61 @@ describe Hashing do
   end# interface
 
   describe 'Recreating a `hasherized` class instance' do
-    let(:hasherized) do
-      Class.new do
-        attr_reader :h
+    describe '.loading' do
 
-        include Hashing
-        hasherize :h
+      before do
+        @original_stdout, $stdout = $stdout, StringIO.new
+      end
 
-        def initialize(h)
-          @h = h
-        end
+      after do
+        $stdout = @original_stdout
       end
-    end
 
-    describe '.loading' do
       it 'uses (`#call`) the strategy defined by `.loading`' do
-        called = false
-        my_strategy = ->(h) { called = true }
-        hasherized.send :loading, my_strategy
-        hasherized.from_hash Hash.new
-        called.must_be :==, true
+        Class.new do
+          include Hashing
+          hasherize(:omg).loading ->(hash) { $stdout.write hash }
+        end.from_hash omg: 'lol'
+        $stdout.string.must_be :==, '{:omg=>"lol"}'
       end
     end
 
     describe '#from_hash' do
-      it 'just calls .new if none strategy was defined by .loading' do
-        new_object = hasherized.from_hash h: 'hasherizing'
-        new_object.h.must_be :==, { h: 'hasherizing' }
+      it 'default strategy is just call `.new` passing the hash' do
+        new_object = Class.new do
+          attr_reader :h
+
+          include Hashing
+          hasherize :omg
+
+          def initialize(h)
+            @h = h
+          end
+        end.from_hash omg: 'lol'
+
+        new_object.h.must_be :==, { omg: 'lol' }
       end
 
       it 'give an informative message in case the Hash is malformed' do
-        OmgLolBBQ = hasherized
+        OmgLolBBQ = Class.new do
+          include Hashing
+          hasherize(:h).loading ->(hash) { $stdout.write hash }
+        end
+
         message = nil
-        proc {
+
+        -> {
           begin
             OmgLolBBQ.from_hash xpto: 'JUST NO!'
           rescue => e
             message = e.message
             raise e
           end
-        }.must_raise Hashing::UnconfiguredIvar
-        message.must_be :==, 'The Hash has a :xpto key, but no @xpto '+
-          'was configured in OmgLolBBQ'
+        }.must_raise Hashing::UnconfiguredIvarError
+
+        message.must_be :==, 'The hash passed to OmgLolBBQ.from_hash has the '+
+          'following keys that aren\'t configured by the .hasherize method: '+
+          'xpto.'
       end
     end
   end
@@ -78,10 +86,10 @@ describe Hashing do
         attr_reader :content
 
         hasherize :file, :commit
-        hasherize :content,
-          to_hash: ->(content) { Base64.encode64(content) },
-          from_hash: ->(hash_string) { Base64.decode64(hash_string) }
-        loading ->(hash) { new hash[:file], hash[:commit], hash[:content] }
+        hasherize(:content).
+          to(->(content) { Base64.encode64(content) }).
+          from(->(hash_string) { Base64.decode64(hash_string) }).
+          loading(->(hash) { new hash[:file], hash[:commit], hash[:content] })
 
         def initialize(file, commit, content)
           @file, @commit, @content = file, commit, content
@@ -106,8 +114,8 @@ describe Hashing do
     let(:hasherized) do
       Class.new do
         include Hashing
-        hasherize :file, :commit
-        loading ->(hash) { new hash[:file], hash[:commit] }
+        hasherize(:file, :commit).
+          loading ->(hash) { new hash[:file], hash[:commit] }
 
         def initialize(file, commit)
           @file, @commit = file, commit

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hashing
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Ricardo Valeriano
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-02 00:00:00.000000000 Z
+date: 2014-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -28,14 +28,14 @@ dependencies:
   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'
 - !ruby/object:Gem::Dependency
@@ -52,9 +52,9 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.0'
-description: Gives you an easy way to specify which instances vars of your objects
-  should be used as `key => value` to serialize it into a hash returned by the `#to_h`
-  method. Also gives you a `YourClass::from_hash` to reconstruct the instances.
+description: Provides an easy way to specify which instances vars of your objects
+  should be used as `key` in a Hash returned by the `#to_h` method. Also gives you
+  a `YourClass::from_hash` to reconstruct the instances.
 email:
 - ricardo.valeriano@gmail.com
 executables: []
@@ -63,17 +63,21 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .travis.yml
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - hashing.gemspec
-- lib/hasherize.rb
 - lib/hashing.rb
+- lib/hashing/hasher.rb
 - lib/hashing/ivar.rb
+- lib/hashing/ivar_collection.rb
+- lib/hashing/macros.rb
+- lib/hashing/unconfigured_ivar_error.rb
 - lib/hashing/version.rb
 - tasks/test.rake
-- test/hasherize_test.rb
+- test/hashing/hasher_test.rb
 - test/hashing/ivar_test.rb
 - test/hashing/nested_test.rb
 - test/hashing_test.rb
@@ -88,23 +92,24 @@ 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: []
 rubyforge_project: 
-rubygems_version: 2.1.11
+rubygems_version: 2.1.4
 signing_key: 
 specification_version: 4
-summary: Serialize your objects as Hashes
+summary: Serialize your objects into Hashes
 test_files:
-- test/hasherize_test.rb
+- test/hashing/hasher_test.rb
 - test/hashing/ivar_test.rb
 - test/hashing/nested_test.rb
 - test/hashing_test.rb
 - test/test_helper.rb
+has_rdoc: 

data/lib/hasherize.rb

@@ -1,40 +0,0 @@
-require 'hashing'
-
-# Provides some sugar syntax to declare which `ivars` should be used to
-# represent an object as a `Hash`.
-#
-# It respects all the behavior you will get by including {Hashing}. In fact,
-# using this constructor is a shortcut to `include Hashing`, and call
-# `.hasherize`
-#
-# @since 0.0.1
-#
-# @example shortcut to `include Hashing` and call `.hasherize`
-#   class File
-#     include Hasherize.new :path, :commit
-#   end
-#
-# @example configuring :to_hash and :from_hash strategies
-#   class File
-#     include Hasherize.new :content,
-#       to_hash: ->(content) { Base64.encode64 content },
-#       from_hash: ->(content_string) { Base64.decode64 content_string }
-#   end
-class Hasherize < Module
-  # Stores the ivars and options to be repassed to `Hashing.serialize` by the
-  # hook {#included}
-  #
-  # @param ivars_and_options [*args] ivar names and options (`:to_hash` and `:from_hash`)
-  def initialize(*ivars_and_options)
-    @ivars = ivars_and_options
-  end
-
-  # Includes the `Hashing` module and calls {Hashing.hasherize}, repassing the
-  # ivar names an the options received in the constructor
-  def included(serializable_class)
-    serializable_class.module_eval do
-      include Hashing
-    end
-    serializable_class.send :hasherize, *@ivars
-  end
-end

data/test/hasherize_test.rb

@@ -1,32 +0,0 @@
-describe Hasherize do
-  let(:hasherized) do
-    Class.new do
-      attr_reader :file, :commit
-
-      include Hasherize.new :file, :commit,
-        to_hash: ->(value) { "X-#{value}" },
-        from_hash: ->(value) { "#{value}-X" }
-
-      loading ->(params) { new params[:file], params[:commit] }
-
-      def initialize(file, commit)
-        @file, @commit = file, commit
-      end
-    end
-  end
-
-  it "just sugar to `include Hashing` and call `hasherize`" do
-    hasherized.ancestors.include?(Hashing).must_be :==, true
-  end
-
-  it "configures the ivars correctly (so I can recreate instances by Hash)" do
-    object = hasherized.from_hash file: 'README.md', commit: 'omglolbbq123'
-    object.file.must_be :==, 'README.md-X'
-    object.commit.must_be :==, 'omglolbbq123-X'
-  end
-
-  it "configure `:to_hash` e `:from_hash` serialization strategies" do
-    object = hasherized.new 'README.md', 'omglolbbq123'
-    object.to_h.must_be :==, { file: 'X-README.md', commit: 'X-omglolbbq123' }
-  end
-end