nrser 0.0.25 → 0.0.26

data/lib/nrser/refinements.rb

@@ -1,5 +1,3 @@
-require 'nrser'
-
 require_relative './refinements/object'
 require_relative './refinements/string'
 require_relative './refinements/array'
@@ -10,3 +8,4 @@ require_relative './refinements/binding'
 require_relative './refinements/set'
 require_relative './refinements/open_struct'
 require_relative './refinements/enumerator'
+require_relative './refinements/symbol'

data/lib/nrser/refinements/array.rb

@@ -1,8 +1,19 @@
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
 require_relative './enumerable'
+require_relative './tree'
+
+
+# Definitions
+# =======================================================================
 
 module NRSER
   refine ::Array do
     include NRSER::Refinements::Enumerable
+    include NRSER::Refinements::Tree
     
     
     # @return [Array]
@@ -14,6 +25,83 @@ module NRSER
     end # #rest
     
     
+    # `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
+    
+    alias_method :sender, :to_sender
+    alias_method :sndr, :to_sender
+    
+    
+    # See {NRSER.chainer}.
+    #
+    def to_chainer publicly: true
+      NRSER.chainer self, publicly: publicly
+    end # #to_chainer
+    
+    alias_method :chainer, :to_chainer
+    alias_method :chnr, :to_chainer
+    
+    
     # Returns a lambda that calls accepts a single arg and calls `#dig` on it
     # with the elements of *this* array as arguments.
     # 
@@ -34,11 +122,12 @@ module NRSER
     #   Lambda proc that accepts a single argument and calls `#dig` with this 
     #   array's contents as the `#dig` arguments.
     # 
-    def digger
-      ->(digable) {
-        digable.dig *self
-      }
-    end # #digable
+    def to_digger
+      NRSER::Message.new( :dig, *self ).to_proc
+    end # #to_digger
+    
+    alias_method :digger, :to_digger
+    alias_method :dggr, :to_digger
     
     
   end # refine ::Array

data/lib/nrser/refinements/enumerable.rb

@@ -37,5 +37,10 @@ module NRSER::Refinements::Enumerable
     NRSER.enumerate_as_values self
   end
   
+  # See {NRSER.only!}
+  def only!
+    NRSER.only! self
+  end
+  
 end # module NRSER::Refinements::Enumerable
 

data/lib/nrser/refinements/hash.rb

@@ -1,9 +1,21 @@
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
 require_relative './enumerable'
+require_relative './tree'
+
+
+# Definitions
+# =======================================================================
 
 module NRSER
   
   refine ::Hash do
     include NRSER::Refinements::Enumerable
+    include NRSER::Refinements::Tree
+    
     
     # See {NRSER.except_keys!}.
     def except! *keys
@@ -27,12 +39,6 @@ module NRSER
     end
     
     
-    # See {NRSER.leaves}.
-    def leaves
-      NRSER.leaves self
-    end # #leaves
-    
-    
     # See {NRSER.transform_keys!}
     def transform_keys! &block
       return enum_for(:transform_keys!) { size } unless block_given?
@@ -89,5 +95,36 @@ module NRSER
                   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
+    
+    
+    # See {NRSER.deep_merge}
+    def deep_merge other_hash, &block
+      NRSER.deep_merge self, other_hash, &block
+    end
+    
+    
+    # See {NRSER.deep_merge!}
+    def deep_merge! other_hash, &block
+      NRSER.deep_merge! self, other_hash, &block
+    end
+    
   end # refine ::Hash
 end # NRSER

data/lib/nrser/refinements/object.rb

@@ -1,24 +1,44 @@
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+require 'nrser/object'
+
+
+# Definitions
+# =======================================================================
+
 module NRSER
   refine Object do
+    # Yield `self`. Analogous to {#tap} but returns the result of the invoked
+    # block.
     def pipe
       yield self
     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
     
-    # Calls {NRSER.as_array} in `self`.
+    # Call {NRSER.as_array} on `self`.
     def as_array
       NRSER.as_array self
     end

data/lib/nrser/refinements/symbol.rb

@@ -0,0 +1,12 @@
+module NRSER
+  refine ::Symbol do
+    
+    def to_retriever
+      NRSER.retriever self
+    end
+    
+    alias_method :retriever, :to_retriever
+    alias_method :rtvr, :to_retriever
+    
+  end # refine ::Symbol
+end # NRSER

data/lib/nrser/refinements/tree.rb

@@ -0,0 +1,41 @@
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Declarations
+# =======================================================================
+
+module NRSER; end
+module NRSER::Refinements; end
+
+
+# Definitions
+# =======================================================================
+
+# Instance methods that are refined in to the Ruby built-ins that we consider
+# trees: {Array}, {Hash} and {OpenStruct}.
+# 
+module NRSER::Refinements::Tree
+  
+  # Sends `self` to {NRSER.leaves}.
+  def leaves
+    NRSER.leaves self
+  end # #leaves
+  
+  
+  # Sends `self` and the optional `block` to {NRSER.each_branch}.
+  def each_branch &block
+    NRSER.each_branch self, &block
+  end
+  
+end # module NRSER::Refinements::Tree
+

data/lib/nrser/rspex.rb

@@ -0,0 +1,329 @@
+# encoding: utf-8
+
+##############################################################################
+# RSpec helpers, shared examples, extensions, and other goodies.
+# 
+# This file is *not* required by default when `nrser` is since it **defines
+# global methods** and is not needed unless you're in [Rspec][].
+# 
+# [Rspec]: http://rspec.info/
+# 
+##############################################################################
+
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+require_relative './message'
+
+
+# Helpers
+# =====================================================================
+
+# Merge "expectation" hashes by appending all clauses for each state.
+# 
+# @example
+#   
+# 
+# @param [Array<Hash>] *expectations
+#   Splat of "expectation" hashes - see the examples.
+# 
+def merge_expectations *expectations
+  Hash.new { |result, state|
+    result[state] = []
+  }.tap { |result| 
+    expectations.each { |ex|
+      ex.each { |state, clauses|
+        result[state] += clauses.to_a
+      }
+    }
+  }
+end
+
+class Wrapper
+  def initialize description: nil, &block
+    @description = description
+    @block = block
+  end
+  
+  def unwrap context: nil
+    if context
+      context.instance_exec &@block
+    else
+      @block.call
+    end
+  end
+  
+  def to_s
+    if @description
+      @description.to_s
+    else
+      "#<Wrapper ?>"
+    end
+  end
+end
+
+def wrap description = nil, &block
+  Wrapper.new description: description, &block
+end
+
+def unwrap obj, context: nil
+  if obj.is_a? Wrapper
+    obj.unwrap context: context
+  else
+    obj
+  end
+end
+
+# Extensions
+# =====================================================================
+
+module NRSER; end
+
+module NRSER::RSpex
+  PREFIXES = {
+    # module: "𝓜 𝓸𝓭𝓾𝓵𝓮",
+    module: "𝞛",
+    section: '§',
+    method: '𝞴',
+  }
+  
+  # Instance methods to extend example groups with.
+  # 
+  module ExampleGroup
+    
+    # Create a new {RSpec.describe} section where the subject is set by
+    # calling the parent subject with `args` and evaluate `block` in it.
+    # 
+    # @example
+    #   describe "hi sayer" do
+    #     subject{ ->( name ) { "Hi #{ name }!" } }
+    #     
+    #     describe_called_with 'Mom' do
+    #       it { is_expected.to eq 'Hi Mom!' }
+    #     end
+    #   end
+    # 
+    # @param [Array] *args
+    #   Arguments to call `subject` with to produce the new subject.
+    # 
+    # @param [#call] &block
+    #   Block to execute in the context of the example group after refining
+    #   the subject.
+    # 
+    def describe_called_with *args, &block
+      describe "called with #{ args.map( &:inspect ).join( ', ' ) }" do
+        subject { super().call *args }
+        instance_exec &block
+      end
+    end # #describe_called_with
+    
+    # Aliases to other names I was using at first... not preferring their use
+    # at the moment.
+    # 
+    # The `when_` one sucks because Atom de-dents the line, and `describe_` 
+    # is just clearer what the block is doing for people reading it.
+    alias_method :called_with, :describe_called_with
+    alias_method :when_called_with, :describe_called_with
+    
+    
+    def describe_message symbol, *args, &body
+      description = \
+        "message #{ [symbol, *args].map( &:inspect ).join( ', ' ) }"
+      
+      describe description, type: :message do
+        subject { NRSER::Message.new symbol, *args }
+        instance_exec &body
+      end
+    end
+    
+    
+    # For use when `subject` is a {NRSER::Message}. Create a new context for
+    # the `receiver` where the subject is the result of sending that message
+    # to the receiver.
+    # 
+    # @param [Object] receiver
+    #   Object that will receive the message to create the new subject.
+    # 
+    # @param [Boolean] publicly:
+    #   Send message publicly via {Object#public_send} (default) or privately  
+    #   via {Object.send}.
+    # 
+    # @return
+    #   Whatever the `context` call returns.
+    # 
+    def describe_sent_to receiver, publicly: true, &block
+      mode = if publicly
+        "publicly"
+      else
+        "privately"
+      end
+      
+      describe "sent to #{ receiver } (#{ mode })" do
+        subject { super().send_to unwrap( receiver, context: self ) }
+        instance_exec &block
+      end
+    end # #describe_sent_to
+    
+    # Aliases to other names I was using at first... not preferring their use
+    # at the moment.
+    # 
+    # The `when_` one sucks because Atom de-dents the line, and `describe_` 
+    # is just clearer what the block is doing for people reading it.
+    alias_method :sent_to, :describe_sent_to
+    alias_method :when_sent_to, :describe_sent_to
+    
+    
+    # Describe a "section". Just like {RSpec.describe} except it:
+    # 
+    # 1.  Expects a string title.
+    #     
+    # 2.  Prepends a little section squiggle `§` to the title so sections are 
+    #     easier to pick out visually.
+    #     
+    # 3.  Adds `type: :section` metadata.
+    # 
+    # @param [String] title
+    #   String title for the section.
+    # 
+    # @param [Hash<Symbol, Object>] **metadata
+    #   Additional [RSpec metadata][] for the example group.
+    #   
+    #   [RSpec metadata]: https://relishapp.com/rspec/rspec-core/docs/metadata/user-defined-metadata
+    # 
+    # @return
+    #   Whatever {RSpec.describe} returns.
+    # 
+    def describe_section title, **metadata, &block
+      describe(
+        "#{ NRSER::RSpex::PREFIXES[:section] } #{ title }",
+        type: :section,
+        **metadata
+      ) do
+        instance_exec &block
+      end
+    end # #describe_section
+    
+    # Old name
+    alias_method :describe_topic, :describe_section
+    
+    
+    def describe_module mod, **metadata, &block
+      describe(
+        "#{ NRSER::RSpex::PREFIXES[:module] } #{ mod.name }",
+        type: :module,
+        **metadata
+      ) do
+        instance_exec &block
+      end
+    end # #describe_module
+    
+    
+    def describe_method name, **metadata, &block
+      describe(
+        "#{ NRSER::RSpex::PREFIXES[:method] } #{ name }",
+        type: :method,
+        **metadata
+      ) do
+        instance_exec &block
+      end
+    end # #describe_section
+    
+    
+    # Define a `context` block with `let` bindings and evaluate the `body`
+    # block in it.
+    # 
+    # @param [Hash<Symbol, Object>] **bindings
+    #   Map of symbol names to value to bind using `let`.
+    # 
+    # @param [#call] &body
+    #   Body block to evaluate in the context.
+    # 
+    # @return
+    #   Whatever `context` returns.
+    # 
+    def context_where **bindings, &body
+      description = bindings.map { |name, value|
+        "let #{ name } = #{ value }"
+      }.join( ',  ' )
+      
+      context "| #{ description } |", type: :where do
+        bindings.each { |name, value|
+          let( name ) { unwrap value, context: self }
+        }
+        
+        instance_exec &body
+      end
+    end
+    
+    
+  end # module ExampleGroup
+  
+end # module NRSER:RSpex
+
+RSpec.configure do |config|
+  config.extend NRSER::RSpex::ExampleGroup
+end
+
+
+include NRSER::RSpex::ExampleGroup
+
+
+# Shared Examples
+# =====================================================================
+
+shared_examples "expect subject" do |*expectations|
+  merge_expectations( *expectations ).each { |state, specs|
+    specs.each { |verb, noun|
+      it {
+        # like: is_expected.to(include(noun))
+        is_expected.send state, self.send(verb, noun)
+      }
+    }
+  }
+end # is expected
+
+
+# Shared example for a functional method that compares input and output pairs.
+# 
+shared_examples "function" do |mapping: {}, raising: {}|
+  mapping.each { |args, expected|
+    args = NRSER.as_array args
+    
+    context "called with #{ args.map( &:inspect ).join ', ' }" do
+      subject { super().call *args }
+      
+      it {
+        expected = unwrap expected, context: self
+        
+        matcher = if expected.respond_to?( :matches? )
+          expected
+        elsif expected.is_a? NRSER::Message
+          expected.send_to self
+        else
+          eq expected
+        end
+        
+        is_expected.to matcher
+      }
+    end
+  }
+  
+  raising.each { |args, error|
+    args = NRSER.as_array args
+    
+    context "called with #{ args.map( &:inspect ).join ', ' }" do
+    # it "rejects #{ args.map( &:inspect ).join ', ' }" do
+      it { expect { subject.call *args }.to raise_error( *error ) }
+    end
+  }
+end # function
+