kv_accessor 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cd61aa81ee2bcd6db26543b002c1916d366a1738
-  data.tar.gz: 2c2095c33a8d941b8c3d5325d9555e1bf5cfc455
+  metadata.gz: a9825ad1d5e43106077b0948d9a7338ea0702554
+  data.tar.gz: f457ccbc9724f7e90ade499797c94c7d52ef7941
 SHA512:
-  metadata.gz: 43edfb17fa1d2e34ade55e2a7b909ca6a8bfa7bcd2d788daff5c8d5f049227a85cdc72c1abea050476ea0add7b657e37ac1155653867f657479a30937fc932da
-  data.tar.gz: 6d2fa5e256730c6d25869499be0a30e1461b14dc0a96a0a810706912642e7d94c58dacee498e2db4b44d2dd12737eab0438431b294e26616309344acf1c8b734
+  metadata.gz: d16a8b478d0431850f57dfab61efa763b99c5fa337dec5d13ba8093d9e8bce5c58af3c435e682b802475895de509134510858b0d463e6afbf06d9d5d16093b72
+  data.tar.gz: ed2ca4e9fe6f37f040e562f3238307b1f4261a34300402bf24a4a3bcc0d526bfc7269e0521e28b26bb2735dc5aa5de9ec433089b107e9893cb0fe6fb97f7f5e2

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## 0.1.1 - 2016-03-28
+### Added
+- README.md and CHANGELOG.md content.
+
+### Changed
+- `KvAccessor.kv_accessor`/`.kv_reader`/`.kv_writer` now return the hash of
+  `accessor_name => key` to have more meaning.
+- Refactored/edited some of the specs.
+
+### Fixed
+- Some of the documentation
+
+[Unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...HEAD

data/README.md

@@ -0,0 +1,221 @@
+KvAccessor
+==========
+
+Define reader and writer accessor methods for an attribute/method that quacks
+like a Hash (`respond_to?(:[])`).
+
+```ruby
+class MyCar
+  extend KvAccessors
+  attr_accessor :details
+
+  kv_accessor :details, :make, 'model'
+
+  def initialize(details = {})
+    self.details = details
+  end
+end
+
+car = MyCar.new(:make => 'Chevrolet', 'model' => 'Camaro')
+car.make #=> "Chevrolet"
+car.model #=> "Camaro"
+```
+
+Installation
+------------
+
+Gem
+
+```terminal
+$ gem install kv_accessor
+```
+
+Bundler
+
+```ruby
+gem 'kv_accessor'
+```
+
+Usage
+-----
+
+Easily encapsulate Hash like objects.
+
+The reader/writer can be named separately from the `#[]`/`#[]=` key via an
+alias_accessors argument (this allows for aliasing of complex keys or class
+differences like Symbol vs. String).
+
+No initializer is implemented, so any needed initialization is up to the owner.
+
+A word of warning: `#inspect` is called on the `:[]` key the implimentation is
+via `class_eval`. `#to_s` is called on the passed `method` name and the method
+is called without regard to the receiver (eg. a Kernel method can be called
+if no instance method overrides it).
+
+No guarding against user input exists. Only values should come from user input.
+
+Meant as a DSL for creating value style objects that encapsulate a Hash object
+so as to avoid inheriting from Hash/OpenStruct. Take a look at Struct,
+OpenStruct, and [Virtus](https://github.com/solnic/virtus) for alternatives with
+other features.
+
+An extended example:
+
+```ruby
+class MyCar
+  attr_accessor :details
+  extend KvAccessors
+
+  kv_accessor :details, :make, :year => 'model_year',
+              :blue_interior_cost => { 'leather' => 'blue' }
+  kv_reader :details, 'model', :ac?, :seats
+  kv_writer :details, 'price'
+
+  def initialize(details = {})
+    self.details = details
+  end
+end
+
+c = MyCar.new(:make => 'Chevrolet', 'model' => 'Camaro', 'model_year' => 1967,
+              'submodel' => 'SS', 'price' => 20_000.00, :ac? => true,
+	      :seats => 4, { 'leather' => 'blue' } => 2_000.00)
+c.make
+#=> "Chevrolet"
+c.model
+#=> "Camaro"
+
+# Even though the 'submodel' is a part of 'details', all the attributes need to
+# be specified.
+c.submodel
+#=> NoMethodError
+
+# '#model' was defined as a kv_reader only
+c.model = 'Corvette'
+#=> NoMethodError
+
+# Full on accessor
+c.year
+#=> 1967
+c.year = 1968
+#=> 1968
+c.year
+#=> 1968
+c.details['model_year']
+#=> 1968
+
+# Using a complex key with alias.
+# This example is a little contrived, but this has plenty of uses, like using
+# classes as keys.
+# This example key lookup would be:
+# 'details[{ 'leather' => 'blue' }]'
+c.blue_interior_cost
+#=> 2_000.00
+c.blue_interior_cost = 4_000.00
+#=> 4_000.00
+c.details[{ 'leather' => 'blue' }]
+#=> 4_000.00
+
+# kv_writer with no reader present
+c.price
+#=> NoMethodError
+c.price = 25_000.00
+#=> 25_000.00
+c.details['price']
+#=> 25_000.00
+
+c.details
+#=> { :make => "Chevrolet", "model" => "Camaro", "model_year" => 1967,
+#     "submodel" => "SS", { "leather" => "blue" } => 4_000.00,
+#     "price" => 25_000.00}
+```
+
+Can be used for whatever attributes respond to '#[]'/'#[]='.
+
+```ruby
+class Employee < ActiveRecord::Base
+  store :settings, coder: JSON
+  has_one :office
+  extend KvAccessors
+
+  # Could just use a normal delegator here, but this shows any object with a
+  # '#[]'/'#[]=' can work since ActiveRecord models define a '#[]' interface
+  # for their columns.
+  kv_reader :office, 'chair', 'table'
+
+  # Define for as many attributes as you like
+  kv_accessor :settings, 'wallpaper', :language
+
+  after_initialize { settings ||= {} }
+end
+
+c = Employee.new
+
+# Since an '#office' hasn't been assigned yet, this will try to call '#[]' on
+# nil. Best to always set a default like 'settings' in 'after_initialize'.
+c.chair
+#=> NoMethodError
+
+c.office = Office.new(chair: true, table: false)
+c.chair
+#=> true
+
+c.wallpaper = 'birdy'
+```
+
+Since the kv_accessor/reader/writer methods return a hash, an easy pattern to
+manage the accessors during runtime would be to assign the result to a const.
+
+```ruby
+class MyCar
+  extend KvAccessors
+
+  attr_accessor :details
+
+  # The kv_* methods return a hash of 'attribute_name => key' for convenience.
+  # I like to use this to easily filter out keys in the initializer.
+  SERIALIZABLE_ACCESSORS =
+    kv_accessor :details, :make, :year => 'model_year',
+                :blue_interior_cost => { 'leather' => 'blue' }
+
+  SERIALIZABL_READERS = SERIALIZABLE_ACCESSORS.merge(
+    kv_writer :details, 'model'
+  )
+
+  SERIALIZABLE_WRITERS = SERIALIZABLE_ACCESSORS.merge(
+    kv_writer :details, 'price'
+  )
+
+  def initialize(details = {})
+    self.details = details
+  end
+
+  def serializable_hash
+    ACCESSORS.merge(READERS).merge(WRITERS)
+      .map { |name, key| [name.to_s, details[key]] }.to_h
+  end
+end
+
+c = Car.new(:make => 'Chevrolet', 'model' => 'Camaro', 'model_year' => 1967,
+            'submodel' => 'SS', 'price' => 25_000.00,
+            { 'leather' => 'blue' } => 4000.00)
+
+c.serializable_hash
+#=> { "make" => "Chevrolet", "model" => "Camaro", "year" => 1967,
+#     "blue_interior_cost" => 4000.00, "price" => 25_000.00}
+```
+
+Resources
+---------
+
+[rubydoc.info documentation](http://www.rubydoc.info/gems/kv_accessor)
+
+Contributing
+------------
+
+Normal github PR flow.
+
+
+LICENSE
+-------
+
+3 Clause BSD

data/lib/kv_accessor.rb

@@ -1,9 +1,9 @@
 # Define reader and writer accessors for a Hash like instance method.
 #
 # Define reader and writer methods for a method returning a duck that quacks
-# like a Hash (`respond_to?(:[]`). The reader/writer can be named separately
-# from the ':[]' key via the alias_accessors argument (this allows for aliasing
-# of complex keys).
+# like a Hash (`respond_to?(:[])`). The reader/writer can be named separately
+# from the '#[]'/'#[]=' key via the alias_accessors argument (this allows for
+# aliasing of complex keys or types).
 #
 # A word of warning: '#inspect' is called on the ':[]' key,
 # '#to_s' is called on the 'key' name and the implimentation is via
@@ -11,8 +11,10 @@
 # is called without regard to the receiver (eg. a Kernel method can be called
 # if no instance method overrides it).
 #
-# This is purely meant to be a DSL for creating value style objects. Take a look
-# at Struct, OpenStruct, and Virtus before choosing this.
+# Meant as a DSL for creating value style objects that encapsulate a Hash object
+# so as to avoid hacks like inheriting from Hash/OpenStruct. Take a look at
+# Struct, OpenStruct, and [Virtus](https://github.com/solnic/virtus) for
+# alternatives with other features.
 #
 # @example
 #   class MyCar
@@ -20,7 +22,7 @@
 #     extend KvAccessors
 #     kv_accessor :details, :make, year: 'model_year',
 #                 options: { 'leather' => 'blue' }
-#     kv_reader 'model'
+#     kv_reader :details, 'model'
 #
 #     def initialize(details = {})
 #       @details = details
@@ -96,28 +98,42 @@ module KvAccessor
   #   c.details
   #   #=> { :make => "Chevrolet", "model" => "Camaro", :model_year => 1968,
   #   #     "submodel" => "SS"
+  #
+  # @param keys [#to_s] used for both the key and the attribute name
+  # @param aliased_accessors [Hash< #to_s, #inspect >] the key of
+  #   aliased_accessors is used as the attribute method name and the value of
+  #   aliased_accessors is used as the first argument to `#[]`/`#[]=` off
+  #   `method`
+  #
+  # @return [Hash] all the attribute name => method[key] so this method can be
+  #   meaningfully chained.
+  #   @example
+  #     class Employee
+  #       attr_accessor :info
+  #       ATTRIBUTES = kv_accessor :info, :ssid, :dob
+  #
+  #       def initalize(info)
+  #         self.info = info.select { |k, v| ATTRIBUTES.key?(k) }
+  #       end
+  #     end
   def kv_accessor(method, *keys, **aliased_accessors)
-    kv_reader(method, *keys, **aliased_accessors)
-    kv_writer(method, *keys, **aliased_accessors)
+    kv_reader(method, *keys, **aliased_accessors).merge(
+      kv_writer(method, *keys, **aliased_accessors)
+    )
   end
 
   # Define reader accessors for a Hash like instance method.
   #
-  # Define reader accessor methods for each +keys+. Accessors named other than
-  # the key name can be defined via +aliased_accessors+. Calls to +name+ will
-  # call ':[]' on +method+ with either +key+ or the value described via
-  # +aliased_accessors+.
-  #
-  # See the overall {KvAccessors} docs for a better definition of what gets
-  # called on what.
-  #
-  # This is not guarded against any sort of user input. You have been warned.
+  # Define reader accessor methods for each keys+. Accessors named other than
+  # the key name can be defined via +aliased_accessors+. Calls to either a
+  # +keys+ attribute name or the key of +aliased_accessor+ will call ':[]' off
+  # of +method+ with either +key+ or the value described via +aliased_accessors+.
   #
   # @example
   #   class MyCar
   #     attr_accessor :details
   #     extend KvAccessors
-  #     kv_accessor :details, :make, 'model', year: :model_year
+  #     kv_reader :details, :make, 'model', year: :model_year
   #
   #     def initialize(details = {})
   #       @details = details
@@ -129,12 +145,40 @@ module KvAccessor
   #   c.make #=> "Chevrolet"
   #   c.model #=> "Camaro"
   #   c.year #=> 1967
-  #   c.year = 1968
-  #   c.year #=> 1968
+  #   c.year = 1968 #=> NoMethodError
   #   c.submodel #=> NoMethodError
   #   c.details
-  #   #=> { :make => "Chevrolet", "model" => "Camaro", :model_year => 1968,
+  #   #=> { :make => "Chevrolet", "model" => "Camaro", :model_year => 1967,
   #         "submodel" => "SS" }
+  #
+  # See the overall {KvAccessors} docs for a better definition of what gets
+  # called on what.
+  #
+  # This is not guarded against any sort of user input. You have been warned.
+  #
+  # @see kv_accessor
+  #
+  # @param keys [#to_s] used for both the key and the attribute name
+  # @param aliased_accessors [Hash< #to_s, #inspect >] the key of
+  #   aliased_accessors is used as the attribute method name and the value of
+  #   aliased_accessors is used as the argument to `#[]` off `method`
+  #
+  # @return [Hash] all the attribute name => method[key] so this method can be
+  #   meaningfully chained.
+  #   @example
+  #     class Employee
+  #       attr_accessor :info
+  #       ATTRIBUTES = kv_reader :info, :ssid, :birth
+  #
+  #       def initalize(info)
+  #         self.info = info.select { |k, v| ATTRIBUTES.key?(k) }
+  #       end
+  #     end
+  #     employee = Employee.new(ssid: '123-456-7890', birth: '1979-06-23',
+  #                             eye_color: 'brown')
+  #     employee.birth #=> '1979-06-23'
+  #     employee.info
+  #     #=> { ssid: '123-456-7890', birth: '1979-06-23' }
   def kv_reader(method, *keys, **aliased_accessors)
     accessors = Hash[keys.map { |v| [v, v] }].merge(aliased_accessors)
     accessors.each do |name, key|
@@ -157,15 +201,11 @@ module KvAccessor
   # Define writter accessors for a Hash like instance method.
   #
   # Define writter accessor methods for each +keys+. Accessors named other than
-  # the key name can be defined via +aliased_accessors+. Calls to +name+ will
-  # call ':[]' on +method+ with either +key+ or the value described via
+  # the key name can be defined via +aliased_accessors+. Calls to either a
+  # +keys+ attribute name or the key of +aliased_accessor+ will call '#:[]=' off
+  # of +method+ with either +key+ or the value described via
   # +aliased_accessors+.
   #
-  # See the overall {KvAccessors} docs for a better definition of what gets
-  # called on what.
-  #
-  # This is not guarded against any sort of user input. You have been warned.
-  #
   # @example
   #   class MyCar
   #     attr_accessor :details
@@ -193,6 +233,36 @@ module KvAccessor
   #   c.details
   #   #=> { :make => "Chevrolet", "model" => "Corvette", :model_year => 1968,
   #   #     "submodel" => "SS"
+  #
+  # See the overall {KvAccessors} docs for a better definition of what gets
+  # called on what.
+  #
+  # This is not guarded against any sort of user input. You have been warned.
+  #
+  # @see kv_accessor
+  #
+  # @param keys [#to_s] used for both the key and the attribute name
+  # @param aliased_accessors [Hash< #to_s, #inspect >] the key of
+  #   aliased_accessors is used as the attribute method name and the value of
+  #   aliased_accessors is used as the argument to `#[]=` off `method`
+  #
+  # @return [Hash] all the attribute name => method[key] so this method can be
+  #   meaningfully chained.
+  #   @example
+  #     class Employee
+  #       attr_accessor :info
+  #       ATTRIBUTES = kv_writer :info, :ssid, :birth
+  #
+  #       def initalize(info)
+  #         self.info = info.select { |k, v| ATTRIBUTES.key?(k) }
+  #       end
+  #     end
+  #
+  #     employee = Employee.new(ssid: '123-456-7890', birth: '1979-06-23',
+  #                             eye_color: 'brown')
+  #     employee.ssid = '555-555-5555'
+  #     employee.info
+  #     #=> { ssid: '555-555-5555', birth: '1979-06-23' }
   def kv_writer(method, *keys, **aliased_accessors)
     accessors = Hash[keys.map { |v| [v, v] }].merge(aliased_accessors)
     accessors.each do |name, key|

data/lib/kv_accessor/version.rb

@@ -1,3 +1,3 @@
 module KvAccessor
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/spec/lib/kv_accessor_spec.rb

@@ -16,12 +16,21 @@ RSpec.describe KvAccessor do
       attr_accessor :details, :other
       extend KvAccessor
 
-      kv_accessor :details, :make, year: 'model_year',
-                  blue_interior: { 'leather' => 'blue' }
-      kv_reader :details, 'model', :price
-      kv_writer :details, 'color', :price
+      # The self is required for consts in anonymous classes.
+      self::DETAILS_ACCESSORS =
+        kv_accessor :details, :make, year: 'model_year',
+                    blue_interior: { 'leather' => 'blue' }
 
-      kv_accessor :other, :upc
+      self::DETAILS_READERS = self::DETAILS_ACCESSORS.merge(
+        kv_reader :details, 'model', :price
+      )
+
+      self::DETAILS_WRITERS = self::DETAILS_ACCESSORS.merge(
+        kv_writer :details, 'color', :price
+      )
+
+      self::OTHER_ACCESSORS =
+        kv_accessor :other, :upc
 
       def initialize(details, other)
         self.details = details
@@ -33,46 +42,74 @@ RSpec.describe KvAccessor do
   # For the expect to change, the duping is somehow necessary
   subject(:data_object) { kv_class.new(default_details.dup, default_other.dup) }
 
-  it 'responds to all the accessor names' do
+  it 'responds to all the accessor names specified' do
     expect(data_object).to respond_to(:make, :year, :blue_interior, :make=,
                                       :year=, :blue_interior=, :model, :price,
                                       :color=, :price=, :upc)
   end
 
-  it 'does not respond to unspecified accessor names' do
+  it 'does not respond to unspecified readers/writers' do
     expect(data_object).not_to respond_to(:submodel, :model=)
   end
 
-  it 'has all of the corresponding reader attributes' do
+  it 'fetches all corresponding reader attributes' do
     expect(data_object).to have_attributes(
       make: 'Chevrolet', model: 'Camaro', blue_interior: 2_000.00,
       price: 40_000.00, year: 1967, upc: '808'
     )
   end
 
-  it 'updates only the explicit keys on attribute assignment' do
-    # There's some funky stuff going on with the ordering between `from()`,
-    # `change { }`, and `expect { }`. `change { }.from` doesn't seem to compare
-    # the objects first, before running the expect statement. I think it only
-    # saves the initial output, runs the expect statement, runs the change block
-    # again, and then finally compares the results. So any order dependent
-    # results need to be another copy.
-    expect {
+  describe 'attribute assignment' do
+    before do
       data_object.make = 'Ford'
       data_object.price = 41_000.00
       data_object.year = 1968
       data_object.blue_interior = 3_000.00
       data_object.color = 'red'
       data_object.upc = '809'
-    }.to change { data_object.details }.from(
-      default_details
-    ).to(
-      default_details.merge(
-        :make => 'Ford', :price => 41_000.00, 'model_year' => 1968,
-        'color' => 'red', { 'leather' => 'blue' } => 3_000.00,
+    end
+
+    it 'updates the specified key-value objects' do
+      expect(data_object).to have_attributes(
+        details: default_details.merge(:make => 'Ford', :price => 41_000.00,
+                                       'model_year' => 1968, 'color' => 'red',
+                                       { 'leather' => 'blue' } => 3_000.00),
+        other: { upc: '809' }
       )
-    ).and change { data_object.other }.from(
-      default_other
-    ).to(upc: '809')
+    end
+
+    it 'all the updates are available via the attribute methods' do
+      expect(data_object).to have_attributes(
+        make: 'Ford', price: 41_000.00, year: 1968, blue_interior: 3_000.00,
+        upc: '809'
+      )
+    end
+  end
+
+  describe '.kv_accessor' do
+    it 'returns the hash of attributes for the kv_accessor' do
+      expect(
+        Class.new { extend KvAccessor }
+          .kv_accessor(:attributes, :mayonnaise, year: 'release date')
+      ).to eq(mayonnaise: :mayonnaise, year: 'release date')
+    end
+  end
+
+  describe '.kv_reader' do
+    it 'returns the hash of attributes for the kv_reader' do
+      expect(
+        Class.new { extend KvAccessor }
+          .kv_reader(:attributes, :iscariot, release: 'born')
+      ).to eq(iscariot: :iscariot, release: 'born')
+    end
+  end
+
+  describe '.kv_writer' do
+    it 'returns the hash of attributes for the kv_writer' do
+      expect(
+        Class.new { extend KvAccessor }
+          .kv_writer(:attributes, :adore, vocals: 'singers')
+      ).to eq(adore: :adore, vocals: 'singers')
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kv_accessor
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Jeremiah McCann
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-28 00:00:00.000000000 Z
+date: 2016-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -65,3 +65,4 @@ summary: Generate accessor methods for an indexed object
 test_files:
 - spec/lib/kv_accessor_spec.rb
 - spec/spec_helper.rb
+has_rdoc: