nrser 0.0.25 → 0.0.26

data/lib/nrser/merge_by.rb

@@ -0,0 +1,26 @@
+
+
+module NRSER
+  
+  # Eigenclass (Singleton Class)
+  # ========================================================================
+  # 
+  class << self
+    
+    # @todo Document merge_by method.
+    # 
+    # @param [type] arg_name
+    #   @todo Add name param description.
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    def merge_by current, *updates, &getter
+      updates.reduce( to_h_by current, &getter ) { |result, update|
+        deep_merge! result, to_h_by(update, &getter)
+      }.values
+    end # #merge_by
+    
+  end # class << self (Eigenclass)
+    
+end # module NRSER

data/lib/nrser/message.rb

@@ -0,0 +1,125 @@
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # Container for a message (method call) to be sent to a receiver via 
+  # {Object#send} (or {Object#public_send}).
+  # 
+  # Encapsulates the method symbol as well as any arguments and block to send.
+  # 
+  # Implements `#to_proc` so it can be used like
+  # 
+  #     enum.map &message
+  # 
+  # You can invoke the message on a receiver object like
+  # 
+  #     msg.send_to obj
+  # 
+  # Useful for clearly describing and recognizing data that is meant to be 
+  # sent to an object as a method call, especially in testing.
+  # 
+  class Message
+    # Name of method the message is for.
+    # 
+    # @return [Symbol | String]
+    #     
+    attr_reader :symbol
+
+
+    # Arguments (parameters). May be empty.
+    # 
+    # @return [Array]
+    #     
+    attr_reader :args
+
+
+    # Optional block to send to the receiver.
+    # 
+    # @return [nil | #call]
+    #     
+    attr_reader :block
+    
+    
+    # Construct a new message.
+    # 
+    # @param [String | Symbol] symbol
+    #   Name of target method.
+    # 
+    # @param [Array] *args
+    #   Any arguments that should be sent.
+    # 
+    # @param [nil | #call] &block
+    #   Optional block that should be sent.
+    # 
+    def initialize symbol, *args, &block
+      @symbol = symbol
+      @args = args
+      @block = block
+    end
+    
+    
+    # Creates a {Proc} that accepts a single `receiver` argument and calls
+    # {#sent_to} on it, allowing messages to be used via the `&` operator
+    # in `map`, etc.
+    # 
+    # @example Map each entry as the message receiver using `&`
+    #   
+    #   enum = [ [], [1], [1, 2] ]
+    #   
+    #   length_message = NRSER::Message.new :length
+    #   first_message = NRSER::Message.new :first
+    #   
+    #   enum.map &length_message
+    #   # => [0, 1, 2]
+    #   
+    #   enum.map &first_message
+    #   # => [nil, 1, 1]
+    # 
+    # @return [Proc]
+    # 
+    def to_proc publicly: true
+      # block
+      ->( receiver ) { send_to receiver, publicly: publicly }
+    end
+    
+    alias_method :to_sender, :to_proc
+
+    
+    # Send this instance to a receiver object.
+    # 
+    # @example
+    #   
+    #   msg.send_to obj
+    # 
+    # @param [Object] receiver
+    #   Object that the message will be sent to.
+    # 
+    # @param [Boolean] publicly:
+    #   When `true`, the message will be sent via {Object#public_send}. This is
+    #   the default behavior.
+    #   
+    #   When `false`, the message will be sent via {Object#send}, allowing it
+    #   to invoke private and protected methods on the receiver.
+    # 
+    # @return [Object]
+    #   Result of the method call.
+    # 
+    def send_to receiver, publicly: true
+      if publicly
+        receiver.public_send symbol, *args, &block
+      else
+        receiver.send symbol, *args, &block
+      end
+    end
+    
+    # @return [String]
+    #   Brief description of the message.
+    # 
+    def to_s
+      "#<NRSER::Message symbol=#{ symbol } args=#{ args } block=#{ block }>"
+    end
+  end # class Message
+  
+end # module NRSER
+

data/lib/nrser/meta/props.rb

@@ -217,7 +217,8 @@ module Props
   #   @todo Document return value.
   # 
   def to_h only_own: false, only_primary: false
-    self.class.props(only_own: only_own, only_primary: only_primary).
+    self.class.
+      props(only_own: only_own, only_primary: only_primary).
       map_values { |name, prop| prop.get self }
   end # #to_h
   
@@ -251,7 +252,6 @@ module Props
   end # #to_data
   
   
-  
   # Language Inter-Op
   # ---------------------------------------------------------------------
   

data/lib/nrser/meta/props/prop.rb

@@ -154,7 +154,6 @@ class Prop
   end # #set
   
   
-  
   # @todo Document set_from_hash method.
   # 
   # @param [type] arg_name
@@ -168,7 +167,11 @@ class Prop
       set instance, values[name]
     else
       if default?
-        set instance, default.dup
+        set instance, if !default.nil? && default.respond_to?( :dup )
+          default.dup
+        else
+          default
+        end
       else
         raise TypeError.new NRSER.squish <<-END
           Prop #{ name } has no default value and no value was provided in

data/lib/nrser/object.rb

@@ -0,0 +1,5 @@
+# Require all the individual `//lib/object` files...
+# 
+require_relative './object/truthy'
+require_relative './object/as_hash'
+require_relative './object/as_array'

data/lib/nrser/object/as_array.rb

@@ -0,0 +1,37 @@
+module NRSER
+  
+  # Return an array given any value in the way that makes most sense:
+  # 
+  # 1.  If `value` is an array, return it.
+  #     
+  # 2.  If `value` is `nil`, return `[]`.
+  #     
+  # 3.  If `value` responds to `#to_a`, try calling it. If it succeeds, return
+  #     that.
+  #     
+  # 4.  Return an array with `value` as it's only item.
+  # 
+  # Refinement
+  # ----------
+  # 
+  # Added to `Object` in `nrser/refinements`.
+  # 
+  # @param [Object] value
+  # 
+  # @return [Array]
+  # 
+  def self.as_array value
+    return value if value.is_a? Array
+    return [] if value.nil?
+    
+    if value.respond_to? :to_a
+      begin
+        return value.to_a
+      rescue
+      end
+    end
+    
+    [value]
+  end # .as_array
+  
+end # module NRSER

data/lib/nrser/object/as_hash.rb

@@ -0,0 +1,101 @@
+module NRSER
+  
+  # Treat the value as the value for `key` in a hash if it's not already a
+  # hash and can't be converted to one:
+  # 
+  # 1.  If the value is a `Hash`, return it.
+  #     
+  # 2.  If `value` is `nil`, return `{}`.
+  #     
+  # 3.  If the value responds to `#to_h` and `#to_h` succeeds, return the
+  #     resulting hash.
+  #     
+  # 4.  Otherwise, return a new hash where `key` points to the value.
+  #     **`key` MUST be provided in this case.**
+  # 
+  # Useful in method overloading and similar situations where you expect a 
+  # hash that may specify a host of options, but want to allow the method
+  # to be called with a single value that corresponds to a default key in that
+  # option hash.
+  # 
+  # Refinement
+  # ----------
+  # 
+  # Added to `Object` in `nrser/refinements`.
+  # 
+  # 
+  # Example Time!
+  # -------------
+  # 
+  # Say you have a method `m` that handles a hash of HTML options that can
+  # look something like
+  # 
+  #     {class: 'address', data: {confirm: 'Really?'}}
+  # 
+  # And can call `m` like
+  # 
+  #     m({class: 'address', data: {confirm: 'Really?'}})
+  # 
+  # but often you are just dealing with the `:class` option. You can use
+  # {NRSER.as_hash} to accept a string and treat it as the `:class` key:
+  # 
+  #     using NRSER
+  #     
+  #     def m opts
+  #       opts = opts.as_hash :class
+  #       # ...
+  #     end
+  # 
+  # If you pass a hash, everything works normally, but if you pass a string
+  # `'address'` it will be converted to `{class: 'address'}`.
+  # 
+  # 
+  # About `#to_h` Support
+  # ---------------------
+  # 
+  # Right now, {.as_hash} also tests if `value` responds to `#to_h`, and will
+  # try to call it, using the result if it doesn't raise. This lets it deal 
+  # with Ruby's "I used to be a Hash until someone mapped me" values like
+  # `[[:class, 'address']]`. I'm not sure if this is the best approach, but 
+  # I'm going to try it for now and see how it pans out in actual usage.
+  # 
+  # @todo
+  #   It might be nice to have a `check` option that ensures the resulting
+  #   hash has a value for `key`.
+  # 
+  # @param [Object] value
+  #   The value that we want to be a hash.
+  # 
+  # @param [Object] key [default nil]
+  #   The key that `value` will be stored under in the result if `value` is 
+  #   not a hash or can't be turned into one via `#to_h`. If this happens
+  #   this value can **NOT** be `nil` or an `ArgumentError` is raised.
+  # 
+  # @return [Hash]
+  # 
+  # @raise [ArgumentError]
+  #   If it comes to constructing a new Hash with `value` as a value and no
+  #   argument was provided 
+  # 
+  def self.as_hash value, key = nil
+    return value if value.is_a? Hash
+    return {} if value.nil?
+    
+    if value.respond_to? :to_h
+      begin
+        return value.to_h
+      rescue
+      end
+    end
+    
+    # at this point we need a key argument
+    if key.nil?
+      raise ArgumentError,
+            "Need key to construct hash with value #{ value.inspect }, " +
+            "found nil."
+    end
+    
+    {key => value}
+  end # .as_hash
+  
+end # module NRSER

data/lib/nrser/proc.rb

@@ -0,0 +1,132 @@
+##
+# Methods that make useful {Proc} instances.
+## 
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative './message'
+
+
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # Creates a new {NRSER::Message} from the array.
+  # 
+  # @example
+  #   
+  #   message = NRSER::Op.message( :fetch, :x )
+  #   message.send_to x: 'ex', y: 'why?'
+  #   # => 'ex'
+  # 
+  # @return [NRSER::Message]
+  # 
+  def self.message symbol, *args, &block
+    NRSER::Message.new symbol, *args, &block
+  end # #message
+  
+  singleton_class.send :alias_method, :msg, :message
+  
+  
+  # Create a {Proc} that sends the arguments to a receiver via `#public_send`.
+  # 
+  # Equivalent to
+  # 
+  #     message( symbol, *args, &block ).to_proc
+  # 
+  # Pretty much here for completeness' sake.
+  # 
+  # @example
+  #   
+  #   sender( :fetch, :x ).call x: 'ex'
+  #   # => 'ex'
+  # 
+  # @return [Proc]
+  # 
+  def self.public_sender symbol, *args, &block
+    message( symbol, *args, &block ).to_proc
+  end # .public_sender
+  
+  singleton_class.send :alias_method, :sender, :public_sender
+  singleton_class.send :alias_method, :sndr, :public_sender
+  
+  
+  # Create a {Proc} that sends the arguments to a receiver via `#send`,
+  # forcing access to private and protected methods.
+  # 
+  # Equivalent to
+  # 
+  #     message( symbol, *args, &block ).to_proc publicly: false
+  # 
+  # Pretty much here for completeness' sake.
+  # 
+  # @example
+  #   
+  #   sender( :fetch, :x ).call x: 'ex'
+  #   # => 'ex'
+  # 
+  # @return [Proc]
+  # 
+  def self.private_sender symbol, *args, &block
+    message( symbol, *args, &block ).to_proc publicly: false
+  end # .private_sender
+  
+  
+  # Map *each entry* in `mappable` to a {NRSER::Message} and return a
+  # {Proc} that accepts a single `receiver` argument and reduces it by
+  # applying each message in turn.
+  # 
+  # In less precise terms: create a proc that chains the entries as
+  # methods calls.
+  # 
+  # @note
+  #   `mappable`` entries are mapped into messages when {#to_chain} is called,
+  #   meaning subsequent changes to `mappable` **will not** affect the 
+  #   returned proc.
+  # 
+  # @example Equivalent of `Time.now.to_i`
+  # 
+  #   NRSER::chainer( [:now, :to_i] ).call Time
+  #   # => 1509628038
+  # 
+  # @return [Proc]
+  # 
+  def self.chainer mappable, publicly: true
+    messages = mappable.map { |value| NRSER::Message.new *value }
+    
+    ->( receiver ) {
+      messages.reduce( receiver ) { |receiver, message|
+        message.send_to receiver, publicly: publicly
+      }
+    }
+  end # .chainer
+  
+  singleton_class.send :alias_method, :chnr, :chainer
+  
+  
+  # Return a {Proc} that accepts a single argument that must respond to `#[]`
+  # and retrieves `key` from it.
+  # 
+  # @param [String | Symbol | Integer] key
+  #   Key (or index) to retrieve.
+  # 
+  # @return [Proc]
+  # 
+  def self.retriever key
+    ->( indexed ) { indexed[key] }
+  end # .getter
+  
+  singleton_class.send :alias_method, :rtvr, :retriever
+  
+  
+end # module NRSER