nrser 0.3.9 → 0.3.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8924f7337f324ced68cc42837909ecd01e31cbed
-  data.tar.gz: 9967780c03770b6f18214d6800107046db3ba3ae
+  metadata.gz: 2c105c78f752949b6b6f96460bb5369e3fa55097
+  data.tar.gz: a41c0ab138a2ce53510199cdc1fb48da0cc3e77d
 SHA512:
-  metadata.gz: e8bc8cfb3460f2c1bba1aeec16f5e9f7f56d431a5caddd01fea73422ddafb1dbe11503664a91103be82be48c51e7620794e11a052f414656baff4726bd271f3e
-  data.tar.gz: 5c48ccefb961b1308c8adf7b11aa225ce7a932ddc663c99d62e425ae7dacda93f572187fdacc86795b990950e7caff23b8e208a10b5b5484b3de4b03abcb7624
+  metadata.gz: d435115336cdf3abc0b2119c8748f7d2d440b6e327a55d7e27ed561df7d2648da4a4f6718b697daf5e73316a56b0d663cd0b87a141ec8220277b51431e89f550
+  data.tar.gz: fd2b59def500f548e4b774c880bbd9e98dfa0442ddb4c1253230c3e7cdadf4184b24440b60132ad58655a30d76510d7d1b85bf0762c7c94478adc9856212cf41

data/lib/nrser/char/alpha_numeric_sub.rb

@@ -141,21 +141,19 @@ class NRSER::Char::AlphaNumericSub
   # Constructor
   # ======================================================================
   
-  # Instantiate a new `Special`.
+  # Instantiate a new `AlphaNumericSub`.
   # 
-  # @param [String] char:
-  #   The actual character as a length 1 UTF-8 string.
+  # @param [String] sub_a
+  #   Character the lower-case `a` ASCII character gets replaced with.
   # 
-  # @param [nil | String] caret:
-  #   Optional `^X` replacement for control characters, see {#caret} for
-  #   details.
+  # @param [String] sub_A
+  #   Character the upper-case `A` ASCII character gets replaced with.
   # 
-  # @param [Array<#to_s>] names:
-  #   Optional names this character goes by.
+  # @param [String] sub_0
+  #   Character the `0` gets subbed out for.
   # 
-  # @param [nil | String] symbol:
-  #   Optional printable unicode character replacement, see {#symbol} for
-  #   details.
+  # @param [Hash?] exceptions
+  #   I don't know just read the source.
   # 
   def initialize  sub_a: nil,
                   sub_A: nil,
@@ -185,14 +183,6 @@ class NRSER::Char::AlphaNumericSub
   # Instance Methods
   # ======================================================================
   
-  # The first of {#names} (if any).
-  # 
-  # @return [nil]
-  #   When {#names} is empty.
-  # 
-  # @return [String]
-  #   When {#names} is not empty.
-  # 
   def sub src
     dest = src.dup
     

data/lib/nrser/char/special.rb

@@ -90,17 +90,17 @@ class NRSER::Char::Special
   
   # Instantiate a new `Special`.
   # 
-  # @param [String] char:
+  # @param [String] char
   #   The actual character as a length 1 UTF-8 string.
   # 
-  # @param [nil | String] caret:
+  # @param [nil | String] caret
   #   Optional `^X` replacement for control characters, see {#caret} for
   #   details.
   # 
-  # @param [Array<#to_s>] names:
+  # @param [Array<#to_s>] names
   #   Optional names this character goes by.
   # 
-  # @param [nil | String] symbol:
+  # @param [nil | String] symbol
   #   Optional printable unicode character replacement, see {#symbol} for
   #   details.
   # 
@@ -177,7 +177,7 @@ class NRSER::Char::Special
   # @param [String] string
   #   String to replace this character in.
   # 
-  # @param [Symbol | #to_s] with:
+  # @param [Symbol | #to_s] with
   #   What to replace the character with:
   #   
   #   1.  {Symbol} - this method will be called on the instance and the

data/lib/nrser/core_ext/array.rb

@@ -76,7 +76,7 @@ class Array
   #   [:fetch, :x].sender.call x: 'ex'
   #   # => 'ex'
   # 
-  # @param [Boolean] publicly:
+  # @param [Boolean] publicly
   #   When `true`, uses `#public_send` in liu of `#send`.
   # 
   # @return [Proc]
@@ -93,28 +93,51 @@ class Array
   end # #to_chainer
   
   
-  # Returns a lambda that calls accepts a single arg and calls `#dig` on it
-  # with the elements of *this* array as arguments.
+  # Returns a lambda that calls accepts a single arg and calls either:
+  # 
+  # 1.  `#[self.first]` if this array has only one entry.
+  # 2.  `#dig( *self )` if this array has more than one entry.
   # 
   # @example
   #   list = [{id: 1, name: "Neil"}, {id: 2, name: "Mica"}]
-  #   list.assoc_by &[:id].to_digger
+  #   list.assoc_by &[:id]
   #   # =>  {
   #   #       1 => {id: 1, name: "Neil"},
   #   #       2 => {id: 2, name: "Mica"},
   #   #     }
   # 
-  # @todo
-  #   I wanted to use `#to_proc` so that you could use `&[:id]`, but unary
-  #   `&` doesn't invoke refinements, and I don't really want to monkey-patch
-  #   anything, especially something as core as `#to_proc` and `Array`.
-  # 
   # @return [Proc]
-  #   Lambda proc that accepts a single argument and calls `#dig` with this
-  #   array's contents as the `#dig` arguments.
+  #   Lambda proc that accepts a single argument and calls `#[]` or `#dig with 
+  #   this array's contents as the arguments.
+  # 
+  def to_proc
+    method_name = case count
+    when 0
+      raise NRSER::CountError.new \
+        "Can not create getter proc from empty array",
+        value: self,
+        expected: '> 0',
+        count: count
+    when 1
+      :[]
+    else
+      :dig
+    end
+      
+    NRSER::Message.new( method_name, *self ).to_proc
+  end # #to_proc
+
+
+  # Old name for {#to_proc}.
+  # 
+  # @deprecated
   # 
   def to_digger
-    NRSER::Message.new( :dig, *self ).to_proc
-  end # #to_digger
+    NRSER.logger.deprecated \
+      method: "#{ self.class.name }##{ __method__ }",
+      alternative: "#{ self.class.name }#to_proc"
+
+    to_proc
+  end
 
 end # class Array

data/lib/nrser/core_ext/enumerable.rb

@@ -1,3 +1,4 @@
+require 'nrser/functions/enumerable/associate'
 require_relative './enumerable/find_map'
 
 

data/lib/nrser/core_ext/enumerable/find_map.rb

@@ -18,7 +18,7 @@ module Enumerable
   # @param [nil | Proc<()=>DEFAULT>] ifnone
   #   Optional lambda to call for the return value when no match is found.
   # 
-  # @param [Proc<(E)=>RESLUT>] &block
+  # @param [Proc<(E)=>RESLUT>] block
   #   Block mapping entires to results.
   # 
   # @return [nil]

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

@@ -1,3 +1,6 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
 require 'active_support/core_ext/object/deep_dup'
 
 class Hash

data/lib/nrser/core_ext/hash/extract_values_at.rb

@@ -31,10 +31,10 @@ class Hash
   #   hash
   #   # => {:c=>3, :d=>4}
   #   
-  # @param *keys
+  # @param keys
   #   Hash keys to extract.
   # 
-  # @param [#<<] into:
+  # @param [#<<] into
   #   Object to extract values at `keys` into.
   # 
   # @return [into]

data/lib/nrser/core_ext/method/full_name.rb

@@ -3,7 +3,7 @@ require_relative '../module/names'
 
 class Method
   
-  # Returns the method's {#receiver} and {#name} in the common
+  # Returns the method's {::Method#receiver} and {::Method#name} in the common
   # `A.cls_meth` / `A#inst_meth` format.
   # 
   def full_name

data/lib/nrser/core_ext/module/method_objects.rb

@@ -46,7 +46,7 @@ class Module
   # @param include_super  (see NRSER.method_objects_for)
   # @param sort:          (see NRSER.method_objects_for)
   # 
-  # @param [Boolean] include_initialize:
+  # @param [Boolean] include_initialize
   #   When `true`, include `#initialize` method if it's defined, which is
   #   normally excluded from {Module#instance_methods}.
   #   

data/lib/nrser/core_ext/module/source_locations.rb

@@ -108,27 +108,39 @@ class Module
   end
   
   
-  # Get *all* source locations for that module (or class) methods.
+  # Get *all* source locations for that module (or class) methods - class
+  # *and* instance methods.
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
+  # @param [Boolean] only_valid
+  #   Filter results to only valid source locations.
   # 
   # @return [Hash<Method, Array<String, Fixnum>>]
-  #   @todo Document return value.
   # 
   def method_locations only_valid: false
     # Get all the src locs for own methods
-    own_class_method_locations( only_valid: only_valid ).
-      map { |name, location|
-        [".#{ name }", location]
-      }.
-      to_h.
-      merge! \
-        own_instance_method_locations(  only_valid: only_valid,
-                                        include_initialize: true ).
-          map { |name, location|
-            ["##{ name }", location]
-          }.to_h
+    # own_class_method_locations( only_valid: only_valid ).
+    #   map { |name, location|
+    #     [".#{ name }", location]
+    #   }.
+    #   to_h.
+    #   merge! \
+    #     own_instance_method_locations(  only_valid: only_valid,
+    #                                     include_initialize: true ).
+    #       map { |name, location|
+    #         ["##{ name }", location]
+    #       }.to_h
+    
+    [
+      [ '.', own_class_method_locations(    only_valid: only_valid ) ],
+
+      [ '#', own_instance_method_locations( only_valid: only_valid,
+                                            include_initialize: true ) ],
+      
+    ].each_with_object( {} ) do |(prefix, method_locations), result|
+      method_locations.each do |name, location|
+        result["#{ prefix }#{ name }"] = location
+      end
+    end
   end # .module_source_locations
   
   

data/lib/nrser/core_ext/object/lazy_var.rb

@@ -14,7 +14,7 @@ class Object
   #   The name of the instance variable. Needs to have that `@` on the
   #   front, like `:@x`.
   # 
-  # @param [Proc<() => VALUE>] &block
+  # @param [Proc<() => VALUE>] block
   #   The block to call to get the value.
   # 
   # @return [VALUE]

data/lib/nrser/core_ext/pathname.rb

@@ -1,10 +1,31 @@
+# frozen_string_literal: true
+# encoding: UTF-8
+
+# Requirements
+# ========================================================================
+
+# Stdlib
+# ------------------------------------------------------------------------
+
 require 'pathname'
 
+# Project / Package
+# ------------------------------------------------------------------------
+
+
+# Definitions
+# ========================================================================
+
+# NRSER's extensions to the stdlib's `Pathname` class.
+# 
+# @see  https://ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html
+#       Pathname
+# 
 class Pathname
   
   # override to accept Pathname instances.
   # 
-  # @param [String] *prefixes
+  # @param [String] prefixes
   #   the prefixes to see if the Pathname starts with.
   # 
   # @return [Boolean]
@@ -21,26 +42,50 @@ class Pathname
   end
   
   
-  alias_method :_original_sub, :sub
+  # @!method _core_sub *args, &block
+  #   An `alias_method` reference to the `#sub` method as we found it, which
+  #   we'll use inside our override of {#sub}... and now you can too!
+  #   
+  #   Arguments are the same as [String#sub][].
+  #   
+  #   [String#sub]: https://ruby-doc.org/core/String.html#method-i-sub
+  #   
+  #   @see  https://ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html#method-i-sub
+  #         Ruby Stdlib Pathname#sub
+  #   
+  #   @return [Pathname]
+  # 
+  alias_method :_core_sub, :sub
   
   
-  # override sub to support Pathname instances as patterns.
+  # Our override of `#sub` to support {Pathname} instances as patterns.
+  # 
+  # Just calls `#to_s` on `pattern` if it's a {Pathname} before passing down
+  # to {#_core_sub}.
   # 
   # @param [String | Regexp | Pathname] pattern
-  #   thing to replace.
+  #   Thing to replace.
   # 
-  # @param [String | Hash] replacement
-  #   thing to replace it with.
+  # @param args
+  #   See Ruby core's [String#sub][], which [Pathname#sub][] calls between 
+  #   stringifying and re-wrapping in a {Pathname} (core's [String#sub][] is 
+  #   overloaded).
+  #   
+  #   [String#sub]: https://ruby-doc.org/core/String.html#method-i-sub
+  #   [Pathname#sub]: https://ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html#method-i-sub
+  # 
+  # @param [Proc] block
+  #   See [String#sub][].
   # 
   # @return [Pathname]
-  #   new Pathname.
+  #   A brand new Pathname boys and girls!
   # 
-  def sub pattern, replacement
+  def sub pattern, *args, &block
     case pattern
     when Pathname
-      _original_sub pattern.to_s, replacement
+      _core_sub pattern.to_s, *args, &block
     else
-      _original_sub pattern, replacement
+      _core_sub pattern, *args, &block
     end
   end
 
@@ -72,10 +117,10 @@ class Pathname
   # Shortcut to convert into a relative pathname, by default from the working
   # directory, with option to `./` prefix.
   # 
-  # @param [Pathname] base_dir:
+  # @param [Pathname] base_dir
   #   Directory you want the result to be relative to.
   # 
-  # @param [Boolean] dot_slash:
+  # @param [Boolean] dot_slash
   #   When `true` will prepend `./` to the resulting path, unless it already
   #   starts with `../`.
   # 
@@ -122,5 +167,15 @@ class Pathname
   def to_dot_rel_s **kwds
     to_rel_s( **kwds, dot_slash: true ).to_s
   end
+
+
+  # The "closest" directory - which is `self` if the instance is a
+  # {#directory?}, otherwise it's {#dirname}.
+  # 
+  # @return [Pathname]
+  # 
+  def closest_dir
+    directory? ? self : dirname
+  end
   
 end # class Pathname

data/lib/nrser/core_ext/pathname/subpath.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+# encoding: UTF-8
+
+# Requirements
+# ========================================================================
+
+# Stdlib
+# ------------------------------------------------------------------------
+
+require 'pathname'
+
+# Project / Package
+# ------------------------------------------------------------------------
+
+# Need {ValueError}
+require 'nrser/errors/value_error'
+
+
+# Definitions
+# ========================================================================
+
+class Pathname
+
+  # Is `other` a subpath of `self`?
+  # 
+  # Which - it turns out - is a bit of a ricky question! Who knew?!
+  # 
+  # Maybe that's why it's not in the stand' lib.
+  # 
+  # Here's how we gonna go:
+  # 
+  # 1.  Raise a {NRSER::ValueError} unless `self` is a {#directory?} and is
+  #     {#absolute?}.
+  #     
+  #     I don't think it make any sense to ask about subpaths of something that
+  #     is not a directory, and things just get too messy unless it's absolute
+  #     since we need to expand `other` to make sure it doesn't dot-dot-dig 
+  #     it's way outta there.
+  # 
+  # 2.  
+  # 
+  # @param [Boolean] strict
+  #   Decides behavior when `other` expands to the same directory as `self`:
+  #   
+  #   1.  When `strict: false` (the default) a directory **is** considered a 
+  #       subpath of itself.
+  #       
+  #   2.  When `strict: true`, a directory **is not** considered a subpath of
+  #       itself.
+  # 
+  # @return [Boolean]
+  #   `true` if `other` is a path inside `self`.
+  #   
+  #   See the `strict` parameter for behavior when `other` expands to `self`.
+  # 
+  # @raise [NRSER::ValueError]
+  #   If `self` is not a {#directory?}.
+  # 
+  # @raise [NRSER::ValueError]
+  #   If `self` is not {#absolute?}.
+  # 
+  def subpath? other, root: nil, strict: false
+    unless directory?
+      raise NRSER::ValueError.new \
+        "Receiver {Pathname}", self, "must be a {#directory} in order to test",
+        "for subpaths",
+        value: self
+    end
+
+    unless absolute?
+      raise NRSER::ValueError.new \
+        "Receiver {Pathname}", self, "must be {#absolute?} in order to test",
+        "for subpaths",
+        value: self
+    end
+
+    abs_other = other.to_pn.expand_path root
+
+    # Deal with easy case first, when they're the same dir
+    return !strict if self == abs_other
+
+    # Ok, now see if they prefix match
+    abs_other.start_with? self
+  end # #subpath?
+  
+end # class Pathname