nrser 0.2.2 → 0.3.0

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

@@ -0,0 +1,214 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Need {Module#anonymous?}
+require 'active_support/core_ext/module/anonymous'
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+# Need {String#underscore}, etc.
+require 'nrser/core_ext/string'
+
+# Need {NRSER::Meta::Source::Location.for_methods}
+require 'nrser/meta/source/location'
+
+# Need {Module.class_method_objects}, etc.
+require_relative './method_objects'
+
+
+# Definitions
+# =======================================================================
+
+# Extension methods for {Module}
+# 
+class Module
+  
+  # @!group Source Location Readers
+  # ==========================================================================
+  
+  # Map class method names to the their source locations.
+  # 
+  # @see NRSER::Meta::Source::Location.for_methods
+  # 
+  # @param include_super  (see Module#class_method_objects)
+  # @param sort:          (see Module#class_method_objects)
+  # @param only_valid:    (see NRSER::Meta::Source::Location.for_methods)
+  # 
+  # @return (see NRSER::Meta::Source::Location.for_methods)
+  # 
+  def class_method_locations  include_super = true,
+                              sort: true,
+                              only_valid: false
+    NRSER::Meta::Source::Location.for_methods \
+      class_method_objects( include_super, sort: sort ),
+      only_valid: only_valid
+  end
+  
+  
+  # Just calls {#class_method_locations} with `include_super = false`.
+  # 
+  # @param sort:        (see #class_method_locations)
+  # @param only_valid:  (see #class_method_locations)
+  # 
+  # @return             (see #class_method_locations)
+  # 
+  def own_class_method_locations  sort: true,
+                                  only_valid: false
+    class_method_locations false, sort: sort, only_valid: only_valid
+  end
+  
+  
+  # Map instance method names to the their source locations.
+  # 
+  # @see NRSER::Meta::Source::Location.for_methods
+  # 
+  # @param include_super        (see Module#instance_method_objects)
+  # @param sort:                (see Module#instance_method_objects)
+  # @param include_initialize:  (see Module#instance_method_objects)
+  # @param only_valid:          (see NRSER::Meta::Source::Location.for_methods)
+  # 
+  # @return (see NRSER::Meta::Source::Location.for_methods)
+  # 
+  def instance_method_locations   include_super = true,
+                                  sort: true,
+                                  include_initialize: false,
+                                  only_valid: false
+    NRSER::Meta::Source::Location.for_methods \
+      instance_method_objects(
+        include_super,
+        sort: sort,
+        include_initialize: include_initialize,
+      ),
+      only_valid: only_valid
+  end
+  
+  
+  # Just calls {#instance_method_locations} with `include_super = false`.
+  # 
+  # @param sort:                (see #instance_method_locations)
+  # @param include_initialize:  (see #instance_method_locations)
+  # @param only_valid:          (see NRSER::Meta::Source::Location.for_methods)
+  # 
+  # @return (see #instance_method_locations)
+  # 
+  def own_instance_method_locations sort: true,
+                                    include_initialize: false,
+                                    only_valid: false
+    instance_method_locations sort: sort,
+                              include_initialize: include_initialize,
+                              only_valid: only_valid
+  end
+  
+  
+  # Get *all* source locations for that module (or class) methods.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @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
+  end # .module_source_locations
+  
+  
+  # Get the "canonical" lib-relative path for this module based off it's
+  # {#name} (via {String#underscore}, with `'.rb'` suffixed).
+  # 
+  # @todo
+  #   I bet ActiveSupport has some method for this re auto-loading.
+  # 
+  # @return [nil]
+  #   If this module is {#anonymous?}.
+  # 
+  # @return [Pathname]
+  #   If this module is not {#anonymous?}.
+  # 
+  def canonical_rel_path
+    if anonymous?
+      nil
+    else
+      Pathname.new( name.underscore + '.rb' )
+    end
+  end # #canocical_rel_path
+  
+  
+  # Try to find a reasonable file and line for the module (or class) by
+  # looking at the locations of it's methods.
+  # 
+  # @return [NRSER::Meta::Source::Location]
+  #   Two entry array; first entry is the string file path, second is the
+  #   line number.
+  #   
+  #   Note that both will be `nil` if we can't find a source location
+  #   (the location will not be {NRSER::Meta::Source::Location#valid?}).
+  # 
+  def source_location
+    # Get all the src locs for all methods
+    locations = method_locations only_valid: true
+    
+    # Short circuit if we don't have shit to work with...
+    return NRSER::Meta::Source::Location.new if locations.empty?
+    
+    # If any files end with the "canonical path" then use that. It's a path
+    # suffix
+    # 
+    #     "my_mod/sub_mod/some_class.rb"
+    # 
+    # the for a class
+    # 
+    #     MyMod::SubMod::SomeClass
+    # 
+    canonical_rel_path = self.canonical_rel_path
+    
+    unless canonical_rel_path.nil?
+      
+      # Find first line in canonical path (if any)
+      canonical_path_location = locations.
+        values.
+        find_all { |(path, line)| path.end_with? canonical_rel_path.to_s }.
+        min_by { |(path, line)| line }
+      
+      # If we found one, we're done!
+      return canonical_path_location if canonical_path_location
+      
+    end
+    
+    # OK, that didn't work, so...
+    
+    # If it's a {Class} and it has an `#initialize` method, point there.
+    # 
+    if is_a?( Class ) && locations['#initialize']
+      return locations['#initialize']
+    end
+    
+    # No dice. Moving on...
+    
+    # Get the first line on the shortest path
+    locations.values.min_by { |(path, line)|
+      [path.length, line]
+    }
+  end # .module_source_location
+  
+  # @!endgroup Source Location Readers
+  
+end # class Module

data/lib/nrser/core_ext/module.rb

@@ -0,0 +1,2 @@
+require_relative './module/method_objects'
+require_relative './module/source_locations'

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

@@ -0,0 +1,31 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+
+class Object
+  
+  # If the instance variable `name` is not defined, sets it to the result
+  # of `&block`. Always returns the instance variable's value.
+  # 
+  # Useful for lazy values that can be `nil` or `false`, since `||=` will
+  # always re-evaluate in their cases.
+  # 
+  # @param [Symbol] name
+  #   The name of the instance variable. Needs to have that `@` on the
+  #   front, like `:@x`.
+  # 
+  # @param [Proc<() => VALUE>] &block
+  #   The block to call to get the value.
+  # 
+  # @return [VALUE]
+  #   The value of the instance variable.
+  # 
+  def lazy_var name, &block
+    unless instance_variable_defined? name
+      instance_variable_set name, block.call
+    end
+    
+    instance_variable_get name
+  end # #lazy_instance_var
+  
+end

data/lib/nrser/core_ext/object.rb

@@ -0,0 +1,46 @@
+
+class Object
+  # Yield `self`. Analogous to {#tap} but returns the result of the invoked
+  # block.
+  def thru
+    yield self
+  end
+  
+  
+  # Just an alias for `#equal?` that is easier for to remember.
+  # 
+  # @param [*] other
+  #   Something else.
+  # 
+  # @return [Boolean]
+  #   `true` if `self` and `other` are the same object.
+  # 
+  def is? other
+    equal? other
+  end
+  
+  
+  # See {NRSER.truthy?}.
+  def truthy?
+    NRSER.truthy? self
+  end
+  
+  
+  # See {NRSER.falsy?}.
+  def falsy?
+    NRSER.falsy? self
+  end
+  
+  
+  # Calls {NRSER.as_hash} on `self` with the provided `key`.
+  def as_hash key = nil
+    NRSER.as_hash self, key
+  end
+  
+  
+  # Call {NRSER.as_array} on `self`.
+  def as_array
+    NRSER.as_array self
+  end
+  
+end # class Object

data/lib/nrser/core_ext/open_struct.rb

@@ -0,0 +1,6 @@
+class OpenStruct
+  # See {NRSER.to_open_struct}.
+  def self.from_h hash, freeze: false
+    NRSER.to_open_struct hash, freeze: freeze
+  end # .from
+end # class OpenStruct

data/lib/nrser/{ext → core_ext}/pathname.rb

@@ -1,6 +1,6 @@
+require 'pathname'
 
-# @todo document NRSER::Ext::Pathname module.
-module NRSER::Ext::Pathname
+class Pathname
   
   # override to accept Pathname instances.
   # 
@@ -15,6 +15,9 @@ module NRSER::Ext::Pathname
   end
   
   
+  alias_method :_original_sub, :sub
+  
+  
   # override sub to support Pathname instances as patterns.
   # 
   # @param [String | Regexp | Pathname] pattern
@@ -29,9 +32,9 @@ module NRSER::Ext::Pathname
   def sub pattern, replacement
     case pattern
     when Pathname
-      super pattern.to_s, replacement
+      _original_sub pattern.to_s, replacement
     else
-      super pattern, replacement
+      _original_sub pattern, replacement
     end
   end
 
@@ -71,4 +74,4 @@ module NRSER::Ext::Pathname
     NRSER.find_up! rel_path, **kwds, from: self
   end # #find_root
   
-end # module NRSER::Ext::Pathname
+end # class Pathname

data/lib/nrser/{ext → core_ext}/string.rb

@@ -1,11 +1,10 @@
+require 'pathname'
+require 'active_support/core_ext/string/filters'
+require 'active_support/core_ext/string/inflections'
+
 # Extension methods for {String}
 # 
-module NRSER::Ext::String
-  
-  def squish
-    NRSER.squish self
-  end
-  
+class String
   
   def unblock
     NRSER.unblock self
@@ -22,11 +21,6 @@ module NRSER::Ext::String
   end
   
   
-  def truncate *args
-    NRSER.truncate self, *args
-  end
-  
-  
   # See {NRSER.constantize}
   def constantize
     NRSER.constantize self
@@ -88,4 +82,4 @@ module NRSER::Ext::String
   
   # @!endgroup Unicode Stylization
   
-end # module NRSER::Ext::String
+end # class String

data/lib/nrser/core_ext/symbol.rb

@@ -0,0 +1,13 @@
+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

data/lib/nrser/core_ext/time.rb

@@ -0,0 +1,46 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+require 'time'
+
+# Deps
+# ------------------------------------------------------------------------
+
+require 'active_support/core_ext/time'
+
+
+# Definitions
+# =======================================================================
+
+class Time
+  
+  # `#iso8601` with the `-` and `:` characters removed. Intended to be more
+  # agreeable to a wider range of file systems and programs than the standard
+  # format, while still adhering to ISO 8601 (as far as I can tell) and
+  # acceptable to {Time.parse}.
+  # 
+  # There is nothing tricky about this method; I just wanted to standardize a
+  # format for these situations. I *hate* reading date-times like this, but
+  # it seems like the best and safest approach :/
+  # 
+  # @example
+  #   time = Time.now
+  #   
+  #   time.iso8601
+  #   # => "2018-04-19T03:00:30+08:00" # Nice, but potentially problematic
+  #   
+  #   Time.now.iso8601_for_files
+  #   # => "20180419T030030+8000" # Fucking ugly, but easier on stupid systems
+  # 
+  # @return [String]
+  # 
+  def iso8601_for_idiots
+    iso8601.gsub /\-\:/, ''
+  end # #iso8601_for_idiots
+  
+end

data/lib/nrser/core_ext.rb

@@ -0,0 +1,13 @@
+# Requires *ALL* of the core extensions
+
+require_relative './core_ext/array'
+require_relative './core_ext/binding'
+require_relative './core_ext/enumerable'
+require_relative './core_ext/exception'
+require_relative './core_ext/hash'
+require_relative './core_ext/module'
+require_relative './core_ext/object'
+require_relative './core_ext/open_struct'
+require_relative './core_ext/pathname'
+require_relative './core_ext/string'
+require_relative './core_ext/symbol'

data/lib/nrser/errors/abstract_method_error.rb

@@ -0,0 +1,150 @@
+require 'nrser/core_ext/object/lazy_var'
+
+require_relative './nicer_error'
+
+# Extension of Ruby's {NotImplementedError} to provide a useful message
+# and convenient constructor for abstract methods.
+# 
+# This is a {NRSER::NicerError}.
+# 
+# @example
+#   
+#   def f
+#     raise NRSER::AbstractMethodError.new( self, __method__ )
+# 
+# 
+class NRSER::AbstractMethodError < NotImplementedError
+  
+  # Mixins
+  # ========================================================================
+  
+  # Be nicer!
+  include NRSER::NicerError
+  
+  # Be log!
+  include NRSER::Log::Mixin
+  
+  
+  # Attributes
+  # ========================================================================
+  
+  # The abstract method's name that was called¹.
+  # 
+  # > ¹ I mean, that's what it *should* be, it's really just what was passed
+  # >   as the `method_name:` keyword to {#initialize}.
+  # 
+  # @return [Symbol]
+  #     
+  attr_reader :method_name
+  
+  
+  # TODO document `method_instance` attribute.
+  # 
+  # @return [Method]
+  #     
+  attr_reader :method_instance
+  
+  
+  
+  # TODO document `instance` attribute.
+  # 
+  # @return [attr_type]
+  #     
+  attr_reader :instance
+  
+  
+  
+  # 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 = instance.method @method_name
+    
+    super()
+  end # #initialize
+  
+  
+  def method_instance
+    lazy_var :@method_instance do
+      # Just drop a warning if we can't get the method object
+      logger.catch.warn(
+        "Failed to get method",
+        instance: instance,
+        method_name: method_name,
+      ) do
+        instance.method method_name
+      end
+    end
+  end
+  
+  
+  def method_owner
+    lazy_var :@method_owner do
+      method_instance && method_instance.owner
+    end
+  end
+  
+  
+  def method_owner_name
+    lazy_var :@method_owner_name do
+      if method_owner
+        method_owner.safe_name
+      else
+        '???'
+      end
+    end
+  end
+  
+  
+  def method_full_name
+    lazy_var :@method_full_name do
+      "#{ method_owner_name }##{ method_name.to_s }"
+    end
+  end
+  
+  
+  def context
+    {
+      instance: instance,
+      method_name: method_name,
+    }
+  end
+  
+  
+  def default_message
+    "Method ##{ method_name.to_s } is abstract"
+  end
+  
+  
+  def details
+    @details ||= if method_owner == instance.class
+      <<~END
+        Method #{ method_full_name } is abstract, meaning
+        #{ method_owner_name } is an abstract class and the invoking
+        instance #{ instance } should NOT have been constructed.
+      END
+    else
+      <<~END
+        Method #{ method_full_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.to_s }.
+        
+        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
+  end
+  
+end # class NRSER::AbstractMethodError

data/lib/nrser/errors/argument_error.rb

@@ -0,0 +1,42 @@
+# 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::ArgumentError < ::ArgumentError
+  
+  include NRSER::NicerError
+  
+  
+  # Instance Methods
+  # ========================================================================
+  
+  # def default_message
+  #   ["Expected", name, ""]
+  # end
+  
+end # class NRSER::ArgumentError