nrser 0.2.2 → 0.3.0

data/lib/nrser/errors/nicer_error.rb

@@ -1,110 +1,336 @@
+# encoding: UTF-8
 # frozen_string_literal: true
 
+
 # Requirements
-# =======================================================================
+# ========================================================================
 
 # Stdlib
-# -----------------------------------------------------------------------
+# ------------------------------------------------------------------------
 
-# Deps
-# -----------------------------------------------------------------------
+# Using {PP.pp} as default dumper.
+require 'pp'
 
-# Project / Package
-# -----------------------------------------------------------------------
+require 'nrser/core_ext/object/lazy_var'
 
 
 # Definitions
 # =======================================================================
 
-# A mixin for {Exception} and utilities to make errors nicer.
+# 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}.
 # 
 module NRSER::NicerError
   
+  # Constants
+  # ========================================================================
+  
+  # Default column width
+  DEFAULT_COLUMN_WIDTH = 78
+  
   
-  # TODO document `context` attribute.
+  # Module Methods
+  # ==========================================================================
+  
+  # Column width to format for (just summary/super-message at the moment).
+  # 
+  # @todo
+  #   Implement terminal width detection like Thor?
+  # 
+  # @return [Fixnum]
+  #   Positive integer.
   # 
-  # @return [Hash<Symbol, V>]
-  #     
-  attr_reader :context
+  def self.column_width
+    DEFAULT_COLUMN_WIDTH
+  end
   
   
-  # @todo Document render_message method.
+  # Construct a nicer error.
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
+  # @param [Array] *message
+  #   Main message segments.
   # 
-  # @return [return_type]
-  #   @todo Document return value.
+  # @param [Binding?] binding:
+  #   When provided any details string will be rendered using it's
+  #   {Binding#erb} method.
   # 
-  def self.render_message message,
-                          context: {},
-                          add_context: true,
-                          &get_extended_message
-    
-    # 1.  Figure out if `message` is just the "short message" (single line)
-    #     or if it's "old-style" where it's just the whole thing.
-    
-    message_lines = message.lines
+  # @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.
+  #       
+  #   2.  `String` - the value will be used. If `binding:` is provided, it
+  #       will be rendered against it as ERB.
+  #       
+  #   3.  `Proc<()=>String>` - if and when an extended message is needed
+  #       the proc will be called, and the resulting string will be used
+  #       as in (2).
+  #       
+  #   4.  `#to_s` - catch all; if and when an extended message is needed
+  #       `#to_s` will be called on the value and the result will be used
+  #       as in (2).
+  # 
+  # @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
     
-    if message_lines.length > 1
-      message_lines = NRSER.dedent message_lines, return_lines: true
-      short_message = message_lines.first.chomp
-      extended_message_lines = message_lines.rest
-    else
-      short_message = message
-      extended_message_lines = nil
-    end
+    message = default_message if message.empty?
+    super_message = format_message *message
     
-    # Ok, `short_message` is a single line string
-    #     `extended_message_lines` is an array of string lines or `nil`
+    super super_message
+  end # #initialize
+  
+  
+  # Format a segment of the error message.
+  # 
+  # Strings are simply returned. Other things are inspected (for now).
+  # 
+  # @param [Object] segment
+  #   The segment.
+  # 
+  # @return [String]
+  #   The formatted string for the segment.
+  # 
+  def format_message_segment segment
+    return segment if String === segment
     
-    # 2.
-      
-    if get_extended_message
-      got_extended_message = if get_extended_message.arity == 0
-        get_extended_message.call
+    # TODO  Do better!
+    segment.inspect
+  end # #format_message_segment
+  
+  
+  # Format the main message by converting args to strings and joining them.
+  # 
+  # @param [Array] *message
+  #   Message segments.
+  # 
+  # @return [String]
+  #   Formatted and joined message ready to pass up to the built-in
+  #   exception's `#initialize`.
+  # 
+  def format_message *message
+    message.map( &method( :format_message_segment ) ).join( ' ' )
+  end
+  
+  
+  # Main message to use when none provided to {#initialize}.
+  # 
+  # @return [String]
+  # 
+  def default_message
+    "(no message)"
+  end
+  
+  
+  # Any additional context values to add to extended messages provided to
+  # {#initialize}.
+  # 
+  # @return [Hash<Symbol, *>]
+  # 
+  def context
+    @context
+  end
+  
+  
+  def details
+    @details
+  end
+  
+  
+  # Render details (first time only, then cached) and return the string.
+  # 
+  # @return [String?]
+  # 
+  def details_section
+    lazy_var :@details_section do
+      # No details if we have nothing to work with
+      if details.nil?
+        nil
       else
-        get_extended_message.call context
+        contents = case details
+        when Proc
+          details.call
+        when String
+          details
+        else
+          details.to_s
+        end
+        
+        if contents.empty?
+          nil
+        else
+          if @binding
+            contents = binding.erb contents
+          end
+          
+          "# Details\n\n" + contents
+        end
       end
-      
-      got_extended_message_lines = NRSER.dedent \
-        got_extended_message,
-        return_lines: true
-      
-      if extended_message_lines
-        extended_message_lines += [
-          "\n",
-          *got_extended_message_lines
-        ]
+    end
+  end
+  
+  
+  # @return [String?]
+  # 
+  def context_section
+    lazy_var :@context_section do
+      if context.empty?
+        nil
       else
-        extended_message_lines = got_extended_message_lines
+        "# Context:\n\n" + context.map { |name, value|
+          name_str = name.to_s
+          value_str = PP.pp \
+            value,
+            ''.dup,
+            (NRSER::NicerError.column_width - name_str.length - 2)
+          
+          if value_str.lines.count > 1
+            "#{ name_str }:\n\n#{ value_str.indent 4 }\n"
+          else
+            "#{ name_str }: #{ value_str }\n"
+          end
+        }.join
       end
     end
-    
-    if add_context
-      extended_message_lines += [
-        "Context:\n",
-        "\n"
-        "\n    <%=  %>"
-      ]
-    end
+  end
+  
+  
+  # Return the extended message, rendering if necessary (cached after first
+  # call).
+  # 
+  # @return [String]
+  #   Will be empty if there is no extended message.
+  # 
+  def extended_message
+    @extended_message ||= begin
+      sections = []
+      
+      sections << details_section unless details_section.nil?
+      sections << context_section unless context_section.nil?
       
-  end # .render_message
+      joined = sections.join "\n\n"
+    end
+  end
   
   
-  # @todo Document initialize method.
+  # Should we add the extended message to {#to_s} output?
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
+  # @todo
+  #   Just returns `true` for now... should be configurable in the future.
   # 
-  # @return [return_type]
-  #   @todo Document return value.
+  # @return [Boolean]
   # 
-  def initialize  message,
-                  context: {},
-                  add_context: true,
-                  &
-    @context = context
-  end # #initialize
+  def add_extended_message?
+    true
+  end
+  
+  
+  # Get the message or the extended message.
+  # 
+  # @note
+  #   This is a bit weird, having to do with what I can tell about the
+  #   built-in errors and how they handle their message - they have *no*
+  #   instance variables, and seem to rely on `#to_s` to get the message
+  #   out of C-land, however that works.
+  #   
+  #   {Exception#message} just forwards here, so I overrode that with
+  #   {#message} to just get the *summary/super-message* from this method.
+  # 
+  # @param [Boolean?] extended:
+  #   Flag to explicitly control summary/super or extended message:
+  #   
+  #   1.  `nil` - call {#add_extended_message?} to decide (default).
+  #   2.  `false` - return just the *summary/super-message*.
+  #   3.  `true` - always add the *extended message* (unless it's empty).
+  # 
+  # @return [String]
+  # 
+  def to_s extended: nil
+    # The way to get the superclass' message
+    message = super()
+    
+    # If `extended` is explicitly `false` then just return that
+    return message if extended == false
+    
+    # Otherwise, see if the extended message was explicitly requested,
+    # of if we're configured to provide it as well.
+    # 
+    # Either way, don't add it it's empty.
+    # 
+    if  (extended || add_extended_message?) &&
+        !extended_message.empty?
+      message + "\n\n" + extended_message
+    else
+      message
+    end
+  end
   
 end # module NRSER::NicerError

data/lib/nrser/errors/type_error.rb

@@ -0,0 +1,46 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+require_relative './nicer_error'
+
+
+# Declarations
+# =======================================================================
+
+
+# Definitions
+# =======================================================================
+
+
+# Extension of {::ArgumentError} that includes {NRSER::NicerError} and
+# supports optional
+# 
+class NRSER::TypeError < ::TypeError
+  
+  include NRSER::NicerError
+  
+  
+  # Instance Methods
+  # ========================================================================
+  
+  # def expected
+  #   context[:expected]
+  # end
+  
+  # def default_message
+  #   ["Expected", name, ""]
+  # end
+  
+end # class NRSER::ArgumentError

data/lib/nrser/errors.rb

@@ -13,6 +13,9 @@
 require_relative './errors/value_error'
 require_relative './errors/attr_error'
 require_relative './errors/count_error'
+require_relative './errors/argument_error'
+require_relative './errors/type_error'
+require_relative './errors/abstract_method_error'
 
 
 module NRSER
@@ -22,58 +25,6 @@ module NRSER
   class ConflictError < StandardError; end
   
   
-  # Extension of Ruby's {NotImplementedError} to provide a useful message
-  # and convenient constructor for abstract methods.
-  # 
-  # @example
-  #   
-  #   def f
-  #     raise NRSER::AbstractMethodError.new( self, __method__ )
-  # 
-  # 
-  class AbstractMethodError < NotImplementedError
-    
-    # Construct a new `AbstractMethodError`.
-    # 
-    # @param [Object] instance
-    #   Instance that invoked the abstract method.
-    # 
-    # @param [Symbol | String] method_name
-    #   Name of abstract method.
-    # 
-    def initialize instance, method_name
-      @instance = instance
-      @method_name = method_name
-      @method = instance.method @method_name
-      
-      message = if @method.owner == instance.class
-        NRSER.dedent <<-END
-          Method #{ @method.owner.name }##{ @method_name } is abstract, meaning
-          #{ @method.owner.name } is an abstract class and the invoking
-          instance #{ @instance } should NOT have been constructed.
-        END
-      else
-        NRSER.squish <<-END
-          Method #{ @method.owner.name }##{ @method_name } is abstract and
-          has not been implemented in invoking class #{ @instance.class }.
-          
-          If you *are* developing the invoking class #{ @instance.class } it
-          (or a parent class between it and #{ @method.owner.name }) must
-          implement ##{ @method_name }.
-          
-          If you *are not* developing #{ @instance.class } it should be treated
-          as an abstract base class and should NOT be constructed. You need to
-          find a subclass of #{ @instance.class } to instantiate or write
-          your own.
-        END
-      end
-      
-      super message
-    end # #initialize
-    
-  end # class AbstractMethodError
-  
-  
   # A wrapper error around a list of other errors.
   # 
   class MultipleErrors < StandardError
@@ -103,7 +54,7 @@ module NRSER
         headline = "#{ errors.count } error(s) occurred - #{ class_counts }"
       end
       
-      message = NRSER.erb binding, <<-END
+      message = binding.erb <<-END
         <%= headline %>
         
         <% errors.each_with_index do |error, index| %>

data/lib/nrser/ext/tree.rb

@@ -1,3 +1,6 @@
+module NRSER::Ext; end
+
+
 # Instance methods that are refined in to the Ruby built-ins that we consider
 # trees: {Array}, {Hash} and {OpenStruct}.
 # 

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

@@ -11,11 +11,11 @@ module NRSER
   # get it's key, raising an error if multiple entries map to the same key.
   # 
   # @example Basic usage
-  #   ['a', :b].to_h_by &:class
+  #   ['a', :b].assoc_by &:class
   #   # => {String=>"a", Symbol=>:b}
   # 
   # @example Conflict error
-  #   [:a, :b].to_h_by &:class
+  #   [:a, :b].assoc_by &:class
   #   # NRSER::ConflictError: Key Symbol is already in results with value:
   #   #
   #   #     :a
@@ -37,7 +37,7 @@ module NRSER
       key = block.call element
       
       if result.key? key
-        raise NRSER::ConflictError.new erb binding, <<-END
+        raise NRSER::ConflictError.new binding.erb <<-END
           Key <%= key.inspect %> is already in results with value:
           
               <%= result[key].pretty_inspect %>
@@ -47,10 +47,7 @@ module NRSER
       
       result[key] = element
     }
-  end # .to_h_by
-  
-  singleton_class.send :alias_method, :to_h_by, :assoc_by
-  
+  end # .assoc_by
   
   
   # Create a {Hash} mapping the entries in `enum` to the value returned by
@@ -68,7 +65,7 @@ module NRSER
       value = if hash.key? entry
         case on_conflict
         when :raise
-          raise NRSER::ConflictError.new erb binding, <<-END
+          raise NRSER::ConflictError.new binding.erb <<-END
             Entry <%= entry %> appears more than once in `enum`
             
             This would cause conflict in the resulting {Hash}.
@@ -97,7 +94,7 @@ module NRSER
       
       hash[entry] = value
     }
-  end # .map_to
+  end # .assoc_to
   
   
 end # module NRSER

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

@@ -1,6 +1,5 @@
 require_relative './include_slice/array_include_slice'
 
-using NRSER
 
 module NRSER
   
@@ -54,11 +53,11 @@ module NRSER
       raise TypeError.new binding.erb <<-END
         Both `enum` and `slice` must be {Enumerable}
         
-        enum (<%= enum.class.name %>):
+        enum (<%= enum.class.safe_name %>):
         
             <%= enum.pretty_inspect %>
         
-        slice (<%= slice.class.name %>):
+        slice (<%= slice.class.safe_name %>):
         
             <%= slice.pretty_inspect %>
         

data/lib/nrser/functions/enumerable.rb

@@ -1,8 +1,6 @@
-require_relative './enumerable/find_map'
 require_relative './enumerable/find_all_map'
 require_relative './enumerable/include_slice'
 require_relative './enumerable/associate'
-require_relative './enumerable/map_values'
 
 module NRSER
   
@@ -64,7 +62,7 @@ module NRSER
     NRSER::Types.
       length(bounds).
       check(enum.find_all &block) { |type:, value:|
-        erb binding, <<-END
+        binding.erb <<-END
           
           Length of found elements (<%= value.length %>) FAILED to
           satisfy <%= type.to_s %>.

data/lib/nrser/functions/exception.rb

@@ -11,7 +11,7 @@ module NRSER
   # @return [String]
   # 
   def self.format_exception e
-    "#{ e.message } (#{ e.class }):\n  #{ e.backtrace.join("\n  ") }"
+    "#{ e.to_s } (#{ e.class }):\n  #{ e.backtrace.join("\n  ") }"
   end
   
 end # module NRSER

data/lib/nrser/functions/hash.rb

@@ -3,11 +3,5 @@
 
 # Project / Package
 # -----------------------------------------------------------------------
-require_relative './hash/except_keys'
-require_relative './hash/transform_keys'
-require_relative './hash/symbolize_keys'
-require_relative './hash/stringify_keys'
-require_relative './hash/slice_keys'
 require_relative './hash/guess_label_key_type'
 require_relative './hash/bury'
-require_relative './hash/deep_merge'

data/lib/nrser/functions/merge_by.rb

@@ -21,8 +21,8 @@ module NRSER
   #   Final array of merged hashes. Don't depend on order.
   # 
   def self.merge_by current, *updates, &merge_key
-    updates.reduce( to_h_by current, &merge_key ) { |result, update|
-      deep_merge! result, to_h_by( update, &merge_key )
+    updates.reduce( assoc_by current, &merge_key ) { |result, update|
+      result.deep_merge! assoc_by( update, &merge_key )
     }.values
   end # .merge_by