nrser 0.3.9 → 0.3.10

data/lib/nrser/errors/nicer_error.rb

@@ -19,67 +19,8 @@ require 'nrser/core_ext/object/lazy_var'
 
 # A mixin for {Exception} and utilities to make life better... even when things
 # go wrong.
-# 
-# "Nicer" errors do a few things:
-# 
-# 1.  **`message` is a splat/`Array`**
-#     
-#     Accept an {Array} `message` instead of just a string, dumping non-string
-#     values and joining everything together.
-#     
-#     This lets you deal with printing/dumping all in one place instead of
-#     ad-hoc'ing `#to_s`, `#inspect`, `#pretty_inspect`, etc. all over the
-#     place (though you can still dump values yourself of course since string
-#     pass right through).
-#     
-#     Write things like:
-# 
-#         MyError.new "The value", value, "sucks, it should be", expected
-# 
-#     This should cut down the amount of typing when raising as well, which
-#     is always welcome.
-#     
-#     It also allows for a future where we get smarter about dumping things,
-#     offer configuration options, switch on environments (slow, rich dev
-#     versus fast, concise prod), etc.
-# 
-# 2.  **"Extended" Messages**
-#     
-#     The normal message that we talked about in (1) - that we call the
-#     *summary message* or *super-message* (since it gets passed up to the
-#     built-in Exception's `#initialize`) - is intended to be:
-#     
-#     1.  Very concise
-#         -   A single line well under 80 characters if possible.
-#             
-#         -   This just seems like how Ruby exception messages were meant to
-#             be, I guess, and in many situations it's all you would want or
-#             need (production, when it just gets rescued anyways,
-#             there's no one there to read it, etc.).
-#             
-#     2.  Cheap to render.
-#         -   We may be trying to do lot very quickly on a production system.
-#     
-#     However - especially when developing - it can be really nice to add
-#     considerably more detail and feedback to errors.
-#     
-#     To support this important use case as well, `NicerError` introduces the
-#     idea of an *extended message* that does not need to be rendered and
-#     output along with the *summary/super-message*.
-#     
-#     It's rendering is done on-demand, so systems that are not configured to
-#     use it will pay a minimal cost for it's existence.
-#     
-#     > See {#extended_message}.
-#     
-#     The extended message is composed of:
-#     
-#     1.  Text *details*, optionally rendered via {Binding.erb} when a
-#         binding is provided.
-#     
-#     2.  A *context* of name and value pairs to dump.
-#         
-#     Both are provided as optional keyword parameters to {#initialize}.
+#
+# Check the docs at the {file:lib/nrser/errors/README.md nrser/errors README}.
 # 
 module NRSER::NicerError
   
@@ -104,18 +45,44 @@ module NRSER::NicerError
   def self.column_width
     DEFAULT_COLUMN_WIDTH
   end
+
+
+  module ClassMethods
+    def def_context_delegator keys:, presence_predicate: true
+      keys = Array keys
+
+      keys.each do |key|
+        define_method key do
+          if (found_key = keys.find { |k| context.key? k })
+            context[found_key]
+          end
+        end
+
+        if presence_predicate
+          define_method "#{ key }?" do
+            !!keys.find { |k| context.key? k }
+          end
+        end
+      end
+    end
+  end
+
+  def self.included base
+    base.extend ClassMethods
+  end
   
   
   # Construct a nicer error.
   # 
-  # @param [Array] *message
-  #   Main message segments.
+  # @param [Array] message
+  #   Main message segments. See {#format_message} and {#format_message_segment}
+  #   for an understanding of how they are, well, formatted.
   # 
-  # @param [Binding?] binding:
+  # @param [Binding?] binding
   #   When provided any details string will be rendered using it's
   #   {Binding#erb} method.
   # 
-  # @param [nil | String | Proc<()=>String> | #to_s] details:
+  # @param [nil | String | Proc<()=>String> | #to_s] details
   #   Additional text details to add to the extended message. When:
   #   
   #   1.  `nil` - no details will be added.
@@ -131,16 +98,16 @@ module NRSER::NicerError
   #       `#to_s` will be called on the value and the result will be used
   #       as in (2).
   # 
-  # @param [Hash<Symbol, VALUE>] **context
+  # @param [Hash<Symbol, VALUE>] context
   #   Any additional names and values to dump with an extended message.
   # 
   def initialize  *message,
                   binding: nil,
                   details: nil,
                   **context
-    @binding = binding
-    @context = context
-    @details = details
+    @binding = binding.freeze
+    @context = context.freeze
+    @details = details.freeze
     
     message = default_message if message.empty?
     super_message = format_message *message
@@ -159,6 +126,10 @@ module NRSER::NicerError
   # @return [String]
   #   The formatted string for the segment.
   # 
+  # @todo
+  #   This should talk to config when that comes about to find out how to
+  #   dump things.
+  # 
   def format_message_segment segment
     return segment.to_summary if segment.respond_to?( :to_summary )
     
@@ -171,7 +142,7 @@ module NRSER::NicerError
   
   # Format the main message by converting args to strings and joining them.
   # 
-  # @param [Array] *message
+  # @param [Array] message
   #   Message segments.
   # 
   # @return [String]
@@ -306,7 +277,7 @@ module NRSER::NicerError
   #   {Exception#message} just forwards here, so I overrode that with
   #   {#message} to just get the *summary/super-message* from this method.
   # 
-  # @param [Boolean?] extended:
+  # @param [Boolean?] extended
   #   Flag to explicitly control summary/super or extended message:
   #   
   #   1.  `nil` - call {#add_extended_message?} to decide (default).

data/lib/nrser/errors/value_error.rb

@@ -1,5 +1,21 @@
 # frozen_string_literal: true
+# encoding: UTF-8
 
+# Requirements
+# ========================================================================
+
+# Make nice(r)
+require_relative './nicer_error'
+
+
+# Namespace
+# ========================================================================
+
+module  NRSER
+
+
+# Definitions
+# ========================================================================
 
 # Raised when there is a problem with a *value* that does not fall into one
 # of the other built-in exception categories (non-exhaustive list):
@@ -7,66 +23,45 @@
 # 1.  It's the wrong type (TypeError)
 # 2.  It's an argument (ArgumentError)
 # 
-# The invalid value is attached to the error as an instance value so that
-# rescuers up the stack can do more intelligent things with it if need be.
+# It is encouraged to attach the invalid value as the `value:` keyword argument,
+# which is then stored in {#context} hash and can be accessed via {#value}.
 # 
 class NRSER::ValueError < StandardError
+
+  # Play nice :)
+  include NicerError
   
-  # The invalid value.
-  # 
-  # @return [Object]
-  #     
-  attr_reader :subject
-  
-  
-  def initialize message = nil, subject:
-    @subject = subject
-    
-    # If we received `nil` for the message, call {#build_message} to get it.
-    # 
-    # This provides a "hook" to assemble the message at the last possible
-    # moment before it needs to go up to {StandardError#initialize}, allowing
-    # {#build_message} to work with an otherwise fully-initialized instance.
-    # 
-    # Of course, {NRSER::ValueError#build_message}
-    # throws {NotImplementedError} since it doesn't really have enough
-    # knowledge to build anything useful (we're going for useful errors,
-    # "Value #{ value } is invalid" does not suffice).
-    # 
-    message = build_message if message.nil?
-    
-    super message
-  end
-  
-  
-  # Build the error message when none is provided to `#initialize`.
+  # @!method value?
+  #   `true` if we have a `:value` key in the {#context}.
+  #   
+  #   @return [Boolean]
+  #   
+  # @!method value
+  #   Get the value at the `:value` key in {#context}.
+  #   
+  #   @return [Object]
   # 
-  # When no `message` (or `nil`) is provided to {NRSER::ValueError.initialize}
-  # it will call this method to get the error message just before it needs it
-  # to call up to {StandardError#initialize} (via `super message`).
-  # 
-  # This allows {NRSER::ValueError} subclasses that are able to build a useful
-  # default message or would like to augment the user-provided one to do so
-  # at the last possible moment before it's needed, letting them work with an
-  # otherwise fully-initialized instance.
-  # 
-  # Hence a subclass several generations down from {NRSER::ValueError} can
-  # use values initialized in all the constructors in-between, avoiding a lot
-  # of headache.
-  # 
-  # This implementation always raises {NRSER::AbstractMethodError} because
-  # {NRSER::ValueError} does not have enough information to construct a useful
-  # message.
-  # 
-  # @return [String]
-  #   Implementations must return the message string for
-  #   {StadardError#initialize}.
-  # 
-  # @raise [NRSER::AbstractMethodError]
-  #   Must be implemented by subclasses if they wish to use message building.
+  def_context_delegator keys: :value
+
+
+  # @!method initialize *message, **kwds
+  #   Create a new {ValueError}.
+  #   
+  #   @param [Array] message
+  #     See {NicerError#initialize}.
+  #   
+  #   @param [Hash<Symbol, Object>] kwds
+  #     Except as called out below, other keywords are passed up to 
+  #     {NicerError#initialize}.
+  #   
+  #   @option kwds [Object] :value
+  #     The problematic value.
   # 
-  def build_message
-    raise NRSER::AbstractMethodError.new( self, __method__ )
-  end
-  
-end
+
+end # class ValueError
+
+
+# /Namespace
+# ========================================================================
+
+end # module NRSER

data/lib/nrser/functions.rb

@@ -1,7 +1,5 @@
-##
 # Require everything in `//lib/nrser/functions` - the core functional
 # interfaces that underlie all the refinements.
-##
 
 require_relative './functions/proc'
 require_relative './functions/object'

data/lib/nrser/functions/enumerable.rb

@@ -48,7 +48,7 @@ module NRSER
   #   Passed as only argument to {NRSER::Types.length} to create the length
   #   type the results are checked against.
   # 
-  # @param [Proc] &block
+  # @param [Proc] block
   #   `#find`/`#find_all`-style block that will be called with each entry
   #   from `enum`. Truthy responses mean the entry matched.
   # 
@@ -109,7 +109,7 @@ module NRSER
   #   Enumerable in question (really, anything that responds to `#first` and
   #   `#count`).
   # 
-  # @param [D] default:
+  # @param [D] default
   #   Value to return if `enum` does not have only one entry.
   # 
   # @return [E]
@@ -142,19 +142,7 @@ module NRSER
     count = enum.count
     
     unless count == 1
-      message = binding.erb <<-END
-        Expected enumerable to have #count == 1 but it has
-        
-        #count = <%= enum.count %>
-        
-        Enumerable (class: <%= enum.class %>):
-        
-            <%= enum.pretty_inspect %>
-        
-      END
-      
-      raise NRSER::CountError.new message,
-                                  subject: enum,
+      raise NRSER::CountError.new value: enum,
                                   count: count,
                                   expected: 1
     end
@@ -206,7 +194,7 @@ module NRSER
   #   {Enumerable} (or other object with compatible `#each_with_object` and
   #   `#to_enum` methods) you want to count.
   # 
-  # @param [Proc<(E)=>C>] &block
+  # @param [Proc<(E)=>C>] block
   #   Block mapping entries in `enum` to the group to count them in.
   # 
   # @return [Hash{C=>Integer}]
@@ -229,7 +217,7 @@ module NRSER
   # @param [Enumerable<E>] enum
   #   Values to call `&block` with.
   # 
-  # @param [Proc<E=>V>] &block
+  # @param [Proc<E=>V>] block
   #   Block to call, which is expected to raise an error if it fails.
   # 
   # @return [V]

data/lib/nrser/functions/enumerable/associate.rb

@@ -24,7 +24,7 @@ module NRSER
   # @param [Enumerable<V>] enum
   #   Enumerable containing the values for the hash.
   # 
-  # @param [Proc<(V)=>K>] &block
+  # @param [Proc<(V)=>K>] block
   #   Block that maps `enum` values to their hash keys.
   # 
   # @return [Hash<K, V>]
@@ -53,12 +53,21 @@ module NRSER
   # Create a {Hash} mapping the entries in `enum` to the value returned by
   # passing them through `&block`, raising on conflicts.
   # 
+  # @param [Enumerable<ENTRY>] enum
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
+  # @param [ :raise | :first_wins | :last_wins | Proc ] on_conflict
+  #   What to do when there's a conflict mapping the entries into the hash.
+  #   
+  #   The names are meant to make some sense.
   # 
-  # @return [return_type]
-  #   @todo Document return value.
+  # @param [Proc<(ENTRY)=>VALUE>] block
+  #   The star of the show! Maps `ENTRY` from `enum` to `VALUE` for the
+  #   resulting hash.
+  # 
+  # @return [Hash<ENTRY, VALUE>]
+  # 
+  # @raise [NRSER::ConflictError]
+  #   If a conflict occurs and `on_conflict` is set to `:raise`.
   # 
   def self.assoc_to enum, on_conflict: :raise, &block
     enum.each_with_object( {} ) { |entry, hash|

data/lib/nrser/functions/enumerable/find_all_map.rb

@@ -17,7 +17,7 @@ module NRSER
   # @param [Enumerable<E>] enum
   #   Entries to search (in order).
   # 
-  # @param [Proc<(E)=>R>] &block
+  # @param [Proc<(E)=>R>] block
   #   Block mapping entires to results.
   # 
   # @return [nil]

data/lib/nrser/functions/enumerable/include_slice/array_include_slice.rb

@@ -22,7 +22,7 @@ module NRSER
   #   The {Enumerable} slice that we want to see if `enum` includes. Must
   #   support `#length` and `#slice` like {Array} does.
   # 
-  # @param [Proc<(E, S)=>Boolean>] &is_match
+  # @param [Proc<(E, S)=>Boolean>] is_match
   #   Optional {Proc} that accepts an entry from `enum` and an entry from
   #   `slice` and returns if they match.
   # 

data/lib/nrser/functions/hash/bury.rb

@@ -22,7 +22,7 @@ module NRSER
   # @param [Object] value
   #   The value to set at the end of the path.
   # 
-  # @param [Class | :guess] parsed_key_type:
+  # @param [Class | :guess] parsed_key_type
   #   How to handle parsed key path segments:
   #   
   #   -   `String` - use the strings that naturally split from a parsed
@@ -68,17 +68,7 @@ module NRSER
       create_arrays_for_unsigned_keys: create_arrays_for_unsigned_keys
   end # .bury!
   
-
-  # @todo Document _internal_bury! method.
-  # 
-  # @private
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
+  
   def self._internal_bury! tree,
                       key_path,
                       value,

data/lib/nrser/functions/merge_by.rb

@@ -8,11 +8,11 @@ module NRSER
   # @param [Array<Hash>] current
   #   Current (base) array of hashes to start with (lowest predominance).
   # 
-  # @param [Array<Hash>] *updates
+  # @param [Array<Hash>] updates
   #   One or more arrays of update hashes to merge over `current` (last is
   #   highest predominance).
   # 
-  # @param [Proc<(Hash)=>Object>] &merge_key
+  # @param [Proc<(Hash)=>Object>] merge_key
   #   Each hash is passed to `&merge_key` and the result is used to match
   #   hashes for merge. Must not return equal values for two different hashes
   #   in any of the arrays (`current` or any of `*updates`).