nrser 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3d16770ce888fe9a347449f09975b9ed97eb7ab5
-  data.tar.gz: ae0979f9123be24d08b8c45ac6d8c99cc4273603
+  metadata.gz: 866f9b21a10a8770d932228f5ad747e12782a4ba
+  data.tar.gz: bc50260a343986944cfe31e16d7d0e495360ab03
 SHA512:
-  metadata.gz: 9b5106ee53cbf739e2b0b549b5273a6a4057679d261abd0a710679a0e9b6cd95b66794f4afe6a883ccea56fc58afb76d56f38f0b3de385e9dc5da22caa3bc450
-  data.tar.gz: e58f6730e248c028c521295b53568485c277abb7ed6191c285b8a44515a0db97f1fe20054e85b4c6c9f2bc38511f5994dbd7cd715c0d2002c06b6e592b6603f0
+  metadata.gz: 0a77767059fb6d66420094f0e20f3fbad8e01e2cf37720df0ef0d20bd86f01193f85df842966a7f1e6fb8175b436f7abc0b5ee9cec6b802cec693ff02186cf0d
+  data.tar.gz: 93f5875dc928e78c86206b3552c5a3b7ac7b84b5af4dff1456498cc48a56b6d62d0582420e6a20cc64115f37c4968321bf1993dec1deb38ea8b5eec6901aa90f

data/lib/nrser/char/alpha_numeric_sub.rb

@@ -2,11 +2,10 @@
 # frozen_string_literal: true
 
 
-
 # Refinements
 # =======================================================================
 
-using NRSER
+require 'nrser/refinements/types'
 using NRSER::Types
 
 

data/lib/nrser/char.rb

@@ -2,12 +2,6 @@
 # frozen_string_literal: true
 
 
-# Refinements
-# =======================================================================
-
-using NRSER
-
-
 # Declarations
 # ============================================================================
 

data/lib/nrser/core_ext/array.rb

@@ -0,0 +1,120 @@
+class Array
+  include NRSER::Ext::Tree
+  
+  
+  # @return [Array]
+  #   new array consisting of all elements after the first (which may be
+  #   none, resulting in an empty array).
+  # 
+  def rest
+    NRSER.rest self
+  end # #rest
+  
+  
+  def extract! &block
+    NRSER.extract_from_array! self, &block
+  end
+  
+  
+  # Calls {NRSER.ellipsis} on `self`.
+  def ellipsis *args
+    NRSER.ellipsis self, *args
+  end
+  
+  
+  # `to_*` Converters
+  # =====================================================================
+  
+  # Checks that length is 2 and returns `self`.
+  # 
+  # @return [Array]
+  #   Array of length 2.
+  # 
+  # @raise [TypeError]
+  #   If length is not 2.
+  # 
+  def to_pair
+    unless length == 2
+      raise TypeError,
+            "Array is not of length 2: #{ self.inspect }"
+    end
+    
+    self
+  end # #to_pair
+  
+  
+  # To Operation Objects
+  # ---------------------------------------------------------------------
+  
+  # Creates a new {NRSER::Message} from the array.
+  # 
+  # @example
+  #   
+  #   message = [:fetch, :x].to_message
+  #   message.send_to x: 'ex', y: 'why?'
+  #   # => 'ex'
+  # 
+  # @return [NRSER::Message]
+  # 
+  def to_message
+    NRSER::Message.new *self
+  end # #to_message
+  
+  alias_method :to_m, :to_message
+  
+  
+  # Create a {Proc} that accepts a single `receiver` and provides this array's
+  # entries as the arguments to `#public_send` (or `#send` if the `publicly`
+  # option is `false`).
+  # 
+  # Equivalent to
+  # 
+  #   to_message.to_proc publicly: boolean
+  # 
+  # @example
+  #   
+  #   [:fetch, :x].sender.call x: 'ex'
+  #   # => 'ex'
+  # 
+  # @param [Boolean] publicly:
+  #   When `true`, uses `#public_send` in liu of `#send`.
+  # 
+  # @return [Proc]
+  # 
+  def to_sender publicly: true
+    to_message.to_proc publicly: publicly
+  end
+  
+  
+  # See {NRSER.chainer}.
+  #
+  def to_chainer publicly: true
+    NRSER.chainer self, publicly: publicly
+  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.
+  # 
+  # @example
+  #   list = [{id: 1, name: "Neil"}, {id: 2, name: "Mica"}]
+  #   list.assoc_by &[:id].to_digger
+  #   # =>  {
+  #   #       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.
+  # 
+  def to_digger
+    NRSER::Message.new( :dig, *self ).to_proc
+  end # #to_digger
+
+end # class Array

data/lib/nrser/core_ext/binding.rb

@@ -0,0 +1,44 @@
+require_relative './string'
+require_relative './enumerable'
+
+# Extension methods for {Binding}
+# 
+class Binding
+  
+  # Calls {NRSER.template} with `self` prepended to `*args`
+  # 
+  # @param (see NRSER.erb)
+  # @return (see NRSER.erb)
+  # 
+  def erb source
+    require 'erb'
+    
+    NRSER.filter_repeated_blank_lines(
+      NRSER.with_indent_tagged( NRSER.dedent( source ) ) { |tagged_str|
+        ERB.new( tagged_str ).result( self )
+      },
+      remove_leading: true
+    )
+  end
+  
+  alias_method :template, :erb
+  
+  
+  # Get a {Hash} of all local variable names (as {Symbol}) to values.
+  # 
+  # @return [Hash<Symbol, Object>]
+  # 
+  def locals
+    self.local_variables.assoc_to { |symbol| local_variable_get symbol }
+  end
+  
+  
+  # Get a {Array} of all local variable values.
+  # 
+  # @return [Array<Object>]
+  # 
+  def local_values
+    self.local_variables.map { |symbol| local_variable_get symbol }
+  end
+  
+end # class Binding

data/lib/nrser/{functions → core_ext}/enumerable/find_map.rb

@@ -1,25 +1,20 @@
-module NRSER
-  
-  # @!group Enumerable Functions
+module Enumerable
   
   # Find the first truthy (not `nil` or `false`) result of calling `&block`
-  # with entries from `enum`.
+  # on entries.
   # 
-  # Like {Enumerable#find}, accept an optional `ifnone` procedure to call if
+  # Like {Enumerable#find}, accepts an optional `ifnone` procedure to call if
   # no match is found.
   # 
   # @example
   #   
-  #   NRSER.find_map( [1, 2, 3, 4] ) do |i|
+  #   [1, 2, 3, 4].find_map do |i|
   #     if i.even?
   #       "#{ i } is even!"
   #     end
   #   end
   #   # => "2 is even!"
   # 
-  # @param [Enumerable<E>] enum
-  #   Entries to search (in order).
-  # 
   # @param [nil | Proc<()=>DEFAULT>] ifnone
   #   Optional lambda to call for the return value when no match is found.
   # 
@@ -27,19 +22,27 @@ module NRSER
   #   Block mapping entires to results.
   # 
   # @return [nil]
-  #   When `block.call( E )` is `nil` or `false` for all `E` in `enum`
+  #   When `block.call( E )` is `nil` or `false` for all entries `E`
   #   *and* `ifnone` is `nil` or not provided.
   # 
   # @return [V]
-  #   When `block.call( E )` is `nil` or `false` for all `E` in `enum`
+  #   When `block.call( E )` is `nil` or `false` for all entries `E`
   #   *and* `ifnone` is a lambda that returns `DEFAULT`.
   # 
-  # @return [R]
+  # @return [RESULT]
   #   The first result `RESLUT = block.call( E )`
   #   where `RESLUT` is not `nil` or `false`.
   # 
-  def self.find_map enum, ifnone = nil, &block
-    enum.each do |entry|
+  # @return [DEFAULT]
+  #   When `ifnone` procedure is provided and `&block` returns `nil` or
+  #   `false` for all entries.
+  # 
+  # @return [nil]
+  #   When `ifnone` procedure is *not* provided and `&block` returns `nil` or
+  #   `false` for all entries.
+  # 
+  def find_map ifnone = nil, &block
+    each do |entry|
       if result = block.call( entry )
         # Found a match, short-circuit
         return result
@@ -48,6 +51,6 @@ module NRSER
     
     # No matches, return `ifnone`
     ifnone.call if ifnone
-  end # .find_map
+  end # #find_map
   
 end # module NRSER

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

@@ -1,15 +1,9 @@
-# Instance methods to extend {Enumerable} objects.
+require_relative './enumerable/find_map'
+
+
+# Instance methods to extend {Enumerable}.
 # 
-# Refined into many of them, including {Array}, {Set}, {Hash} and {OpenStruct},
-# and may be independently used as well.
-# 
-module NRSER::Ext::Enumerable
-  
-  # See {NRSER.map_values}
-  def map_values &block
-    NRSER.map_values self, &block
-  end
-  
+module Enumerable
   
   # See {NRSER.find_bounded}
   def find_bounded bounds, &block
@@ -24,17 +18,14 @@ module NRSER::Ext::Enumerable
   
   
   # See {NRSER.assoc_by}
-  def assoc_by &block
-    NRSER.assoc_by self, &block
+  def assoc_by *args, &block
+    NRSER.assoc_by self, *args, &block
   end
   
-  # Old name
-  alias_method :to_h_by, :assoc_by
-  
   
   # See {NRSER.assoc_to}
-  def assoc_to &block
-    NRSER.assoc_to  self, &block
+  def assoc_to *args, &block
+    NRSER.assoc_to self, *args, &block
   end
   
   
@@ -68,15 +59,10 @@ module NRSER::Ext::Enumerable
   end
   
   
-  # See {NRSER.find_map}
-  def find_map *args, &block
-    NRSER.find_map self, *args, &block
-  end
-  
   # See {NRSER.slice?}
   def slice? *args, &block
     NRSER.slice? self, *args, &block
   end
   
   
-end # module NRSER::Ext::Enumerable
+end # module Enumerable

data/lib/nrser/core_ext/exception.rb

@@ -0,0 +1,30 @@
+class Exception
+  def format
+    NRSER.format_exception self
+  end
+
+  # Create a new instance from the squished message.
+  # 
+  # See {NRSER.squish}.
+  # 
+  # @param [String] message
+  # 
+  # @return [Exception]
+  # 
+  def self.squished message
+    new NRSER.squish( message )
+  end
+  
+  # Create a new instance from the dedented message.
+  # 
+  # See {NRSER.dedent}.
+  # 
+  # @param [String] message
+  # 
+  # @return [Exception]
+  # 
+  def self.dedented message
+    new NRSER.dedent( message )
+  end
+  
+end # NRSER

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

@@ -0,0 +1,49 @@
+class Hash  
+  # Like {#extract!} combined with {Hash#values_at} - extracts `keys` and
+  # appends (via `#<<`) the values to `into` (in order of `keys`).
+  # 
+  # `into` default to an empty Array.
+  # 
+  # @example Basic Usage
+  #   hash = { a: 1, b: 2, c: 3, d: 4 }
+  #   
+  #   hash.extract_values_at! :a, :b
+  #   # => [1, 2]
+  #   
+  #   hash
+  #   # => {c: 3, d: 4}
+  #   
+  #   hash = { a: 1, b: 2, c: 3, d: 4 }
+  #   
+  #   hash.extract_values_at! :b, :a
+  #   # => [2, 1]
+  # 
+  #   hash
+  #   # => {c: 3, d: 4}
+  #   
+  # @example Custom `into
+  #   hash = { a: 1, b: 2, c: 3, d: 4 }
+  #   into = Set[1, 3, 5]
+  # 
+  #   hash.extract_values_at! :a, :b, into: into
+  #   # => #<Set: {1, 3, 5, 2}>
+  #   
+  #   hash
+  #   # => {:c=>3, :d=>4}
+  #   
+  # @param *keys
+  #   Hash keys to extract.
+  # 
+  # @param [#<<] into:
+  #   Object to extract values at `keys` into.
+  # 
+  # @return [into]
+  #   The `into` object with the extracted values (if any are found).
+  # 
+  def extract_values_at! *keys, into: []
+    keys.each_with_object( into ) { |key, result|
+      result << delete(key) if has_key?( key )
+    }
+  end
+  
+end

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

@@ -0,0 +1,24 @@
+class Hash
+  # Just like {Hash#transform_values} but yields `key, value`.
+  # 
+  def transform_values_with_keys &block
+    return enum_for( __method__ ) { size } unless block_given?
+    return {} if empty?
+    result = self.class.new
+    each do |key, value|
+      result[key] = block.call key, value
+    end
+    result
+  end
+  
+  
+  # Just like {#transform_values_with_keys} but mutates `self`.
+  # 
+  def transform_values_with_keys! &block
+    return enum_for( __method__ ) { size } unless block_given?
+    each do |key, value|
+      self[key] = block.call key, value
+    end
+  end
+  
+end

data/lib/nrser/core_ext/hash.rb

@@ -0,0 +1,50 @@
+require 'active_support/core_ext/hash'
+
+require 'nrser/ext/tree'
+
+require_relative './hash/extract_values_at'
+require_relative './hash/transform_values_with_keys'
+
+class Hash
+  include NRSER::Ext::Tree
+  
+  # Short names
+  alias_method :sym_keys!,  :symbolize_keys!
+  alias_method :sym_keys,   :symbolize_keys
+  
+  alias_method :str_keys!,  :stringify_keys!
+  alias_method :str_keys,   :stringify_keys
+  
+  
+  # See {NRSER.bury!}
+  def bury! key_path,
+            value,
+            parsed_key_type: :guess,
+            clobber: false
+    NRSER.bury! self,
+                key_path,
+                value,
+                parsed_key_type: parsed_key_type,
+                clobber: clobber
+  end
+  
+  
+  # Checks that `self` contains a single key/value pair (`#length` of 1)
+  # and returns it as an array of length 2.
+  # 
+  # @return [Array]
+  #   Array of length 2.
+  # 
+  # @raise [TypeError]
+  #   If `self` has more than one key/value pair.
+  # 
+  def to_pair
+    unless length == 1
+      raise TypeError,
+            "Hash has more than one pair: #{ self.inspect }"
+    end
+    
+    first
+  end
+  
+end

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

@@ -0,0 +1,96 @@
+# Extension methods for {Module}
+# 
+class Module
+  
+  # @!group {Method} Object Readers
+  # ==========================================================================
+
+  # Get class methods for this {Module} ({Class} are also {Module}, so works
+  # same for those).
+  # 
+  # @param include_super  (see NRSER.method_objects_for)
+  # @param sort:          (see NRSER.method_objects_for)
+  # 
+  # @return [Array<Method>]
+  #   List of method objects (all bound to `self`).
+  # 
+  def class_method_objects include_super = true, sort: true
+    NRSER.method_objects_for  self,
+                              include_super,
+                              type: :class,
+                              sort: sort
+  end
+  
+  alias_method :class_Methods, :class_method_objects
+  
+  
+  # Just get the class methods defined in this module (or class) itself,
+  # omitting inherited ones.
+  # 
+  # Equivalent to
+  # 
+  #     #class_method_objects false
+  # 
+  # @param sort:  (see .class_method_objects)
+  # @return       (see .class_method_objects)
+  # 
+  def own_class_method_objects sort: true
+    class_method_objects false, sort: sort
+  end
+  
+  alias_method :own_class_Methods, :own_class_method_objects
+  
+  
+  # Get instance methods for this {Module} (or {Class}).
+  # 
+  # @param include_super  (see NRSER.method_objects_for)
+  # @param sort:          (see NRSER.method_objects_for)
+  # 
+  # @param [Boolean] include_initialize:
+  #   When `true`, include `#initialize` method if it's defined, which is
+  #   normally excluded from {Module#instance_methods}.
+  #   
+  #   Respects  `include_super` - won't include it if we are only looking for
+  #   own instance methods and it's inherited.
+  # 
+  # @return [Array<UnboundMethod>]
+  #   List of method objects (all unbound).
+  # 
+  def instance_method_objects include_super = true,
+                              sort: true,
+                              include_initialize: false
+    NRSER.method_objects_for \
+      self,
+      include_super,
+      type: :instance,
+      sort: sort,
+      include_initialize: include_initialize
+  end # #instance_method_objects
+  
+  alias_method :instance_Methods, :instance_method_objects
+  
+  
+  # Just get the instance methods defined in this {Module} (or {Class}) itself,
+  # omitting inherited ones.
+  # 
+  # Equivalent to
+  # 
+  #     #instance_method_objects false
+  # 
+  # @param sort:                (see #instance_method_objects)
+  # @param include_initialize:  (see #instance_method_objects)
+  # 
+  # @return                     (see #instance_method_objects)
+  # 
+  def own_instance_method_objects sort: true,
+                                  include_initialize: false
+    instance_method_objects false,
+                            sort: sort,
+                            include_initialize: include_initialize
+  end
+  
+  alias_method :own_instance_Methods, :own_instance_method_objects
+  
+  # @!endgroup {Method} Object Readers
+  
+end # class Module

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

@@ -0,0 +1,69 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Need {String#demodulize}
+require 'active_support/core_ext/string/inflections'
+
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Definitions
+# =======================================================================
+
+class Module
+  
+  # Like {Module#name} but also returns a {String} for anonymous classes.
+  # 
+  # So you don't need to do any testing or trying when you want to work
+  # with the name of a module (or class, which are modules).
+  # 
+  # @return [String]
+  # 
+  def safe_name
+    name = self.name
+    return name if name.is_a? String
+    
+    # Slice out whatever that hex thingy that anon modules dump in their
+    # `#to_s`... `"#<Class:0x00007fa6958c1700>" => "0x00007fa6958c1700"`
+    # 
+    # Might as well use that as an identifier so it matches their `#to_s`,
+    # and this should still succeed in whatever funky way even if `#to_s`
+    # returns something totally unexpected.
+    # 
+    to_s_hex = self.to_s.split( ':' ).last[0...-1]
+    
+    type_name = if self.is_a?( Class ) then "Class" else "Module" end
+    
+    "Anon#{ type_name }_#{ to_s_hex }"
+  end # #safe_name
+  
+  
+  # Get the {#safe_name} and run ActiveSupport's {String#demodulize} on it
+  # to get the module (or class) name without the namespace.
+  # 
+  # @example
+  #   NRSER::Types.demod_name
+  #   # => 'Types'
+  # 
+  # @return [String]
+  # 
+  def demodulize_name
+    safe_name.demodulize
+  end # #demodulize_name
+  
+  # Because I always screw up spelling 'demodulize'
+  alias_method :demod_name, :demodulize_name
+  
+  
+end