nrser 0.0.26 → 0.0.27

data/lib/nrser/text/lines.rb

@@ -0,0 +1,52 @@
+
+module NRSER
+  # @!group Text
+  
+  # Classes
+  # =====================================================================
+  
+  # @todo document Lines class.
+  class Lines < Array
+    
+    # Constants
+    # ======================================================================
+    
+    
+    # Class Methods
+    # ======================================================================
+    
+    
+    # Attributes
+    # ======================================================================
+    
+    
+    # Constructor
+    # ======================================================================
+    
+    # Instantiate a new `Lines`.
+    def initialize
+      
+    end # #initialize
+    
+    
+    # Instance Methods
+    # ======================================================================
+    
+  end # class Lines
+  
+  
+  # Functions
+  # =====================================================================
+  
+  def self.lines text
+    case text
+    when String
+      text.lines
+    when Array
+      text
+    else
+      raise TypeError, "Expected String or Array, found #{ text.class.name }"
+    end
+  end
+  
+end # module NRSER

data/lib/nrser/text/word_wrap.rb

@@ -0,0 +1,29 @@
+
+module NRSER
+  # @!group Text
+  
+  # Split text at whitespace to fit in line length. Lifted from Rails'
+  # ActionView.
+  # 
+  # @see http://api.rubyonrails.org/classes/ActionView/Helpers/TextHelper.html#method-i-word_wrap
+  # 
+  # @param [String] text
+  #   Text to word wrap.
+  # 
+  # @param [Fixnum] line_width:
+  #   Line with in number of character to wrap at.
+  # 
+  # @param [String] break_sequence:
+  #   String to join lines with.
+  # 
+  # @return [String]
+  #   @todo Document return value.
+  # 
+  def self.word_wrap text, line_width: 80, break_sequence: "\n"
+    text.split("\n").collect! do |line|
+      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.rb

@@ -3,84 +3,10 @@
 
 # Project / Package
 # -----------------------------------------------------------------------
+
+require_relative './tree/each_branch'
+require_relative './tree/map_branches'
+require_relative './tree/map_tree'
 require_relative './tree/leaves'
 require_relative './tree/map_leaves'
 require_relative './tree/transform'
-
-
-# Definitions
-# =======================================================================
-
-module NRSER
-  
-  # 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.
-  # 
-  # Written and tested against Hash and Array instances, but should work with
-  # anything hash-like that responds to `#each_pair` appropriately or
-  # array-like that responds to `#each_index` and `#each_with_index`.
-  # 
-  # @note Not sure what will happen if the tree has circular references!
-  # 
-  # @param [#each_pair | (#each_index & #each_with_index)] tree
-  #   Structure representing a tree via hash-like and array-like containers.
-  # 
-  # @yieldparam [Object] key
-  #   The first yielded param is the key or index for the value branch at the
-  #   top level of `tree`.
-  #   
-  # @yieldparam [Object] value
-  #   The second yielded param is the branch at the key or index at the top
-  #   level of `tree`.
-  # 
-  # @yieldreturn
-  #   Ignored.
-  # 
-  # @return [Enumerator]
-  #   If no block is provided.
-  # 
-  # @return [#each_pair | (#each_index & #each_with_index)]
-  #   If a block is provided, the result of the `#each_pair` or
-  #   `#each_with_index` call.
-  # 
-  # @raise [NoMethodError]
-  #   If `tree` does not respond to `#each_pair` or to `#each_index` and 
-  #   `#each_with_index`.
-  # 
-  def self.each_branch tree, &block
-    if tree.respond_to? :each_pair
-      # Hash-like
-      tree.each_pair &block
-      
-    elsif tree.respond_to? :each_index
-      # 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 
-      # {Set} does not respond to.
-      
-      if block.nil?        
-        index_enumerator = tree.each_with_index
-        
-        Enumerator.new( index_enumerator.size ) { |yielder|
-          index_enumerator.each { |value, index|
-            yielder.yield index, value
-          }
-        }
-      else
-        tree.each_with_index.map { |value, index|
-          block.call index, value
-        }
-      end
-      
-    else
-      raise NoMethodError.new NRSER.squish <<-END
-        `tree` param must respond to `#each_pair` or `#each_index`,
-        found #{ tree.inspect }
-      END
-      
-    end # if / else
-  end # .each_branch
-  
-end # module NRSER

data/lib/nrser/tree/each_branch.rb

@@ -0,0 +1,76 @@
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # 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.
+  # 
+  # Written and tested against Hash and Array instances, but should work with
+  # anything hash-like that responds to `#each_pair` appropriately or
+  # array-like that responds to `#each_index` and `#each_with_index`.
+  # 
+  # @note Not sure what will happen if the tree has circular references!
+  # 
+  # @param [#each_pair | (#each_index & #each_with_index)] tree
+  #   Structure representing a tree via hash-like and array-like containers.
+  # 
+  # @yieldparam [Object] key
+  #   The first yielded param is the key or index for the value branch at the
+  #   top level of `tree`.
+  #   
+  # @yieldparam [Object] value
+  #   The second yielded param is the branch at the key or index at the top
+  #   level of `tree`.
+  # 
+  # @yieldreturn
+  #   Ignored.
+  # 
+  # @return [Enumerator]
+  #   If no block is provided.
+  # 
+  # @return [#each_pair | (#each_index & #each_with_index)]
+  #   If a block is provided, the result of the `#each_pair` or
+  #   `#each_with_index` call.
+  # 
+  # @raise [NoMethodError]
+  #   If `tree` does not respond to `#each_pair` or to `#each_index` and 
+  #   `#each_with_index`.
+  # 
+  def self.each_branch tree, &block
+    if tree.respond_to? :each_pair
+      # Hash-like
+      tree.each_pair &block
+      
+    elsif tree.respond_to? :each_index
+      # 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 
+      # {Set} does not respond to.
+      
+      if block.nil?        
+        index_enumerator = tree.each_with_index
+        
+        Enumerator.new( index_enumerator.size ) { |yielder|
+          index_enumerator.each { |value, index|
+            yielder.yield [index, value]
+          }
+        }
+      else
+        tree.each_with_index.map { |value, index|
+          block.call [index, value]
+        }
+      end
+      
+    else
+      raise NoMethodError.new NRSER.squish <<-END
+        `tree` param must respond to `#each_pair` or `#each_index`,
+        found #{ tree.inspect }
+      END
+      
+    end # if / else
+  end # .each_branch
+  
+end # module NRSER

data/lib/nrser/tree/map_branches.rb

@@ -0,0 +1,91 @@
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+require 'nrser/types/trees'
+
+require_relative './each_branch'
+
+
+# Definitions
+# =======================================================================
+
+module NRSER
+  
+  # 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.
+  # 
+  # 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 
+  # that value is returned.
+  # 
+  # Uses {NRSER.each_branch} internally.
+  # 
+  # Written and tested against Hash and Array instances, but should work with
+  # anything:
+  # 
+  # 1.  *hash-like* that responds to `#each_pair` appropriately.
+  # 
+  # 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!
+  # 
+  # @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 
+  #   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.
+  # 
+  # @yieldparam [Object] key
+  #   The first yielded param is the key or index for the value branch at the
+  #   top level of `tree`.
+  #   
+  # @yieldparam [Object] value
+  #   The second yielded param is the branch at the key or index at the top
+  #   level of `tree`.
+  # 
+  # @yieldreturn [Array]
+  #   Pair of key (/index) in new array or hash followed by value.
+  # 
+  # @return [Array | Hash]
+  #   If no block is provided.
+  # 
+  # @raise [NoMethodError]
+  #   If `tree` does not respond to `#each_pair` or to `#each_index` and 
+  #   `#each_with_index`.
+  # 
+  def self.map_branches tree, &block
+    if block.nil?
+      raise ArgumentError, "Must provide block"
+    end
+    
+    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
+        }
+      }
+  end # .map_branches
+  
+end # module NRSER

data/lib/nrser/tree/map_tree.rb

@@ -0,0 +1,97 @@
+# 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 
+  # 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 
+  # 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 
+  #   indices).
+  #   
+  #   If you don't want to map hash keys use {NRSER.map_leaves}.
+  # 
+  # See the specs for examples. Used in {NRSER.transformer}.
+  # 
+  # @param tree (see NRSER.each_branch)
+  # 
+  # @param [Boolean] prune:
+  #   When `true`, prunes out values whose labels end with `?` and values are
+  #   `nil`.
+  # 
+  # @yieldparam [Object] element
+  #   Anything reached from the root that is not structural (hash-like or
+  #   array-like), including / inside hash keys (though array 
+  #   indexes are **not** passed).
+  # 
+  def self.map_tree tree, prune: false, &block
+    # TODO type check tree?
+    
+    mapped = tree.map { |element|
+      # Recur if `element` is a tree.
+      # 
+      # 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.
+      # 
+      if Types.tree.test element
+        map_tree element, prune: prune, &block
+      else
+        # When we've run out of trees, finally pipe through the block:
+        block.call element
+      end
+    }
+    
+    # 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
+        pruned = {}
+        
+        mapped.each { |key, value|
+          if  Types.label.test( key ) &&
+              key.to_s.end_with?( '?' )
+            unless value.nil?
+              new_key = key.to_s[0..-2]
+              
+              if key.is_a?( Symbol )
+                new_key = new_key.to_sym
+              end
+              
+              pruned[new_key] = value
+            end
+          else
+            pruned[key] = value
+          end
+        }
+        
+        pruned
+      else
+        mapped.to_h
+      end
+    else
+      # Getting here means it was array-like, so it's already fine
+      mapped
+    end
+  end # .map_branches
+  
+end # module NRSER

data/lib/nrser/tree/transform.rb

@@ -1,3 +1,10 @@
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative './map_tree'
+
 # Definitions
 # =======================================================================
 
@@ -12,19 +19,55 @@ module NRSER
   #   @todo Document return value.
   # 
   def self.transform tree, source
-    each_branch( tree ).map { |pair|
-      pair.map { |value|
-        if NRSER::Types.tree.test value
-          transform value, source
-        else
-          if value.is_a? Proc
-            value.call source
-          else
-            value
-          end
-        end
-      }
-    }.to_h
+    map_tree( tree, prune: true ) { |value|
+      if value.is_a? Proc
+        value.call source
+      else
+        value
+      end
+    }
   end # .transform
   
+  
+  class SendSerializer
+    def initialize messages = []
+      @messages = messages
+    end
+    
+    def method_missing symbol, *args, &block
+      messages = [
+        *@messages,
+        ::NRSER::Message.new( symbol, *args, &block )
+      ]
+      
+      self.class.new messages
+    end
+    
+    def to_proc publicly: true
+      ::NRSER.chainer @messages, publicly: publicly
+    end
+  end
+  
+  
+  
+  # @todo Document transformer method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.transformer &block
+    map_tree( block.call SendSerializer.new ) { |value|
+      if value.is_a? SendSerializer
+        value.to_proc
+      else
+        value
+      end
+    }
+  end # .transformer
+  
+  
+  
 end # module NRSER