nrser 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e2f2d4d8bf9243e750dd94962a0331985b7ec0ca
-  data.tar.gz: 55ae615d5733b4e183052cbe0afdc5cca39fd172
+  metadata.gz: 736ee433c6078e250b89ebbc65455ff157888b6e
+  data.tar.gz: a99e836e91a873ea4b06767376a6c38e30c2fe5a
 SHA512:
-  metadata.gz: 740ca5dd0ada05a5adb259c13f1e2ca5150308b26686f0ffa8d63e399ad748d5c36beea986623bea9884a1fdcdd690f4bce7d03e3b8cd124b615f3f99b11b860
-  data.tar.gz: 43421a77de4da50eb540cc1055e7a732f47b4a058af81898a63da68737b8a4bbe3c8d715d021d9d325580c8d623ffd8d2919fe39a9dd52826a8b458441c71a83
+  metadata.gz: ffed557cf2652d5d9b9af71c4eb65cda37a0a165cacb7f419d9e6717cbb810ab224e3a6710e6e762c72948707e7424180faafd6acd2ab3a310aa2a326422d794
+  data.tar.gz: 3b5307fc1dca415cb54a56ed32799b472c625c8a8d33d2dcef98e74e6ae85e21916cf2df5a211de3c4251c5e5828e5cb842942cf490cd10da8c5ad535ad8693b

data/lib/nrser/env/path.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+using NRSER
+
+
+# Declarations
+# =======================================================================
+
+
+# Definitions
+# =======================================================================
+
+# @todo document NRSER::Env::Path class.
+class NRSER::Env::Path
+  include Enumerable
+  include NRSER::Ext::Enumerable
+  
+  # Constants
+  # ======================================================================
+  
+  # Character used to separate path entries in string format.
+  # 
+  # @return [String]
+  # 
+  SEPARATOR = ':'
+  
+  
+  # Class Methods
+  # ======================================================================
+  
+  # @todo Document normalize method.
+  # 
+  # @param [nil | String | #each_index] source
+  #   Path source.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.normalize source
+    paths = if source.nil?
+      []
+    
+    elsif source.is_a?( String )
+      source.to_s.split SEPARATOR
+      
+    elsif NRSER.array_like?( source )
+      # Flatten it if supported
+      source = source.flatten if source.respond_to?( :flatten )
+      
+      # Stringify each segment, split them and concat results
+      source.flat_map { |entry| entry.to_s.split SEPARATOR }
+    
+    else
+      raise ArgumentError.new binding.erb <<-END
+        Expected a string or an "array-like" source, found:
+        
+            <%= source.pretty_inspect %>
+        
+      END
+    end
+    
+    Hamster::Vector.new paths.
+      # Get rid of empty paths
+      reject( &:empty? ).
+      # Get rid of duplicates
+      uniq.
+      # Freeze all the strings
+      map( &:freeze )
+  end # .normalize
+  
+  
+  # See if a `path` matches any of `patterns`.
+  # 
+  # Short-circuits as soon as a match is found (so patterns may not all be
+  # tested).
+  # 
+  # @param [String] path
+  #   Path to test against.
+  # 
+  # @param [Array<String | Proc<String=>Boolean> | Regexp>] *patterns
+  #   Patterns to test:
+  #   
+  #   -   `String` - test if it and `path` are equal (`==`)
+  #       
+  #   -   `Proc<String=>Boolean>` - call with `path` and evaluate result as
+  #       Boolean.
+  #       
+  #   -   `Regexp` - test if it matches `path` (`=~`)
+  # 
+  # @return [Boolean]
+  #   `true` if *any* of `patterns` match `path`.
+  # 
+  def self.matches_pattern? path, *patterns
+    patterns.any? do |pattern|
+      case pattern
+      when String
+        path == pattern
+      when Proc
+        pattern.call path
+      when Regexp
+        path =~ pattern
+      else
+        raise TypeError.new binding.erb <<-END
+          Each `*patterns` arg should be String, Proc or Regexp, found:
+          
+              <%= pattern.pretty_inspect %>
+          
+        END
+      end
+    end
+  end # .matches_pattern?
+  
+  
+  # @todo Document from_env method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.from_ENV env_key
+    new ENV[env_key.to_s], env_key: env_key
+  end # .from_env
+  
+  
+  # Attributes
+  # ======================================================================
+  
+  # Key for the value in `ENV` that the object represents. This is set when
+  # loading from `ENV` and used to know where to write when saving back to it.
+  # 
+  # @return [nil | String]
+  #     
+  attr_reader :env_key
+  
+  
+  # The object that was originally provided at construction.
+  # 
+  # @return [nil | String | #each_index]
+  #     
+  attr_reader :source
+  
+  
+  # The actual internal list of paths.
+  # 
+  # @return [Hamster::Vector<String>]
+  #     
+  attr_reader :value
+  
+  
+  # Constructor
+  # ======================================================================
+  
+  # Instantiate a new `NRSER::Env::Path`.
+  def initialize source, env_key: nil
+    @env_key = env_key.to_s.freeze
+    @source = source.dup.freeze
+    @value = self.class.normalize source
+  end # #initialize
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+  # 
+  # @param source (see .normalize)
+  # @return [self]
+  # 
+  def prepend source
+    # Normalize the new source to a flat array of strings
+    paths = self.class.normalize source
+    
+    # The new value is the normalized paths followed by the current paths
+    # with the new ones removed (de-duplication)
+    @value = (paths + @value).uniq
+    
+    # Return self for chain-ability
+    self
+  end
+  
+  alias_method :unshift, :prepend
+  alias_method :>>, :prepend
+  
+  
+  # 
+  # @param source (see .normalize)
+  # @return [self]
+  # 
+  def append source
+    # Normalize the new source to a flat array of strings
+    paths = self.class.normalize source
+    
+    # The new value is the current paths with the new paths appended, with
+    # any paths in the current path removed from the new ones (de-duplication)
+    @value = (@value + paths).uniq
+    
+    # Return self for chain-ability
+    self
+  end
+  
+  alias_method :push, :prepend
+  alias_method :<<, :prepend
+  
+  
+  def insert source, before: nil, after: nil
+    paths = self.class.normalize source
+    
+    before_index = if before
+      @value.find_index do |path|
+        self.class.matches_pattern? path, *before
+      end
+    end
+    
+    after_index = if after
+      index = @value.rindex { |path| self.class.matches_pattern? path, *after }
+      index += 1 if index
+    end
+    
+    insert_index = if after_index && before_index
+      # Make sure the conditions don't conflict with each other
+      if after_index > before_index
+        raise "Conflicting bounds!"
+      end
+      
+      # Insert as far "down" the path as allowed
+      [before_index, after_index].max
+    else
+      # Use the one that is not `nil`, or insert at the end if they both are
+      before_index || after_index || @value.length
+    end
+    
+    @value = @value.insert( insert_index, *paths ).uniq
+    
+    self
+  end
+  
+  
+  # Language Interop
+  # ============================================================================
+  
+  # Support for {Enumerable} mixin. Yields each path in order.
+  # 
+  # Specifically, proxies to {Hamster::Vector#each}
+  # 
+  # @see http://www.rubydoc.info/gems/hamster/Hamster/Vector#each-instance_method
+  # 
+  # @param [nil | Proc<(String)=>*>] &block
+  #   When present, block will be called once for each string path in this
+  #   object. First path is most prominent, down to least last.
+  # 
+  # @return [self]
+  #   When `&block` is provided.
+  # 
+  # @return [Enumerator]
+  #   When `&block` is omitted.
+  # 
+  def each &block
+    if block
+      # Proxy for yielding
+      @value.each &block
+      
+      # Return self for chain-ability
+      self
+    else
+      # Return the {Enumerator} from the vector
+      @value.each
+    end
+  end # #each
+  
+  
+  # The paths joined with ':'.
+  # 
+  # @return [String]
+  # 
+  def to_s
+    @value.join SEPARATOR
+  end
+  
+  
+  # The string paths in a new stdlib `Array`. Mutating this array will have no
+  # effect on the {NRSER::Env::Path} data.
+  # 
+  # @return [Array<String>]
+  # 
+  def to_a
+    @value.to_a
+  end
+  
+  protected
+  # ========================================================================
+    
+    # Internal method to remove paths that have already been normalized.
+    # 
+    # @param [type] arg_name
+    #   @todo Add name param description.
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    def remove_paths paths
+      # method body...
+    end # #remove_paths
+    
+    
+  # end protected
+  
+  
+end # class NRSER::Env::Path

data/lib/nrser/env.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Declarations
+# =======================================================================
+
+module NRSER::Env; end
+
+
+# Post-Processing
+# =======================================================================
+
+require_relative './env/path'

data/lib/nrser/errors/attr_error.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# 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.
+  # 
+  # @return [Symbol]
+  #     
+  attr_reader :symbol
+  
+  
+  # Actual invalid value of the subject's attribute.
+  # 
+  # If not provided at construction, will be retrieved by sending {#symbol}
+  # to {#subject} in {#initialize}.
+  # 
+  # @return [Object]
+  #     
+  attr_reader :actual
+  
+  
+  # An optional expected value to use in {#build_message}.
+  # 
+  # @return [Object]
+  #     
+  attr_reader :expected
+  
+  
+  # @param [Object] subject:
+  #   The object that has the invalid attribute value.
+  # 
+  def initialize message = nil, symbol:, subject:, **options
+    @symbol = symbol.to_sym
+    
+    @actual = if options.key?( :actual )
+      options[:actual]
+    else
+      value.send @symbol
+    end
+    
+    @has_expected = options.key? :expected
+    @expected = options[:expected]
+    
+    super message, subject: subject
+  end
+  
+  def has_expected?
+    @has_expected
+  end
+  
+  def build_message
+    headline = if has_expected?
+      "#{ subject.class } object has invalid ##{ symbol }: " +
+        "expected #{ expected }, found #{ actual }"
+    else
+      "#{ subject.class } object has invalid ##{ symbol } (found #{ actual })"
+    end
+    
+    binding.erb <<-END
+      <%= headline  %>
+      
+      Subject:
+      
+          <%= subject.pretty_inspect %>
+      
+    END
+  end
+  
+end # class NRSER::CountError

data/lib/nrser/errors/count_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# 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
+  end
+  
+  def count
+    actual
+  end
+end # class NRSER::CountError

data/lib/nrser/errors/nicer_error.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Definitions
+# =======================================================================
+
+# A mixin for {Exception} and utilities to make errors nicer.
+# 
+module NRSER::NicerError
+  
+  
+  # TODO document `context` attribute.
+  # 
+  # @return [Hash<Symbol, V>]
+  #     
+  attr_reader :context
+  
+  
+  # @todo Document render_message method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  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
+    
+    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
+    
+    # Ok, `short_message` is a single line string
+    #     `extended_message_lines` is an array of string lines or `nil`
+    
+    # 2.
+      
+    if get_extended_message
+      got_extended_message = if get_extended_message.arity == 0
+        get_extended_message.call
+      else
+        get_extended_message.call context
+      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
+        ]
+      else
+        extended_message_lines = got_extended_message_lines
+      end
+    end
+    
+    if add_context
+      extended_message_lines += [
+        "Context:\n",
+        "\n"
+        "\n    <%=  %>"
+      ]
+    end
+      
+  end # .render_message
+  
+  
+  # @todo Document initialize method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def initialize  message,
+                  context: {},
+                  add_context: true,
+                  &
+    @context = context
+  end # #initialize
+  
+end # module NRSER::NicerError

data/lib/nrser/errors/value_error.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+
+# 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):
+# 
+# 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.
+# 
+class NRSER::ValueError < StandardError
+  
+  # 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`.
+  # 
+  # 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 build_message
+    raise NRSER::AbstractMethodError.new( self, __method__ )
+  end
+  
+end

data/lib/nrser/errors.rb

@@ -1,3 +1,20 @@
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative './errors/value_error'
+require_relative './errors/attr_error'
+require_relative './errors/count_error'
+
+
 module NRSER
   
   # Indicates some piece of application state is in conflict with the attempted
@@ -5,7 +22,7 @@ module NRSER
   class ConflictError < StandardError; end
   
   
-  # Extension of Ruby's {NotImplementedError} to provide a useful message 
+  # Extension of Ruby's {NotImplementedError} to provide a useful message
   # and convenient constructor for abstract methods.
   # 
   # @example
@@ -31,22 +48,22 @@ module NRSER
       
       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 
+          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 
+          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 
+          (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 
+          find a subclass of #{ @instance.class } to instantiate or write
           your own.
         END
       end

data/lib/nrser/functions/enumerable.rb

@@ -193,8 +193,10 @@ module NRSER
   #   If `enum` does not have `#count == 1`.
   # 
   def self.only! enum
-    unless enum.count == 1
-      raise ArgumentError.new erb binding, <<-END
+    count = enum.count
+    
+    unless count == 1
+      message = erb binding, <<-END
         Expected enumerable to have #count == 1 but it has
         
         #count = <%= enum.count %>
@@ -204,6 +206,11 @@ module NRSER
             <%= enum.pretty_inspect %>
         
       END
+      
+      raise NRSER::CountError.new message,
+                                  subject: enum,
+                                  count: count,
+                                  expected: 1
     end
     
     enum.first