nrser 0.0.30 → 0.1.0

data/lib/nrser/functions/string/looks_like.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+##
+# Functional methods that try to tell what format a string that
+# is presumed to encode structural data is encoded in.
+##
+
+
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # @!group String Functions
+  
+  # Constants
+  # =====================================================================
+  
+  # Regexp used to guess if a string is a JSON-encoded array.
+  # 
+  # @return [Regexp]
+  # 
+  JSON_ARRAY_RE = /\A\s*\[.*\]\s*\z/m.freeze
+  
+  
+  # Functions
+  # ============================================================================
+  
+
+  # Test if a string looks like it might encode an array in JSON format by
+  # seeing if it's first non-whitespace character is `[` and last
+  # non-whitespace character is `]`.
+  # 
+  # @param [String] string
+  #   String to test.
+  # 
+  # @return [Boolean]
+  #   `true` if we think `string` encodes a JSON array.
+  # 
+  def self.looks_like_json_array? string
+    !!( string =~ JSON_ARRAY_RE )
+  end # #looks_like_json_array
+  
+end # module NRSER

data/lib/nrser/{text → functions/text}/indentation.rb

@@ -1,19 +1,5 @@
-# Requirements
-# =======================================================================
-
-# Stdlib
-# -----------------------------------------------------------------------
-
-# Deps
-# -----------------------------------------------------------------------
-
-# Project / Package
-# -----------------------------------------------------------------------
-require_relative './lines'
-
-
 module NRSER
-  # @!group Text
+  # @!group Text Functions
   
   
   # Constants
@@ -109,7 +95,7 @@ module NRSER
   # `marker` and `separator` can be configured via keyword arguments, but they
   #  default to:
   # 
-  # -   `marker` - {NRSER::INDENT_TAG_MARKER}, the no-printable ASCII 
+  # -   `marker` - {NRSER::INDENT_TAG_MARKER}, the no-printable ASCII
   #     *record separator* (ASCII character 30, "\x1E" / "\u001E").
   #     
   # -   `separator` - {NRSER::INDENT_TAG_SEPARATOR}, the non-printable ASCII

data/lib/nrser/{text → functions/text}/lines.rb

@@ -1,6 +1,5 @@
-
 module NRSER
-  # @!group Text
+  # @!group Text Functions
   
   # Classes
   # =====================================================================

data/lib/nrser/{text → functions/text}/word_wrap.rb

@@ -1,6 +1,5 @@
-
 module NRSER
-  # @!group Text
+  # @!group Text Functions
   
   # Split text at whitespace to fit in line length. Lifted from Rails'
   # ActionView.
@@ -24,6 +23,5 @@ module NRSER
       line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1#{break_sequence}").strip : line
     end * break_sequence
   end # .word_wrap
-  
-  
+    
 end # module NRSER

data/lib/nrser/{tree → functions/tree}/each_branch.rb

@@ -1,8 +1,7 @@
-# Definitions
-# =======================================================================
-
 module NRSER
   
+  # @!group Tree Functions
+  
   # Enumerate over the immediate "branches" of a structure that can be used
   # to compose our idea of a *tree*: nested hash-like and array-like structures
   # like you would get from parsing a JSON document.
@@ -35,7 +34,7 @@ module NRSER
   #   `#each_with_index` call.
   # 
   # @raise [NoMethodError]
-  #   If `tree` does not respond to `#each_pair` or to `#each_index` and 
+  #   If `tree` does not respond to `#each_pair` or to `#each_index` and
   #   `#each_with_index`.
   # 
   def self.each_branch tree, &block
@@ -44,13 +43,13 @@ module NRSER
       tree.each_pair &block
       
     elsif tree.respond_to? :each_index
-      # Array-like... we test for `each_index` because - unintuitively - 
+      # Array-like... we test for `each_index` because - unintuitively -
       # `#each_with_index` is a method of {Enumerable}, meaning that {Set}
       # responds to it, though sets are unordered and the values can't be
-      # accessed via those indexes. Hence we look for `#each_index`, which 
+      # accessed via those indexes. Hence we look for `#each_index`, which
       # {Set} does not respond to.
       
-      if block.nil?        
+      if block.nil?
         index_enumerator = tree.each_with_index
         
         Enumerator.new( index_enumerator.size ) { |yielder|

data/lib/nrser/functions/tree/leaves.rb

@@ -0,0 +1,92 @@
+module NRSER
+  
+  # @!group Tree Functions
+    
+  # Create a new hash where all the values are the scalar "leaves" of the
+  # possibly nested `hash` param. Leaves are keyed by "key path" arrays
+  # representing the sequence of keys to dig that leaf out of the has param.
+  # 
+  # In abstract, if `h` is the `hash` param and
+  # 
+  #     l = NRSER.leaves h
+  # 
+  # then for each key `k` and corresponding value `v` in `l`
+  # 
+  #     h.dig( *k ) == v
+  # 
+  # @pure
+  #   Return value depends only on parameters.
+  # 
+  # @example Simple "flat" hash
+  #   
+  #   NRSER.leaves( {a: 1, b: 2} )
+  #   => {
+  #     [:a] => 1,
+  #     [:b] => 2,
+  #   }
+  # 
+  # @example Nested hash
+  #   
+  #   NRSER.leaves(
+  #     1 => {
+  #       name: 'Neil',
+  #       fav_color: 'blue',
+  #     },
+  #     2 => {
+  #       name: 'Mica',
+  #       fav_color: 'red',
+  #     }
+  #   )
+  #   # => {
+  #   #   [1, :name]      => 'Neil',
+  #   #   [1, :fav_color] => 'blue',
+  #   #   [2, :name]      => 'Mica',
+  #   #   [2, :fav_color] => 'red',
+  #   # }
+  #   
+  # @param [#each_pair | (#each_index & #each_with_index)] tree
+  # 
+  # @return [Hash<Array, Object>]
+  # 
+  def self.leaves tree
+    {}.tap { |results|
+      _internal_leaves tree, path: [], results: results
+    }
+  end # .leaves
+  
+      
+  # Internal recursive implementation for {NRSER.leaves}.
+  # 
+  # @private
+  # 
+  # @pure
+  #   Return value depends only on parameters.
+  # 
+  # @param [#each_pair | (#each_index & #each_with_index)] tree
+  #   Tree to walk.
+  # 
+  # @param [Array] path
+  #   Key path down to `tree`.
+  # 
+  # @param [Hash<Array, Object>] results
+  #   New hash to stick results in.
+  # 
+  # @return [nil]
+  # 
+  def self._internal_leaves tree, path:, results:
+    NRSER.each_branch( tree ) { |key, value|
+      new_path = [*path, key]
+      
+      if NRSER::Types.tree.test value
+        _internal_leaves value, path: new_path, results: results
+      else
+        results[new_path] = value
+      end
+    }
+    
+    nil
+  end # ._internal_leaves
+  
+  private_class_method :_internal_leaves
+  
+end # module NRSER

data/lib/nrser/{tree → functions/tree}/map_branches.rb

@@ -1,18 +1,7 @@
-# Requirements
-# =======================================================================
-
-# Project / Package
-# -----------------------------------------------------------------------
-require 'nrser/types/trees'
-
-require_relative './each_branch'
-
-
-# Definitions
-# =======================================================================
-
 module NRSER
   
+  # @!group Tree Functions
+  
   # Map the immediate "branches" of a structure that can be used
   # to compose our idea of a *tree*: nested hash-like and array-like structures
   # like you would get from parsing a JSON document.
@@ -20,8 +9,8 @@ module NRSER
   # The `block` **MUST** return a pair ({Array} of length 2), the first value
   # of which is the key or index in the new {Hash} or {Array}.
   # 
-  # These pairs are then converted into a {Hash} or {Array} depending on it 
-  # `tree` was {NRSER::Types.hash_like} or {NRSER::Types.array_like}, and 
+  # These pairs are then converted into a {Hash} or {Array} depending on it
+  # `tree` was {NRSER::Types.hash_like} or {NRSER::Types.array_like}, and
   # that value is returned.
   # 
   # Uses {NRSER.each_branch} internally.
@@ -34,20 +23,20 @@ module NRSER
   # 2.  *array-like* that responds to `#each_index` and `#each_with_index`
   #     appropriately.
   # 
-  # @note Not sure what will happen if the tree has circular references!
+  # @pure
+  #   Return value depends only on parameters.
+  # 
+  # @note
+  #   Not sure what will happen if the tree has circular references!
   # 
   # @todo
   #   Might be nice to have an option to preserve the tree class that creates
-  #   a new instance of *whatever* it was and populates that, though I could 
+  #   a new instance of *whatever* it was and populates that, though I could
   #   see this relying on problematic assumptions and producing confusing
   #   results depending on the actual classes.
   #   
   #   Maybe this could be encoded in a mixin that we would detect or something.
   # 
-  # @example
-  #   
-  #   
-  # 
   # @param [#each_pair | (#each_index & #each_with_index)] tree
   #   Structure representing a tree via hash-like and array-like containers.
   # 
@@ -65,10 +54,13 @@ module NRSER
   # @return [Array | Hash]
   #   If no block is provided.
   # 
-  # @raise [NoMethodError]
-  #   If `tree` does not respond to `#each_pair` or to `#each_index` and 
+  # @raise [TypeError | NoMethodError]
+  #   If `tree` does not respond to `#each_pair` or to `#each_index` and
   #   `#each_with_index`.
   # 
+  # @raise [ArgumentError]
+  #   If `&block` is not provided.
+  # 
   def self.map_branches tree, &block
     if block.nil?
       raise ArgumentError, "Must provide block"
@@ -76,16 +68,23 @@ module NRSER
     
     pairs = each_branch( tree ).map &block
     
-    Types.match tree,
-      Types.hash_like, ->( _ ) {
-        pairs.to_h
-      },
-      
-      Types.array_like, ->( _ ) {
-        pairs.each_with_object( [] ) { |(index, value), array|
-          array[index] = value
-        }
+    if hash_like? tree
+      pairs.to_h
+    elsif array_like? tree
+      pairs.each_with_object( [] ) { |(index, value), array|
+        array[index] = value
       }
+    else
+      raise TypeError.new erb binding, <<-END
+        Excepted `tree` arg to be array or hash-like.
+        
+        Received (<%= tree.class %>):
+        
+            <%= tree.pretty_inspect %>
+        
+      END
+    end
+    
   end # .map_branches
   
 end # module NRSER

data/lib/nrser/functions/tree/map_leaves.rb

@@ -0,0 +1,56 @@
+module NRSER
+  
+  # @!group Tree Functions
+  
+  def self.map_leaves tree, &block
+    NRSER::Types.tree.check tree
+    
+    _internal_map_leaves tree, key_path: [], &block
+  end # #map_leaves
+  
+    
+  # Internal recursive implementation for {NRSER.leaves}.
+  # 
+  # @param [#each_pair | (#each_index & #each_with_index)] tree
+  #   Tree to walk.
+  # 
+  # @param [Array] path
+  #   Key path down to `tree`.
+  # 
+  # @param [Hash<Array, Object>] results
+  #   New hash to stick results in.
+  # 
+  # @return [nil]
+  # 
+  def self._internal_map_leaves tree, key_path:, &block
+    NRSER::Types.match tree,
+      NRSER::Types.hash_like, ->( hash_like ) {
+        hash_like.map { |key, value|
+          new_key_path = [*key_path, key]
+          
+          new_value = if NRSER::Types.tree.test( value )
+            _internal_map_leaves value, key_path: new_key_path, &block
+          else
+            block.call new_key_path, value
+          end
+          
+          [key, new_value]
+        }.to_h
+      },
+      
+      NRSER::Types.array_like, ->( array_like ) {
+        array_like.each_with_index.map { |value, index|
+          new_key_path = [*key_path, index]
+          
+          if NRSER::Types.tree.test( value )
+            _internal_map_leaves value, key_path: new_key_path, &block
+          else
+            block.call new_key_path, value
+          end
+        }
+      }
+  end # #_internal_leaves
+  
+  private_class_method :_internal_map_leaves
+  
+end # module NRSER

data/lib/nrser/{tree → functions/tree}/map_tree.rb

@@ -1,31 +1,20 @@
-# Requirements
-# =======================================================================
-
-# Project / Package
-# -----------------------------------------------------------------------
-require_relative './map_branches'
-
-
-# Definitions
-# =======================================================================
-
 module NRSER
   # Recursively descend through a tree mapping *all* non-structural elements
   # - anything not {NRSER::Types.hash_like} or {NRSER::Types.array_like}, both
-  # hash keys *and* values, as well as array entries - through `block` to 
+  # hash keys *and* values, as well as array entries - through `block` to
   # produce a new structure.
   # 
   # Useful when you want to translate pieces of a tree structure depending on
-  # their type or some other property that can be determined *from the element 
-  # alone* - `block` receives only the value as an argument, no location 
+  # their type or some other property that can be determined *from the element
+  # alone* - `block` receives only the value as an argument, no location
   # information (because it's weirder to represent for keys and I didn't need
   # it for the {NRSER.transformer} stuff this was written for).
   # 
   # @note
   #   Array indexes **are not mapped** through `block` and can not be changed
-  #   via this method. This makes it easier to do things like "convert all the 
-  #   integers to strings" when you mean the data entries, not the array 
-  #   indexes (which would fail since the new array wouldn't accept string 
+  #   via this method. This makes it easier to do things like "convert all the
+  #   integers to strings" when you mean the data entries, not the array
+  #   indexes (which would fail since the new array wouldn't accept string
   #   indices).
   #   
   #   If you don't want to map hash keys use {NRSER.map_leaves}.
@@ -40,7 +29,7 @@ module NRSER
   # 
   # @yieldparam [Object] element
   #   Anything reached from the root that is not structural (hash-like or
-  #   array-like), including / inside hash keys (though array 
+  #   array-like), including / inside hash keys (though array
   #   indexes are **not** passed).
   # 
   def self.map_tree tree, prune: false, &block
@@ -49,7 +38,7 @@ module NRSER
     mapped = tree.map { |element|
       # Recur if `element` is a tree.
       # 
-      # Since `element` will be an {Array} of `key`, `value` when `tree` is a 
+      # Since `element` will be an {Array} of `key`, `value` when `tree` is a
       # {Hash} (or similar), this will descend into hash keys that are also
       # trees, as well as into hash values and array entries.
       # 
@@ -61,7 +50,7 @@ module NRSER
       end
     }
     
-    # If `tree` is hash-like, we want to convert the array of pair arrays 
+    # If `tree` is hash-like, we want to convert the array of pair arrays
     # back into a hash.
     if Types.hash_like.test tree
       if prune