key_mapable 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 969c799e73735d2f2a1ba0d275e7e45edf8bb1350d7e41987899858ecd8a02b8
-  data.tar.gz: 40bb387e611607dd18aebeed78ae7946b4a03b6f57f7b3b69dfe9efd74d05abf
+  metadata.gz: 3d4af5366336487b70c0894885b432aef53d24e5e0b5ef383fc17c3e5b68c47f
+  data.tar.gz: c35c0e3e2a246d8ee62ca2f75dc98723dbca65495a3f40c620af31295fba1dd6
 SHA512:
-  metadata.gz: 40e61c0558617201a4d4eaac5baa71d3cbb6035898dc0478ddd9c86e9396eb06ff7f31085d6dde24bd4a3f5c3da6c2fe1d3d394ad3d0fbe0006d4e82a3107157
-  data.tar.gz: 5377db7d4c8006e8eb6e2ab89fd6cf2516f10fe0d4b58563584ec870b9f80fda28475c3a442b2e208d12538897f645df5349042b9c57f3a0561e744762484fb2
+  metadata.gz: bda18ea4b63120d0162453973e11802aa08d81c34f86f9cf7f9fea30e6d1c85ced5f12204d194062fe471d23e416273d2e610b8b785bf2a48c169d3614789f44
+  data.tar.gz: '068828bf2970c33abdfe8e95a149f6383ee82a36c628e4e955b60b666649a1c641500d8f247ae56e4f8949cac4694a1d7b20b31afa61e23e65c2f773f23ea419'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    key_mapable (0.4.0)
+    key_mapable (0.5.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -18,35 +18,139 @@ Or install it yourself as:
 
     $ gem install key_mapable
 
+## A quick example
+
+```ruby
+class Espresso
+  extend KeyMapable
+
+  define_map(:to_h) do
+    key_map(:strength, 'Strength')
+    key_map(:temperature, 'Temperature, transform: ->(value) { value.to_i })
+    key_value('IsHot') { |espresso| espresso.temperature >= 80 }
+    array_key_map(:sips, 'Sips') do
+      key_map(:sipper, 'Sipper')
+      key_map(:temperature, 'Temperature')
+    end
+  end
+end
+```
+
 ## Usage
 
+To map keys from one format to another. You must first extend the `KeyMapable`
+module. This will add the necessary methods to define a map.
+
 ```ruby
-class MyClass
+class Espresso
   extend KeyMapable
+end
+```
 
-  # Define a method called `#to_h` that use the provided map. The keys
-  # will be accessed on the provided subject. Transform the resulting hash
-  # with the provided lambda.
-  define_map(:to_h, resolve: ->(val) { val }, subject: :my_reader) do
-    # Map the value of `#name` to the key 'Name'.
-    key_map(:name, 'Name')
+The `.define_map` method lets you define a method that will return a hash from
+the given map rules defined in the block. The following example will map
+`#strength` to the key `'Strength'` in the hash returned from `#to_h`.
 
-    # Map the value of `#maybe_value` to the key 'GuaranteedValue'.
-    # Transform the value by calling `#to_s` first.
-    key_map(:maybe_value, 'GuaranteedValue', transform: ->(val) { val.to_s })
+```ruby
+class Espresso
+  extend KeyMapable
 
-    # Map the key 'Name' to the value provided by the block.
-    key_value('AConstant') { 'Foo' }
+  attr_accessor :strength
 
-    # Map every item returned from `#rows`.
-    array_key_map(:rows, 'Rows') do
-      # Map the value of `#id` to the key 'Id'.
-      key_map(:id, 'Id')
+  define_map(:to_h) do
+    key_map(:strength, 'Strength')
+  end
+end
+```
+
+You can then use the `#to_h` method like so:
+```ruby
+espresso = Espresso.new
+espresso.strength = 10
+espresso.to_h
+#=> { 'Strength' => 10 }
+```
+
+The map definition can be arbitrarily nested as long as the returned objects
+respond to the described methods.
+```ruby
+define_map(:to_h) do
+  key_map(:manufacturer, 'Manufacturer') do
+    key_map(:location, 'Location') do
+      key_map(:country, 'Country')
     end
   end
 end
 ```
 
+If you wish to transform the value you can provide a third argument which must
+be a lambda and return the transformed value.
+
+```ruby
+define_map(:to_h) do
+  key_map(:temperature, 'Temperature', transform: ->(value) { value.to_i })
+end
+```
+
+You can define a structure for a custom key by using the `#key` method.
+
+```ruby
+define_map(:to_h) do
+  key('Coffee') do
+    key_map(:brand, 'Brand')
+  end
+end
+```
+
+Use `#array_key_map` to define maps over arrays:
+```ruby
+define_map(:to_h) do
+  array_key_map(:sips, 'Sips') do
+    key_map(:sipper, 'Sipper')
+    key_map(:temperature, 'Temperature')
+  end
+end
+```
+
+Use `#key_value` to define a key that will have a manufactured value. The block
+is yielded the subject and must return the manufactured value.
+
+```ruby
+define_map(:to_h) do
+  key_value('IsHot') { |espresso| espresso.temperature >= 80 }
+end
+```
+
+By default the object the keys are read on is the object itself. If you want to
+use another object you can set the `:subject` keyword to a reader method on the
+object.
+
+```ruby
+define_map(:to_h, subject: :my_reader) do
+  # ...
+end
+```
+
+Sometimes you do not want to return a hash. Provide the `:resolve` keyword to
+transform the resulting hash to your own format.
+```ruby
+define_map(:to_h, resolve: ->(value) { OpenStruct.new(value)}) do
+  # ...
+end
+```
+
+If the object itself is an hash you might want to use hash notation to access
+the values. In that case pass `:hash` as the `:access` argument.
+
+```ruby
+define_map(:to_h, access: :hash) do
+  # ...
+end
+```
+
+You can also pass a custom accessor. The accessor must respond to `#access`. It
+will then be passed the subject and key.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/key_mapable.rb

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
 
 require "key_mapable/version"
+require "key_mapable/accessor"
 require "key_mapable/mapper"
 
 module KeyMapable
-  def define_map(method_name, resolve: ->(val) { val }, subject: :itself, &block)
+  def define_map(method_name,
+                 resolve: ->(val) { val },
+                 subject: :itself,
+                 access: :method, &block)
     define_method(method_name) do
       value = public_send(subject)
-      mapper = Mapper.new(value)
+      accessor = Accessor.for(access)
+      mapper = Mapper.new(value, accessor)
       mapper.instance_eval(&block)
       resolve.call(mapper.structure)
     end

data/lib/key_mapable/accessor.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class KeyMapable::Accessor
+  class Method
+    def self.access(subject, key)
+      subject.public_send(key)
+    end
+  end
+
+  class Hash
+    def self.access(subject, key)
+      subject[key]
+    end
+  end
+
+  ACCESSORS = {
+    method: Method,
+    hash: Hash
+  }
+
+  def self.for(accessor_or_name)
+    ACCESSORS.fetch(accessor_or_name, accessor_or_name)
+  end
+end

data/lib/key_mapable/accessor/method.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class KeyMapable::Accessor::Method
+  def self.access(subject, key)
+    subject.public_send(key)
+  end
+end

data/lib/key_mapable/mapper.rb

@@ -2,28 +2,29 @@
 
 # Used internally by the KeyMapable concern.
 class KeyMapable::Mapper
-  attr_reader :subject, :structure
+  attr_reader :subject, :structure, :accessor
 
-  def initialize(subject)
+  def initialize(subject, accessor = KeyMapable::Accessor::Method)
     @subject = subject
     @structure = {}
+    @accessor = accessor
   end
 
   def key_value(key)
-    @structure[key] = yield()
+    @structure[key] = yield(subject)
   end
 
   def key(name, &block)
-    child_mapper = self.class.new(subject)
+    child_mapper = self.class.new(subject, accessor)
     child_mapper.instance_eval(&block)
     @structure[name] = child_mapper.resolve
   end
 
   def key_map(original_key, new_key, transform: ->(val) { val }, &block)
-    original_subject = subject.public_send(original_key)
+    original_subject = access(original_key)
     transformed_subject = transform.call(original_subject)
     if block_given?
-      child_mapper = self.class.new(transformed_subject)
+      child_mapper = self.class.new(transformed_subject, accessor)
       child_mapper.instance_eval &block
       @structure[new_key] = child_mapper.resolve
     else
@@ -32,9 +33,9 @@ class KeyMapable::Mapper
   end
 
   def array_key_map(original_key, new_key, &block)
-    original_subject = subject.public_send(original_key)
+    original_subject = access(original_key)
     @structure[new_key] = original_subject.map do |item|
-      child_mapper = self.class.new(item)
+      child_mapper = self.class.new(item, accessor)
       child_mapper.instance_eval(&block)
       child_mapper.resolve
     end
@@ -43,4 +44,10 @@ class KeyMapable::Mapper
   def resolve
     @structure
   end
+
+  private
+
+  def access(key)
+    accessor.access(subject, key)
+  end
 end

data/lib/key_mapable/version.rb

@@ -1,3 +1,3 @@
 module KeyMapable
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: key_mapable
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Emric
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-01-17 00:00:00.000000000 Z
+date: 2019-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -71,6 +71,8 @@ files:
 - bin/setup
 - key_mapable.gemspec
 - lib/key_mapable.rb
+- lib/key_mapable/accessor.rb
+- lib/key_mapable/accessor/method.rb
 - lib/key_mapable/mapper.rb
 - lib/key_mapable/version.rb
 homepage: https://github.com/istanful/key_mapable