attribute_struct 0.1.8 → 0.2.0

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## v0.2.0
+* Add support for value setting into given context level
+* Add #build helper method
+* Introduce `:value_collapse` option for multi set combination instead of replacement
+* Provide bang suffix aliases
+
 ## v0.1.8
 * Basic (optional) auto camel detection on import
 * Add hash helper methods out to class

data/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+## Branches
+
+### `master` branch
+
+The master branch is the current stable released version.
+
+### `develop` branch
+
+The develop branch is the current edge of development.
+
+## Pull requests
+
+* https://github.com/chrisroberts/attribute_struct/pulls
+
+Please base all pull requests off the `develop` branch. Merges to
+`master` only occur through the `develop` branch. Pull requests
+based on `master` will likely be cherry picked.
+
+## Issues
+
+Need to report an issue? Use the github issues:
+
+* https://github.com/chrisroberts/attribute_struct/issues

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    attribute_struct (0.1.7)
+    attribute_struct (0.1.9)
       hashie (>= 2.0.0)
 
 GEM

data/LICENSE

@@ -0,0 +1,13 @@
+   Copyright 2014 Chris Roberts
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/attribute_struct.gemspec

@@ -5,6 +5,7 @@ Gem::Specification.new do |s|
   s.version = AttributeStruct::VERSION.version
   s.summary = 'Attribute structures'
   s.author = 'Chris Roberts'
+  s.license = 'Apache 2.0'
   s.email = 'chrisroberts.code@gmail.com'
   s.homepage = 'http://github.com/chrisroberts/attribute_struct'
   s.description = 'Attribute structures'

data/lib/attribute_struct/attribute_hash.rb

@@ -5,5 +5,13 @@ class AttributeStruct
   class AttributeHash < ::Hash
     include ::Hashie::Extensions::DeepMerge
     include ::Hashie::Extensions::IndifferentAccess
+
+    def to_hash
+      ::Hash[
+        self.map do |k,v|
+          [k, v.is_a?(::Hash) ? v.to_hash : v]
+        end
+      ]
+    end
   end
 end

data/lib/attribute_struct/attribute_struct.rb

@@ -2,13 +2,15 @@ class AttributeStruct < BasicObject
 
   class << self
 
-    # Global flag for camel cased keys
+    # @return [Truthy, Falsey] global flag for camel keys
     attr_reader :camel_keys
-    # Force tooling from Chef
+    # @return [Truthy, Falsey] force chef tooling (Mash)
     attr_accessor :force_chef
 
-    # val:: bool
     # Automatically converts keys to camel case
+    #
+    # @param val [TrueClass, FalseClass]
+    # @return [TrueClass, FalseClass]
     def camel_keys=(val)
       load_the_camels if val
       @camel_keys = !!val
@@ -22,7 +24,7 @@ class AttributeStruct < BasicObject
       end
     end
 
-    # Determines what hash library to load based on availability
+    # Determine what hash library to load based on availability
     def load_the_hash
       unless(@hash_loaded)
         if(defined?(Chef) || force_chef)
@@ -36,47 +38,97 @@ class AttributeStruct < BasicObject
       end
     end
 
+    # @return [AttributeStruct::AttributeHash, Mash]
     def hashish
       load_the_hash
       @hash_loaded == :chef ? ::Mash : ::AttributeStruct::AttributeHash
     end
 
+    # Create AttributeStruct instance and dump the resulting hash
+    def build(&block)
+      raise ArgumentError.new 'Block required for build!' unless block
+      new(&block)._dump
+    end
+
   end
 
-  # Flag for camel cased keys
+  # @return [Truthy, Falsey] current camelizing setting
   attr_reader :_camel_keys
-
-  def initialize(*args, &block)
+  # @return [AtributeStruct::AttributeHash, Mash] holding space for state
+  attr_reader :_arg_state
+
+  # Create new instance
+  #
+  # @param init_hash [Hash] hash to initialize struct
+  # @yield block to execute within struct context
+  def initialize(init_hash=nil, &block)
     _klass.load_the_hash
     @_camel_keys = _klass.camel_keys
+    @_arg_state = self.class.hashish.new
     @table = __hashish.new
-    unless(args.empty?)
-      if(args.size == 1 && args.first.is_a?(::Hash))
-        _load(args.first)
-      end
+    if(init_hash)
+      _load(init_hash)
     end
     if(block)
       self.instance_exec(&block)
     end
   end
 
-  # val:: bool
-  # Turn camel cased keys on/off
+  # Execute block within current context
+  #
+  # @yield block to execute
+  # @return [Object]
+  def _build(&block)
+    self.instance_exec(&block)
+  end
+
+  # Set state into current context
+  #
+  # @param args [Hashish] hashish type holding data for context
+  # @return [Hashish]
+  def _set_state(args={})
+    _arg_state.merge!(args)
+  end
+
+  # Value of requested state
+  #
+  # @param key [Symbol, String]
+  # @param traverse [TrueClass, FalseClass] traverse towards root for matching key
+  # @return [Object, NilClass]
+  def _state(key, traverse=true)
+    if(_arg_state.keys.include?(key))
+      _arg_state[key]
+    else
+      if(traverse && _parent)
+        _parent._state(key)
+      end
+    end
+  end
+
+  # Enable/disable camel keys
+  #
+  # @param val [TrueClass, FalseClass]
+  # @return [TrueClass, FalseClass]
   def _camel_keys=(val)
     _klass.load_the_camels if val
     @_camel_keys = !!val
   end
 
-  # key:: Object
-  # Access data directly
+  # Direct data access
+  #
+  # @param key [String, Symbol]
+  # @return [Object]
   def [](key)
     _data[_process_key(key)]
   end
 
-  # key:: Object
-  # val:: Object
-  # Directly set val into struct. Useful when key is not valid syntax
-  # for a ruby method
+  # Directly set value into struct. Useful when the key
+  # is not valid ruby syntax for a method
+  #
+  # @param key [String, Symbol]
+  # @param val [Object]
+  # @yield block to execute within context
+  # @return [Object]
   def _set(key, val=nil, &block)
     if(val)
       self.method_missing(key, val, &block)
@@ -84,42 +136,73 @@ class AttributeStruct < BasicObject
       self.method_missing(key, &block)
     end
   end
-
-  # Dragons and unicorns all over in here
+  alias_method :set!, :_set
+
+  # Provides struct DSL behavior
+  #
+  # @param sym [Symbol, String] method name
+  # @param args [Object] argument list
+  # @yield provided block
+  # @return [Object] existing value or newly set value
+  # @note Dragons and unicorns all over in here
   def method_missing(sym, *args, &block)
     if((s = sym.to_s).end_with?('='))
       s.slice!(-1, s.length)
       sym = s
     end
     sym = _process_key(sym)
-    @table[sym] ||= _klass_new
     if(!args.empty? || block)
       if(args.empty? && block)
-        base = @table[sym]
+        if(_state(:value_collapse))
+          orig = @table.fetch(sym, :__unset__)
+        end
+        base = _klass_new
         if(block.arity == 0)
           base.instance_exec(&block)
         else
           base.instance_exec(base, &block)
         end
-        @table[sym] = base
+        if(orig.is_a?(::NilClass))
+          @table[sym] = base
+        else
+          if(orig == :__unset__)
+            @table[sym] = base
+          else
+            orig = [orig] unless orig.is_a?(::Array)
+            orig << base
+            @table[sym] = orig
+          end
+        end
       elsif(!args.empty? && block)
         base = @table[sym]
         base = _klass_new unless base.is_a?(_klass)
-        @table[sym] = base
         leaf = base
+        key = sym
         args.each do |arg|
           leaf = base[arg]
+          key = arg
           unless(leaf.is_a?(_klass))
             leaf = _klass_new
             base._set(arg, leaf)
             base = leaf
           end
         end
+        if(!leaf.nil? && _state(:value_collapse))
+          orig = leaf
+          leaf = orig.parent._klass_new
+        end
         if(block.arity == 0)
           leaf.instance_exec(&block)
         else
           leaf.instance_exec(leaf, &block)
         end
+        if(orig)
+          orig = [orig] unless orig.is_a?(::Array)
+          orig << leaf
+        else
+          orig = leaf
+        end
+        @table[sym] = orig
       else
         if(args.size > 1)
           @table[sym] = _klass_new unless @table[sym].is_a?(_klass)
@@ -131,42 +214,54 @@ class AttributeStruct < BasicObject
           end
           return endpoint # custom break out
         else
-          @table[sym] = args.first
+          if(_state(:value_collapse) && !(leaf = @table[sym]).nil?)
+            leaf = [leaf] unless leaf.is_a?(::Array)
+            leaf << args.first
+            @table[sym] = leaf
+          else
+            @table[sym] = args.first
+          end
         end
       end
     end
+    @table[sym] = _klass_new if @table[sym].nil? && !@table[sym].is_a?(_klass)
     @table[sym]
   end
 
-  # Returns if this struct is considered nil (empty data)
+  # @return [TrueClass, FalseClass] struct is nil (empty data)
   def nil?
     _data.empty?
   end
 
-  # klass:: Class
-  # Returns if this struct is a klass
+  # Determine if self is a class
+  #
+  # @param klass [Class]
+  # @return [TrueClass, FalseClass]
   def is_a?(klass)
     klass.ancestors.include?(_klass)
   end
   alias_method :kind_of?, :is_a?
 
-  # Returns current keys within struct
+  # @return [Array<String,Symbol>] keys within struct
   def _keys
     _data.keys
   end
 
-  # Returns underlying data hash
+  # @return [AttributeStruct::AttributeHash, Mash] underlying struct data
   def _data
     @table
   end
 
-  # key:: Object
-  # Delete entry in struct with key
+  # Delete entry from struct
+  #
+  # @param key [String, Symbol]
+  # @return [Object] value of entry
   def _delete(key)
     _data.delete(_process_key(key))
   end
+  alias_method :delete!, :_delete
 
-  # Dumps the current instance to a Hash
+  # @return [AttributeStruct::AttributeHash, Mash] dump struct to hashish
   def _dump
     processed = @table.map do |key, value|
       if(value.is_a?(::Enumerable))
@@ -183,9 +278,12 @@ class AttributeStruct < BasicObject
     end
     __hashish[*processed.flatten(1)]
   end
+  alias_method :dump!, :_dump
 
-  # hashish:: Hash type object
-  # Clears current instance data and replaces with provided hash
+  # Clear current struct data and replace
+  #
+  # @param hashish [Hash] hashish type instance
+  # @return [self]
   def _load(hashish)
     @table.clear
     if(_root._camel_keys_action == :auto_discovery)
@@ -213,11 +311,13 @@ class AttributeStruct < BasicObject
     self
   end
 
-  # target:: AttributeStruct
-  # Performs a deep merge and returns the resulting AttributeStruct
-  def _merge(target)
+  # Perform deep merge
+  #
+  # @param overlay [AttributeStruct]
+  # @return [AttributeStruct] newly merged instance
+  def _merge(overlay)
     source = _deep_copy
-    dest = target._deep_copy
+    dest = overlay._deep_copy
     if(defined?(::Chef))
       result = ::Chef::Mixin::DeepMerge.merge(source, dest)
     else
@@ -226,21 +326,26 @@ class AttributeStruct < BasicObject
     _klass.new(result)
   end
 
-  # target:: AttributeStruct
-  # Performs a deep merge and updates the current instance with the
-  # resulting value
-  def _merge!(target)
-    result = _merge(target)._dump
+  # Perform deep merge in place
+  #
+  # @param overlay [AttributeStruct]
+  # @return [self]
+  def _merge!(overlay)
+    result = _merge(overlay)._dump
     _load(result)
     self
   end
 
-  # Returns a new Hash type instance based on what is available
+  # @return [Class] hashish type available
   def __hashish
     defined?(::Chef) ? ::Mash : ::AttributeStruct::AttributeHash
   end
 
-  # Returns dup of value. Converts Symbol objects to strings
+  # Provide dup of instance
+  #
+  # @param v [Object]
+  # @return [Object] duped instance
+  # @note if Symbol provided, String is returned
   def _do_dup(v)
     begin
       v.dup
@@ -249,8 +354,10 @@ class AttributeStruct < BasicObject
     end
   end
 
-  # thing:: Object
-  # Returns a proper deep copy
+  # Create a "deep" copy
+  #
+  # @param thing [Object] struct to copy. defaults to self
+  # @return [Object] new instance
   def _deep_copy(thing=nil)
     thing ||= _dump
     if(thing.is_a?(::Enumerable))
@@ -264,8 +371,11 @@ class AttributeStruct < BasicObject
     val
   end
 
-  # key:: String or Symbol
-  # Processes the key and returns value based on current settings
+  # Provide expected key format based on context
+  #
+  # @param key [String, Symbol]
+  # @param args [Object] argument list (:force will force processing)
+  # @return [String, Symbol]
   def _process_key(key, *args)
     key = key.to_s
     if(_camel_keys && _camel_keys_action)
@@ -288,14 +398,16 @@ class AttributeStruct < BasicObject
       key
     end
   end
+  alias_method :process_key!, :_process_key
 
-  # Helper to return class of current instance
+  # @return [Class] this class
   def _klass
     ::AttributeStruct
   end
   alias_method :class, :_klass
 
-  # Helper to return new instance of current instance type
+  # @return [AttributeStruct] new struct instance
+  # @note will set self as parent and propogate camelizing status
   def _klass_new
     n = _klass.new
     unless(_camel_keys_action == :auto_discovery)
@@ -306,22 +418,26 @@ class AttributeStruct < BasicObject
     n
   end
 
-  # v:: Symbol (:auto_disable, :auto_enable)
-  # Sets custom rule for processed keys
+  # Set custom rule for processed keys at this context level
+  #
+  # @param v [Symbol] :auto_disable or :auto_enable
+  # @return [Symbol]
   def _camel_keys_set(v)
     @_camel_keys_set = v
   end
 
-  # Returns value set via #_camel_keys_set
+  # @return [Symbol, NilClass] :auto_disable or :auto_enable
   def _camel_keys_action
     @_camel_keys_set
   end
 
+  # @return [AttributeStruct, NilClass] parent of this struct
   def _parent(obj=nil)
     @_parent = obj if obj
     @_parent
   end
 
+  # @return [AttributeStruct, NilClass] root of the struct or nil if self is root
   def _root
     r = self
     until(r._parent.nil?)
@@ -330,10 +446,10 @@ class AttributeStruct < BasicObject
     r
   end
 
-  # args:: Objects
-  # Helper to create Arrays with nested AttributeStructs. Proc
-  # instances are automatically executed into new AttributeStruct
-  # instances
+  # Create an Array and evaluate discovered AttributeStructs
+  #
+  # @param args [Object] array contents
+  # @return [Array]
   def _array(*args)
     args.map do |maybe_block|
       if(maybe_block.is_a?(::Proc))
@@ -349,5 +465,6 @@ class AttributeStruct < BasicObject
       end
     end
   end
+  alias_method :array!, :_array
 
 end

data/lib/attribute_struct/monkey_camels.rb

@@ -5,7 +5,7 @@ module MonkeyCamels
       klass.class_eval do
 
         include Humps
-        
+
         alias_method :un_camel_to_s, :to_s
         alias_method :to_s, :camel_to_s
         alias_method :un_camel_initialize_copy, :initialize_copy
@@ -14,27 +14,36 @@ module MonkeyCamels
     end
   end
 
+  # Create a camel copy based on settings
+  #
+  # @return [String]
   def camel_initialize_copy(orig)
     new_val = un_camel_initialize_copy(orig)
     orig._camel? ? new_val : new_val._no_hump
   end
-  
+
+  # Provide string formatted based on hump setting
+  #
+  # @return [String]
   def camel_to_s
     val = un_camel_to_s
     _camel? ? val : val._no_hump
   end
 
   module Humps
-    
+
+    # @return [TrueClass, FalseClass] camelized
     def _camel?
       !@__not_camel
     end
 
+    # @return [self] disable camelizing
     def _no_hump
       @__not_camel = true
       self
     end
 
+    # @return [self] enable camelizing
     def _hump
       @__not_camel = false
       self
@@ -48,7 +57,7 @@ end
 String.send(:include, MonkeyCamels)
 Symbol.send(:include, MonkeyCamels)
 
-# Specialized type
+# Specialized String type
 class CamelString < String
   def initialize(val=nil)
     super

data/lib/attribute_struct/version.rb

@@ -1,8 +1,9 @@
 require 'attribute_struct/attribute_struct'
 
 class AttributeStruct
+  # Custom version container
   class Version < ::Gem::Version
   end
-
-  VERSION = Version.new('0.1.8')
+  # Current library version
+  VERSION = Version.new('0.2.0')
 end

data/test/specs/collapse.rb

@@ -0,0 +1,80 @@
+require 'minitest/autorun'
+
+describe AttributeStruct do
+  describe 'Collapse' do
+    describe 'direct value set' do
+
+      describe 'When values are not collapsed' do
+        before do
+          @struct = AttributeStruct.new
+          @struct.direct.assignment 1
+          @struct.direct.assignment 2
+          @dump = @struct._dump
+        end
+
+        it 'should return last set value' do
+          @dump['direct']['assignment'].must_equal 2
+        end
+      end
+
+      describe 'When values are collapsed' do
+        before do
+          @struct = AttributeStruct.new
+          @struct._set_state(:value_collapse => true)
+          @struct.direct.assignment 1
+          @struct.direct.assignment 2
+          @dump = @struct._dump
+        end
+
+        it 'should return both assigned values as an array' do
+          @dump['direct']['assignment'].must_equal [1,2]
+        end
+      end
+
+    end
+
+    describe 'block value set' do
+
+      describe 'When values are not collapsed' do
+        before do
+          @struct = AttributeStruct.new
+          @struct.direct do
+            assignment true
+          end
+          @struct.direct do
+            assignment false
+          end
+          @dump = @struct._dump
+        end
+
+        it 'should return last set value' do
+          @dump['direct']['assignment'].must_equal false
+        end
+
+      end
+
+      describe 'When values are collapsed' do
+        before do
+          @struct = AttributeStruct.new
+          @struct._set_state(:value_collapse => true)
+          @struct.direct do
+            assignment true
+          end
+          @struct.direct do
+            assignment false
+          end
+          @dump = @struct._dump
+        end
+
+        it 'should return both assigned values as an array' do
+          @dump['direct'].must_equal [
+            {'assignment' => true},
+            {'assignment' => false}
+          ]
+        end
+
+      end
+
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: attribute_struct
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-31 00:00:00.000000000 Z
+date: 2014-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -42,13 +42,17 @@ files:
 - test/specs/camel.rb
 - test/specs/merging.rb
 - test/specs/basic.rb
+- test/specs/collapse.rb
 - Gemfile
 - README.md
+- LICENSE
 - attribute_struct.gemspec
 - CHANGELOG.md
+- CONTRIBUTING.md
 - Gemfile.lock
 homepage: http://github.com/chrisroberts/attribute_struct
-licenses: []
+licenses:
+- Apache 2.0
 post_install_message: 
 rdoc_options: []
 require_paths: