traitr 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 344b8ed96166aea681f7b1bc1f5d824caf0ae95c
-  data.tar.gz: 837d71f3b9012e0e8851f70547019e03c95f8196
+  metadata.gz: 989c4e5ac888058f57192ebbbc0e21729f574032
+  data.tar.gz: 21deba747d0819395e847d96bc73d976e62d2c40
 SHA512:
-  metadata.gz: 7b9577c91836a307873d3037ae981990657cb0d141627e8eefa87b125b4f58f7a3aea3d6621ba07b9612eb487fde4489aa3d800aacc90aba70d3b6c6f4418626
-  data.tar.gz: 70125caef20138cd3c21995a6c47910bb2b8ab7b4ddb5d72528a48140188df6e72679e899181395bc93cae1288d4d6e532f251260c64739e8331e92c345a6006
+  metadata.gz: e29befd886a056da95c916aed20ec0bb2933382acaf070d0e3a79341a5434cd023cc72964712ea10cf07b2c196faeb2ebb058f0e35aea1689a09ac58fa79bace
+  data.tar.gz: 18165a4221d8f9e44973920a786c4f196240af8cc245f30a0cd4efa30d316eb3ae1517d06fc2e5f3bbe9c31f7522bf40cd4baa5ef6b5d71ddfdb308d8d31cf6e

data/lib/traitor.rb

@@ -12,6 +12,7 @@ module Traitor
   @trait_cache = {}
 
   class << self
+    # Reset Traitor entirely by clearing its attributes.
     def reset!
       @trait_library = {}
       @alternate_create_methods = {}
@@ -20,6 +21,10 @@ module Traitor
       @trait_cache = {}
     end
 
+    # Hook an object into Traitor. Read GETTING_STARTED.md for assistance.
+    #
+    # @param [String|Symbol] klass - the class reference.
+    # @param [Hash] traits - the hash of traits defined on the Traitor.s
     def define(klass, **traits)
       @trait_library[klass] ||= {}
 
@@ -47,11 +52,20 @@ module Traitor
       @trait_library[klass].merge!(traits)
     end
 
-    ##
     # build an instance of an object using the defined traits and attributes.
-    ##
+    #
+    # @param [String|Symbol] klass - the class reference symbol to get the library from
+    # @param [Array] traits - the list of traits to refer attributes from
+    # @param [Hash] attributes - the list of attributes to apply to the specific object.
     def build(klass, *traits, **attributes)
-      attributes = get_attributes_from_traits(klass, traits).merge(attributes)
+      attrs, concat_attrs = split_attributes(attributes)
+      attributes = get_attributes_from_traits(klass, traits).merge(attrs)
+      # but add all the separate concatenated attributes into a list.
+      concat_attrs.each do |k, v|
+        attributes[k] ||= []
+        attributes[k] << v
+      end
+
       build_kwargs = Traitor::Config.build_kwargs || {}
 
       record = if Traitor::Config.build_with_list
@@ -66,10 +80,12 @@ module Traitor
       record
     end
 
-    ##
     # build an instance of an object using the defined traits and attributes,
-    # and then save it.
-    ##
+    # and then save it using the appropriate create method.
+    #
+    # @param [String|Symbol] klass - the class reference symbol to get the library from
+    # @param [Array] traits - the list of traits to refer attributes from
+    # @param [Hash] attributes - the list of attributes to apply to the specific object.
     def create(klass, *traits, **attributes)
       create_method, create_kwargs = @alternate_create_methods[klass] ||
         [Traitor::Config.create_method, Traitor::Config.create_kwargs || {}]
@@ -88,6 +104,12 @@ module Traitor
       record
     end
 
+    # build an instance of an object using the defined traits and attributes,
+    # and then save it using the explicitly referenced create method.
+    #
+    # @param [String|Symbol] klass - the class reference symbol to get the library from
+    # @param [Array] traits - the list of traits to refer attributes from
+    # @param [Hash] attributes - the list of attributes to apply to the specific object.
     def create_using(klass, create_method, *traits, **attributes)
       old_create_method_kwargs = @alternate_create_methods[klass]
       @alternate_create_methods[klass] = [create_method, attributes.delete(:create_kwargs) || {}]
@@ -98,6 +120,14 @@ module Traitor
 
     private
 
+    # Helper method to call after blocks that are defined on a Traitor.
+    #
+    # @param [String|Symbol] klass - the class reference for the library.
+    # @param [Symbol] trigger - one of the values in BLOCK_KEYS, to check for in
+    #                 the block library.
+    # @param [Object] record - the object the trigger will yield.
+    # @param [Array] traits - A list of traits that the object was built with,
+    #                to find any triggers specific to the referenced traits.
     def call_blocks(klass, trigger, record, *traits)
       return unless @block_library[klass]
       [].tap do |blocks|
@@ -110,12 +140,26 @@ module Traitor
       end.compact.each { |block| block.call(record) }
     end
 
+    # given a string/symbol, return the class based on that symbol.
+    # e.g. :some_class -> SomeClass
+    #
+    # @param [String|Symbol] klass - the class symbol/reference
+    # @return [Object] the class
     def convert_to_class(klass)
       @class_cache[klass] ||= Object.const_get(camelize(klass))
     rescue NameError
       raise Traitor::Error.new("Tried to create a #{camelize(klass)}, but it does not exist!")
     end
 
+    # Given a list of traits, return the compiled hash of attributes with calculated values.
+    # Will properly call lambdas/procs to get their value and will concatenate attributes
+    # prefixed with a '+'.
+    #
+    # Will always start from the :default_traits trait, if it exists.
+    #
+    # @param [String|Symbol] klass - the class reference to get the list of traits from the library.
+    # @param [Array[String|Symbol]] traits - a list of traits to refer to in the library.
+    # @return [Hash] The calculated attributes hash.
     def get_attributes_from_traits(klass, traits)
       # we only call this method when the klass has been converted to a key inside create
       return {} unless library = @trait_library[klass]
@@ -124,23 +168,66 @@ module Traitor
 
       cache_key = klass.to_s + ':' + traits.join(':')
       @trait_cache[cache_key] ||= {}.tap do |attributes|
-        traits.each { |trait| attributes.merge!(library[trait] || {}) }
+        traits.each do |trait|
+          # pull out concatenating attributes into their own list
+          attrs, concat_attrs = split_attributes(library[trait] || {})
+
+          # raw merge in the standard attributes...
+          attributes.merge!(attrs)
+
+          # but add all the separate concatenated attributes into a list.
+          concat_attrs.each do |k, v|
+            attributes[k] ||= []
+            attributes[k] << v
+          end
+        end
       end
 
       # use late resolution on lambda values by calling them here as part of constructing a new hash
       Hash[
         @trait_cache[cache_key].map do |attribute, value|
-          [attribute, value.is_a?(Proc) && ![:after_build, :after_create].include?(attribute) ? value.call : value]
+          [attribute, calculate_value(value)]
         end
       ]
     end
 
+    # Split a hash into two hashes, the first being a list of all values that do
+    # not begin with '+', the latter being a list of all values that do.
+    #
+    # @param [Hash] attributes
+    # @return [Array[Hash, Hash]] The split hash.
+    def split_attributes(attributes)
+      attributes.reduce([{}, {}]) do |memo, attr_val|
+        attribute, value = attr_val
+        if attribute.to_s.start_with?('+')
+          memo[1][attribute[1..-1].to_sym] = value
+        else
+          memo[0][attribute] = value
+        end
+        memo
+      end
+    end
+
+    # Given the value reference from an attribute, call it if callable, or map it
+    # if appropriate, or return it as-is.
+    #
+    # @param [Mixed] v - the value from an attribute. can be Proc, Array, or "value"
+    # @return the calculated value.
+    def calculate_value(v)
+      return v.call if v.is_a?(Proc)
+      return v.map { |sv| calculate_value(sv) } if v.is_a?(Array)
+      v
+    end
+
+    # simplifed version of ActiveRecord camelize.
+    # used to convert a generic class name (in)
+    #
+    # @param [String|Symbol] term - the term to symbolize
+    # @return [String] the camel-cased version of the term, to be retrieved as a const.
     def camelize(term)
-      string = term.to_s
-      string[0] = string[0].upcase
-      string.gsub!(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }
-      string.gsub!('/'.freeze, '::'.freeze)
-      string
+      term.to_s.capitalize
+        .gsub(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }
+        .gsub('/'.freeze, '::'.freeze)
     end
   end
 end

data/lib/traitor/config.rb

@@ -12,29 +12,33 @@ module Traitor
       def configure_for_rails!
         @create_method  = :save
         @create_kwargs  = { validate: false }
-        @build_kwargs = { without_protection: true }
+        @build_kwargs   = { without_protection: true }
       end
 
       def configure_safe_for_rails!
         @create_method  = :save
         @create_kwargs  = {}
-        @build_kwargs = {}
+        @build_kwargs   = {}
       end
 
+      # Undefine all configuration values.
       def reset!
-        @create_method = nil
-        @create_kwargs = {}
-        @build_kwargs = {}
+        @create_method   = nil
+        @create_kwargs   = {}
+        @build_kwargs    = {}
         @build_with_list = false
-        @no_callbacks = false
+        @no_callbacks    = false
       end
 
+      # Temporarily store the old configuration, so the config can be modified and
+      # then later restored.
       def stash!
         @old_config = Hash[
           self.instance_variables.map { |att| [att, self.instance_variable_get(att)] }
         ]
       end
 
+      # After calling #stash!, call this to restore the stashed config.
       def restore!
         return unless @old_config
         @old_config.each { |att, val| self.instance_variable_set(att, val) }

data/lib/traitor/helpers/active_record.rb

@@ -29,6 +29,7 @@ module Traitor
         self.class.connection.execute(insert_sql)
         id = self.maximum(pk)
         self.send(:"#{pk}=", id)
+        self.instance_variable_set(:@new_record, false)
         self.clear_changes_information
       end
 
@@ -43,6 +44,7 @@ module Traitor
         pk = self.class.primary_key
         id = conn.execute("SELECT last_insert_rowid() AS id")[0]['id']
         self.send(:"#{pk}=", id)
+        self.instance_variable_set(:@new_record, false)
         self.clear_changes_information
       end
 
@@ -58,7 +60,16 @@ module Traitor
         end.to_sql
 
         # return and assign everything to gather values created/modified by db triggers
-        self.attributes = self.class.connection.execute(insert_sql + " RETURNING *")[0]
+        result = self.class.connection.execute(insert_sql + " RETURNING *")
+
+        # reassign the write values back to the object, in case there are DB triggers.
+        result.to_a.first.each do |column_name, serialized_value|
+          column = self.column_for_attribute(column_name)
+          deserialized_value = column.type_cast_from_database(serialized_value)
+          self["#{column_name}"] = deserialized_value
+        end
+
+        # mark the instance as having been saved.
         self.instance_variable_set(:@new_record, false)
         self.clear_changes_information
       end

data/lib/traitor/helpers/rspec.rb

@@ -3,6 +3,7 @@ require 'rspec'
 module Traitor
   module Helpers
     class RSpec
+      # define the metadata keys to override traitor configs on a per-example basis.
       def self.configure!
         ::RSpec.configure do |config|
           config.around(:example) do |example|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: traitr
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - Zach Lome
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-29 00:00:00.000000000 Z
+date: 2016-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler