skn_utils 1.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a4bd06660f0cfd6c83198afffde3139c97b65188
+  data.tar.gz: 483673c80d6f9e3c0217dd74b21b7b05b69bc1e8
+SHA512:
+  metadata.gz: a11b5159b5108a8c2aa6174912023f17d9bca2f085f703ba26805589186af0ec8bdf705e45f1ad4416f8c11eddc9fc1590fa27dd027e642cc7ed9b45797f4711
+  data.tar.gz: c5de9340f8529b1a83c05dfcc9848dc8f2deb29a21c81edf9cabea72a0c71f810ceac7d44f39c9b7be2731eaadc136682cba8994e528267444b8b875b398f953

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+/vendor/

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in skn_utils.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 James Scott, Jr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 James Scott Jr
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,221 @@
+# SknUtils 
+Rails Gem containing a Ruby PORO (Plain Old Ruby Object) that can be instantiated at runtime with an input hash.  This library creates an Object with instance variables and associated getters and setters for Dot or Hash notational access to each instance variable.  Additional instance variables can be added post-create by 'obj.my_new_var = "some value"', or simply assigning it.  
+
+
+The intent of this component is to be a container of data results, with easy access to its contents with on-demand transformation to hash, xml, or json. 
+
+* If the key's value is also a hash, it too can optionally become an Object.
+* if the key's value is a Array of Hashes, each element of the Array can optionally become an Object.
+  
+  This nesting action is controlled by the value of the options key ':depth'. 
+    The key :depth defaults to :multi, an has options of :single, :multi, or :multi_with_arrays
+  
+  The ability of the resulting Object to be Marshalled(dump/load) can be preserved by merging configuration options 
+    into the input params key ':enable_serialization' set to true.  It defaults to false for speed purposes
+ 
+
+### Configuration Options
+--------------------------------
+
+    :enable_serialization = false     -- [ true | false ], for speed, omits creation of attr_accessor
+    :depth = :multi                   -- [ :single | :multi | :multi_with_arrays ]
+
+### Public Components
+--------------------------------
+
+    Inherit from NestedResultBase or instantiate an pre-built Class:
+      SknUtils::GenericBean              # => Serializable, includes attr_accessors, and follows hash values only.
+      SknUtils::PageControls             # => Serializable, includes attr_accessors, and follows hash values and arrays of hashes.
+      SknUtils::ResultBean               # => Not Serializable, includes attr_accessors, and follows hash values only.
+      SknUtils::ResultsBeanWithErrors    # => Same as ResultBean with addition of ActiveModel::Errors object.
+    or Include AttributeHelpers          # => Add getter/setters, and hash notation access to instance vars of any object.
+
+
+## Basic features include:
+```ruby
+ - provides the hash or dot notation methods of accessing values from object created; i.e
+     'obj = ResultBean.new({value1: "some value", value2: {one: 1, two: "two"}}) 
+     'x = obj.value1' or 'x = obj.value2.one'
+     'x = obj["value1"]'
+     'x = obj[:value1]'
+
+ - enables serialization by avoiding the use of ''singleton_class'' methods which breaks Serializers:
+    Serializer supports xml, json, hash, and standard Marshall''ing
+
+    person = PageControls.new({name: "Bob"})
+    person.attributes          # => {"name"=>"Bob"}
+    person.serializable_hash   # => {"name"=>"Bob"}
+    person.to_hash             # => {"name"=>"Bob"}
+    person.to_json             # => "{\"name\":\"Bob\"}"
+    person.to_xml              # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<page-controls>\n  <name>Bob</name>\n</page-controls>\n"
+    dmp = Marshal.dump(person) # => "\x04\bo:\x1ASknUtils::PageControls\x06:\n@nameI\"\bBob\x06:\x06ET"
+    person = Marshal.load(dmp) # => #<SknUtils::PageControls:0x007faede906d40 @name="Bob">
+
+    ***GenericBean designed to automatically handle the setup for serialization and multi level without arrays 
+
+ - post create additions:
+    'obj = ResultBean.new({value1: "some value", value2: {one: 1, two: "two"}}) 
+    'x = obj.one'                          --causes NoMethodError
+    'x = obj.one = 'some other value'      --creates a new instance value with accessors
+    'x = obj.one = {key1: 1, two: "two"}'  --creates a new ***bean as the value of obj.one
+    'y = obj.one.two'                      --returns "two"
+    'y = obj.one[:two]                     --returns "two"
+    'y = obj.one['two']                    --returns "two"
+
+ - supports predicates <attr>? and clear_<attr>? method patterns:	
+    'obj = PageControls.new({name: "Something", phone: "2609998888"})'
+    'obj.name?'       # => true    true or false, like obj.name.present?
+    'obj.clear_name'  # => nil     sets :name to nil
+```
+
+The combination of this NestedResultBase(dot notation class) and AttributeHelpers(hash notation module), produces this effect given the same params hash:
+
+    {:depth => <select>, ...}  Input Hash                        Basic dot notation: effect of :depth
+    ----------------------------------------------------      ---------------------------------
+
+(DOES NOT FOLLOW Values) :depth => :single
+```ruby
+    * params = {one: 1,                                         drb.one      = 1
+                two: { one: 1,                                  drb.two      = {one: 1, two: 'two}
+                       two: "two"                               drb.two.two  = NoMethodError
+                     }, 
+                three: [ {one: 'one', two: 2},                  drb.three    = [{one: 'one', two: 2},{three: 'three', four: 4}]
+                         {three: 'three', four: 4}              drb.three[1] = {three: 'three', four: 4}
+                       ]                                        drb.three[1].four = NoMethodError
+               }      
+```
+
+(Follow VALUES that are Hashes only.) :depth => :multi
+```ruby
+    * params = {one: 1,                                         drb.one      = 1
+                two: { one: 1,                                  drb.two.one  = 1
+                	   two: "two"                               drb.two.two  = 'two'
+                     }, 
+                three: [ {one: 'one', two: 2},                  drb.three    = [{one: 'one', two: 2},{three: 'three', four: 4}]
+                         {three: 'three', four: 4}              drb.three[1] = {three: 'three', four: 4}
+                       ]                                        drb.three[1].four = NoMethodError
+	           }
+```
+ 
+(Follow VALUES that are Hashes and/or Arrays of Hashes) :depth => :multi_with_arrays
+```ruby
+    * params = {one: 1,                                         drb.one      = 1
+                two: { one: 1,                                  drb.two.one  = 1
+                       two: "two"                               drb.two.two  = 'two'
+                     }, 
+                three: [ {one: 'one', two: 2},                  drb.three.first.one = 'one'
+                		 {three: 'three', four: 4}              drb.three[1].four   = 4
+                       ]
+               }      
+ 
+```
+# Usage Examples: SubClassing 
+
+(DOES NOT FOLLOW Values)
+```ruby
+       class SmallPackage < NestedResultBase
+          def initialize(params={})
+            super( params.merge({depth: :single}) )    # override default of :multi level
+          end
+       end
+```
+
+(Follow VALUES that are Hashes only.)
+```ruby
+       class ResultBean < NestedResultBase
+          # defaults to :multi level
+       end
+       
+    -- or --
+    
+       class ResultBean < NestedResultBase
+          def initialize(params={})
+            # your other init stuff here
+            super(params)    # default taken 
+          end
+       end
+       
+    -- or --
+    
+       class ResultBean < NestedResultBase
+          def initialize(params={})
+            # your other init stuff here
+            super( params.merge({depth: :multi}) )    # Specified
+          end
+       end
+       
+    ** - or -- enable serialization and default to multi
+       class GenericBean < NestedResultBase
+          def initialize(params={})
+            super( params.merge({enable_serialization: true}) )    # Specified with Serialization Enabled
+          end
+       end
+```
+
+(Follow VALUES that are Hashes and/or Arrays of Hashes, and enable Serializers)
+```ruby
+       class PageControl < NestedResultBase
+          def initialize(params={})
+            super( params.merge({depth: :multi_with_arrays, enable_serialization: true}) )    # override defaults
+          end
+       end
+```
+
+
+NOTE: Cannot be Marshalled/Serialized unless input params.merge({enable_serialization: true}) -- default is false
+Use GenericBean or PageControls if serialization is needed, it initializes with this value true.
+
+## Installation
+----------------
+runtime prereqs: gem 'active_model', '~> 3.0'
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'skn_utils'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install skn_utils
+
+## Build (If not found in RubyGems Yet...)    
+
+1. $ git clone git@github.com:skoona/skn_utils.git
+2. $ cd skn_utils
+3. $ gem install bundler
+4. $ bundle install
+5. $ bundle exec rspec
+6. $ gem build skn_utils.gemspec
+7. $ gem install skn_utils
+* Done
+
+## Console Workout    
+
+Start with building gem first.
+```bash    
+$ cd skn_utils
+$ bundle exec pry
+[1] pry(main)> require 'active_model' 
+[2] pry(main)> require 'skn_utils'    
+[3] pry(main)> rb = SknUtils::ResultBean.new({sample: [{one: "one", two: "two"},{one: 1, two: 2}] })
+[4] pry(main)> pg = SknUtils::PageControls.new({sample: [{one: "one", two: "two"},{one: 1, two: 2}] }) 
+[5] pry(main)> pg.sample.first.one          # Tip :multi_with_arrays
+[6] pry(main)> rb.sample.first.one          # Tip :multi without arrays  you will get a NoMethodError
+[7] pry(main)> rb.sample.first[:one]        
+    
+[n] pry(main)> exit
+* Done
+```
+    
+## Contributing
+
+1. Fork it 
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/skn_utils.rb

@@ -0,0 +1,11 @@
+require "skn_utils/version"
+require 'skn_utils/attribute_helpers'
+require 'skn_utils/nested_result_base'
+require 'skn_utils/generic_bean'
+require 'skn_utils/page_controls'
+require 'skn_utils/result_bean'
+require 'skn_utils/result_bean_with_errors'
+
+module SknUtils
+  
+end

data/lib/skn_utils/attribute_helpers.rb

@@ -0,0 +1,159 @@
+##
+# <Rails.root>/lib/skn_utils/attribute_helpers.rb
+#
+# *** See SknUtils::NestedResultBase for details ***
+#
+##
+# This module provides
+#
+# to_hash Serializer:
+#    person.to_hash
+#      => {"name"=>"Bob"}
+#
+# Support <attr>? and clear_<attr>? method patterns
+#  example:
+#    person.name?
+#      => true          true or false, like obj.name.present?
+#    person.clear_name
+#      => nil           sets :name to nil
+#
+# attr_accessor like feature for all instance variables
+#   person.name
+#     => "Bob"
+#   person.name = "James"
+#     => "James"
+##
+
+
+
+module SknUtils
+  module AttributeHelpers
+
+    # return a hash of all attributes and their current values
+    # including nested arrays of hashes/objects
+    def attributes
+      instance_variable_names.each_with_object({}) do |attr,collector|
+        next if ['skn_enable_serialization', 'skn_enabled_depth'].include?(attr.to_s[1..-1])   # skip control keys
+        value = instance_variable_get(attr)
+        next if value.is_a?(ActiveModel::Errors)
+
+        if value.kind_of?(Array) and value.first.respond_to?(:attribute_helper_object)
+          value = value.map {|ov| ov.respond_to?(:attribute_helper_object) ? ov.attributes : ov }
+        elsif value.respond_to?(:attribute_helper_object)
+          value = value.attributes
+        end
+        collector[attr.to_s[1..-1].to_sym] = value
+      end
+    end
+
+    def to_hash
+      attributes
+    end
+
+    # An alternative mechanism for property access.
+    # This let's you do foo['bar'] along with foo.bar.
+    def [](attr)
+      send("#{attr}")
+    end
+
+    def []=(attr, value)
+      send("#{attr}=", value)
+    end
+
+    # determines if this is one of our objects
+    def attribute_helper_object
+      true
+    end
+
+    ##
+    #  DO NOT ADD METHODS BELOW THIS LINE, unless you want them to be private
+    ##
+    private
+
+    def attribute?(attr)
+      if attr.is_a? Symbol
+        send(attr).present?
+      else
+        send(attr.to_sym).present?
+      end
+    end
+
+    def clear_attribute(attr)
+      if attr.is_a? Symbol
+        instance_variable_set("@#{attr.to_s}", nil)
+      else
+        instance_variable_set("@#{attr}", nil)
+      end
+    end
+
+    # Determines operable Options in effect for this instance
+    # see NestedResultBase
+    def serial_required?
+      respond_to? :serialization_required? and serialization_required?
+    end
+    # see NestedResultBase
+    def multi_required?
+      respond_to? :depth_level and depth_level != :single 
+    end
+    # see NestedResultBase
+    def multi_with_arrays_required?
+      respond_to? :depth_level and depth_level == :multi_with_arrays 
+    end
+
+    ##
+    # Adds the attr?() method pattern.  all attributes will respond to attr?: example - obj.name? with true or false
+    # Adds the clear_attr() method pattern.  all attributes will respond to clear_attr(): example - obj.clear_name sets :name to nil
+    # Handles getter for any instance_variable currently defined
+    # Handles setter for any instance_variable currently defined
+    # Sets new instance_variable for any undefined variable with non-hash value
+    # Sets instance_variable value to Bean object for any undefined variable with hash value param
+    #
+    # Using any form of singleton_class() will break the generic bean, which requires Serialization.
+    # However not adding attr_accessors may impact performance, as method_missing must fill-in for read/writes
+    ##
+    def method_missing(method, *args, &block)
+      # puts("method_missing/method/class/*args=#{method}/#{method.class.name}/#{args}")
+      if method.to_s.start_with?('clear_') and instance_variable_defined?("@#{method.to_s[6..-1]}")
+        clear_attribute(method.to_s[6..-1].to_sym)
+      elsif method.to_s.end_with?('?')
+        if instance_variable_defined?("@#{method.to_s[0..-2]}")
+          attribute?(method.to_s[0..-2].to_sym)
+        else
+          false
+        end
+      elsif method.to_s.end_with?("=")              # add new attribute or whole object
+        if args.first.is_a?(Hash) 
+          singleton_class.send(:attr_accessor, method.to_s[0..-2]) unless serial_required?
+          if multi_required?
+            instance_variable_set "@#{method.to_s[0..-2]}", self.class.new(*args)
+          else
+            instance_variable_set "@#{method.to_s[0..-2]}", *args
+          end
+        elsif args.first.is_a?(Array) and args.flatten.first.kind_of?(Hash)
+          singleton_class.send(:attr_accessor, method.to_s[0..-2]) unless serial_required?
+          if multi_with_arrays_required?
+            instance_variable_set("@#{method.to_s[0..-2]}", 
+                (args.flatten.map {|nobj| nobj.kind_of?(Hash) ? self.class.new(nobj) : nobj }) 
+            )
+          else
+            instance_variable_set "@#{method.to_s[0..-2]}", *args
+          end
+        elsif !args.empty?
+          singleton_class.send(:attr_accessor, method.to_s[0..-2]) unless serial_required?
+          instance_variable_set "@#{method.to_s[0..-2]}", *args
+        else
+          super(method, *args, &block)      # throw excpt for not found or could return false
+        end
+      elsif instance_variable_defined? "@#{method.to_s}"
+        instance_variable_get "@#{method.to_s}"
+      else
+        super(method, *args, &block)
+      end
+    rescue
+       # puts $!.message + $!.backtrace.join("\n")
+      super(method, *args, &block)
+    end
+    # end of private section
+
+  end # end module
+end # end module