nrser 0.3.9 → 0.3.10

data/lib/nrser/core_ext/string.rb

@@ -6,6 +6,33 @@ require 'nrser/sys/env'
 # Extension methods for {String}
 # 
 class String
+
+  # The method I alias as unary `~`, with a full-name so I can find it and
+  # such, I guess.
+  # 
+  # It's a string formatter. Right now, it just calls {#squish}, but I would
+  # like to make it a bit smarter soon so it can be used on 
+  # paragraph-structured text too.
+  # 
+  # It's meant to be used with the `%{}` string quote form, because that allows
+  # multi-line strings, but nothing stopping it from being used elsewhere too.
+  # 
+  # @example
+  # 
+  #     ~%{
+  #       Hey there, here's some "stuff",
+  #       and here's some MORE!
+  #     }
+  #     # => "Hey there, here's some \"stuff\", and here's some MORE!"
+  # 
+  # @return [String]
+  # 
+  def squiggle
+    squish
+  end
+
+  alias_method :~@, :squiggle
+
   
   def unblock
     NRSER.unblock self
@@ -72,7 +99,7 @@ class String
   # 
   # Use {Regexp} ones at your own pleasure and peril.
   # 
-  # @param [String | Regexp] *prefixes
+  # @param [String | Regexp] prefixes
   #   Strings behave as usual per the standard lib.
   #   
   #   Regexp sources are used to create a new Regexp with `\A` at the start -

data/lib/nrser/core_ext/symbol.rb

@@ -1,13 +1,12 @@
 class Symbol
-  
-  # See {NRSER.retriever}.
-  def to_retriever
-    NRSER.retriever self
-  end
-  
-  
-  # Alias 'sender' methods to built-in {#to_proc} so symbols can behave like
-  # arrays in this way
-  alias_method :to_sender,  :to_proc
-  
-end # NRSER
+
+  # Proxy through to built-in {#to_proc} so symbols match the {Array#to_sender}
+  # API. I guess.
+  # 
+  # @return [Proc]
+  #   Accepts one argument and sends itself to that object, returning the
+  #   result.
+  # 
+  def to_sender; self.to_proc; end
+  
+end # class Symbol

data/lib/nrser/errors/README.md

@@ -0,0 +1,154 @@
+About `nrser/errors`
+==============================================================================
+
+{NRSER}'s error pseudo-module (everything in this directory is namespaced
+directly under {NRSER} for brevity) is centered around the {NicerError}
+mixin, which, well... tries to make working with errors a little nicer.
+
+It includes:
+
+1.  "Nice" extensions of some builtin error classes:
+    1.  {NRSER::AbstractMethodError} < {::NotImplementedError}
+        -   For when an abstract method is mistakenly called.
+    2.  {NRSER::ArgumentError} < {::ArgumentError}
+        -   A nice extensions of a familiar favorite.
+    3.  {NRSER::TypeError} < {::TypeError}
+        -   A nice why to say they're not my type. Used extensively in 
+            {NRSER::Types}, which is kind of like Tinder profiles for Ruby 
+            objects.
+2.  New "nice" extensions of {::StandardError}, and extensions of them:
+    1.  {NRSER::ValueError} < {::StandardError}>
+        -   For when a problem is discovered with a value that is not an 
+            argument, and the problem is not it's type.
+    2.  {NRSER::AttrError} < {NRSER::ValueError}
+        -   Raise me when there's an issue with a attribute of an object.
+    3.  {NRSER::CountError} < {NRSER::AttrError}
+        -   For when `#count` doesn't add up. I know, this one is weirdly
+            specific, but it solved something from what I remember.
+
+You can check out the doc-strings to those various classes for details. For the
+rest of this I'm going to focus on what the {NRSER::NicerError} mixin brings to
+the table.
+
+Let's check out some of the nicer features!
+
+
+1.) API Compatibility with Built-In Errors
+------------------------------------------------------------------------------
+
+This one is important. {NRSER::NicerError} strictly enhances the standard Ruby
+{Exception} API, meaning those classes can still be constructed with the
+
+    MyError.new( message_string )
+
+form, and produce the error they should show at `MyError#message` and
+`MyError#to_s`. Everything else is added on and optional, should you chose to
+use it, though you will of course pay some slight performance penalty using
+nicer errors in that way over the built-in classes.
+
+I also want to stick with this policy for mixing classes unless they are very
+specifically focused, like {NRSER::Types::CheckError}, which requires `value`
+and `type` keyword arguments, and things like a hypothetical HTTP error that
+requires the status code, etc., and want to extend the policy to cover the
+{NRSER::NicerError} general construction form:
+
+    MyError.new *message, details:, **context
+
+With general errors for general use, I've found it sucks to try and remember 
+various parameter forms and how they get stitched together when you're on a 
+roll or in a hurry, and I know it will impose even more overhead on people that
+didn't write the library.
+
+Errors should be easy as possible to use; they're already kind-of a pain as is.
+
+
+2.) Splat `message`
+------------------------------------------------------------------------------
+
+Accept an variable amount of positional arguments as a `message` {Array}
+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
+adding `#to_s`, `#inspect`, `#pretty_inspect`, etc. all over the place.
+
+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. For example, you might want to
+produce rich messages with detailed dumps that take more time to format and
+space to store while developing and produce concise messages that are cheap
+to produce and store in production.
+
+> Of course, in line with (1), you can always string-format elements of
+> `message` yourself, and the resulting strings will be joined into the final
+> message. You can also just pass a single string like Ruby's builtin
+> exceptions, maintaining the same API.
+
+
+3.) "Extended" Messages - `details` and `context`
+------------------------------------------------------------------------------
+
+The normal message that we talked about in (2) - that we call the *summary
+message* or *super-message* (since it gets passed up to the built-in
+{StandardError#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, just gets rescued anyways, there's no one there to read it,
+        etc.).
+        
+2.  Cheap to render and store.
+    -   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, {NRSER::NicerError} introduces the
+idea of an *extended message* that does not need to be rendered and
+output along with the *summary/super-message*.
+
+Extended messages are rendered on-demand, so systems that are not configured to
+use it will pay a minimal cost for it's existence.
+
+> See {NRSER::NicerError#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
+{NRSER::NicerError#initialize}.
+
+Those values may be accessed via {NRSER::NicerError#details} and 
+{NRSER::NicerError#context}, and rendered to strings 
+
+
+3.) Default Message
+------------------------------------------------------------------------------
+
+While (1) lets you know you should always be able to use the Ruby and nicer 
+construction forms on all but super-specific errors, {NRSER::NicerError} also
+gives you the option of brevity with support for *default messages*, which
+are constructed when no positional `message` arguments are passed to its
+constructor.
+
+Default messages presumably use the values of some well-known context values to
+render the user-facing string, and degrade into some sort of complaint if
+they're absent (someone could always be a wanker and call `MyError.new`, in
+which case you're left with little resort but tell them so).
+
+You can define default message behavior by overriding `#default_message` after
+mixing-in {NRSER::NicerError}. Please practice caution in this - as well as 
+all error methods: don't cause errors when handling errors.

data/lib/nrser/errors/attr_error.rb

@@ -1,73 +1,166 @@
 # frozen_string_literal: true
+# encoding: UTF-8
+
+# Requirements
+# ========================================================================
+
+require_relative './value_error'
+
+
+# Namespace
+# ========================================================================
+
+module  NRSER
+
 
 # Raised when we expected `#count` to be something it's not.
 # 
 # Extends {NRSER::ValueError}, and the {#value} must be the instance that
 # 
-class NRSER::AttrError < NRSER::ValueError
-  
-  # Name of attribute that has invalid value.
+class AttrError < ValueError
+
+  # @!method name?
+  #   Is there an `:name` key in {#context}?
+  #   
+  #   @return [Boolean]
   # 
-  # @return [Symbol]
-  #     
-  attr_reader :symbol
-  
-  
-  # Actual invalid value of the subject's attribute.
+  # @!method name
+  #   Name of attribute that has invalid value, which can be provided via
+  #   the `:name` key in the {#context}.
+  #   
+  #   @return [Symbol | String]
   # 
-  # If not provided at construction, will be retrieved by sending {#symbol}
-  # to {#subject} in {#initialize}.
+  def_context_delegator keys: :name
+
+
+  # @!method expected?
+  #   Is there an `:expected` key in {#context}?
+  #   
+  #   @return [Boolean]
+  #   
+  # @!method expected
+  #   Optional information about what the attribute value was expected to be,
+  #   which can be provided via the `:expected` key in {#context}.
+  #   
+  #   @return [Object]
   # 
-  # @return [Object]
+  def_context_delegator keys: :expected
+
+
+  # @!method initialize *message, **kwds
+  #   Create a new {AttrError}.
+  #   
+  #   This method does nothing but call `super`. It's here only for doc's sake.
+  #   
+  #   @note
+  #     If you provide the `:name` and `:value` keyword arguments, but *not* 
+  #     `:actual` then {#actual} will attempt to retrieve the attribute's value
+  #     by
   #     
-  attr_reader :actual
-  
-  
-  # An optional expected value to use in {#build_message}.
+  #         value.public_send name
+  #     
+  #     This really *shouldn't* be problematic - if attempting to access a public
+  #     attribute can cause serious side-effects, you may want to re-think your
+  #     design. However, I still felt like I should note it here.
+  #     
+  #     The call is wrapped in a `rescue StandardError`, so you **don't** need
+  #     to worry about anything mundane like an error being raised.
+  #   
+  #   @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 [Symbol | String] :name
+  #     The name of the attribute in question.
+  #   
+  #   @option kwds [Object] :value
+  #     The value that has the bad attribute.
+  #   
+  #   @option kwds [Object | NRSER::Types::Type | String] :expected
+  #     Encouraged to be one of:
+  #     
+  #     1.  The {Object} you wanted the attribute to respond with.
+  #         
+  #     2.  A {NRSER::Types::Type} satisfied by what you would have been satisfied
+  #         with.
+  #         
+  #     3.  A {String} explanation of the condition.
+  #   
+  #   @option kwds [Object] :actual
+  #     The actual attribute value.
+  #     
+
+
+  # Tests if an 'actual' value was provided in the {#context}.
+  # 
+  # @return [Boolean]
+  # 
+  def actual?
+    context.key?( :actual ) || ( value? && name? && value.respond_to?( name ) )
+  rescue StandardError => error
+    false
+  end
+
+
+  # Get an optional actual value for the attribute, from `context[:actual]`
+  # if it exists or by sending {#name} to {#value} if it works.
+  # 
+  # @return [nil]
+  #   If {#context} does not have an `:actual` value and {#value} raises
+  #   a {StandardError}.
   # 
   # @return [Object]
-  #     
-  attr_reader :expected
-  
-  
-  # @param [Object] subject:
-  #   The object that has the invalid attribute value.
+  #   The value of {#context}'s `:actual` key, if any, otherwise {#value}'s
+  #   response to {#name}.
   # 
-  def initialize message = nil, symbol:, subject:, **options
-    @symbol = symbol.to_sym
-    
-    @actual = if options.key?( :actual )
-      options[:actual]
-    else
-      value.send @symbol
+  def actual
+    if context.key? :actual
+      context[ :actual ]
+    elsif value? && name?
+      value.public_send name
     end
-    
-    @has_expected = options.key? :expected
-    @expected = options[:expected]
-    
-    super message, subject: subject
-  end
-  
-  def has_expected?
-    @has_expected
+  rescue StandardError => error
+    nil
   end
+
   
-  def build_message
-    headline = if has_expected?
-      "#{ subject.class } object has invalid ##{ symbol }: " +
-        "expected #{ expected }, found #{ actual }"
+  # Create a default message if none was provided.
+  # 
+  # Uses whatever recognized {#context} values are present, falling back
+  # to {NicerError#default_message} if none are.
+  # 
+  # @return [String]
+  # 
+  def default_message
+    message = []
+
+    if value? && name?
+      message << format_message(  value.class, "object", value.inspect,
+                                  "has invalid ##{ name } attribute" )
+    end
+
+    if expected?
+      message << format_message( "expected", expected )
+    end
+
+    if actual?
+      message << format_message( "found", actual )
+    end
+
+    if message.empty?
+      super
     else
-      "#{ subject.class } object has invalid ##{ symbol } (found #{ actual })"
+      message.join ', '
     end
-    
-    binding.erb <<-END
-      <%= headline  %>
-      
-      Subject:
-      
-          <%= subject.pretty_inspect %>
-      
-    END
   end
   
-end # class NRSER::CountError
+end # class AttrError
+
+
+# /Namespace
+# ========================================================================
+
+end # module NRSER

data/lib/nrser/errors/count_error.rb

@@ -1,19 +1,68 @@
 # frozen_string_literal: true
+# encoding: UTF-8
+
+# Requirements
+# ========================================================================
+
+# Project / Package
+# ------------------------------------------------------------------------
+
+require_relative './attr_error'
+
+
+# Namespace
+# ========================================================================
+
+module  NRSER
+
+
+# Definitions
+# ========================================================================
 
 # Raised when we expected `#count` to be something it's not.
 # 
-# Extends {NRSER::ValueError}, and the {#value} must be the instance that
-# 
 class NRSER::CountError < NRSER::AttrError
-  def initialize message = nil, subject:, expected:, count: nil
-    super message,
-      subject: subject,
-      symbol: :count,
-      actual: (count || subject.count),
-      expected: expected
+
+  # Create a new {CountError}.
+  # 
+  # @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 value that has the bad `#count`.
+  # 
+  # @option kwds [Integer | NRSER::Types::Type | String] :expected
+  #   Encouraged to be one of:
+  #   
+  #   1.  An exact {Integer} that you were looking for.
+  #       
+  #   2.  A {NRSER::Types::Type} satisfied by what you would have been satisfied
+  #       with.
+  #       
+  #   3.  A {String} explanation of the condition.
+  # 
+  # @option kwds [Integer] :actual
+  #   The actual count.
+  # 
+  def initialize *message, **kwds
+    kwds[:actual] = kwds.delete( :count ) if kwds.key?( :count )
+    super *message, **kwds, name: :count
   end
+
+  # Alias for {#actual?}.
+  def count?; actual?; end
   
-  def count
-    actual
-  end
-end # class NRSER::CountError
+  # Alias for {#actual}.
+  def count; actual; end
+
+end # class CountError
+
+
+# /Namespace
+# ========================================================================
+
+end # module NRSER