nrser 0.0.26 → 0.0.27

data/lib/nrser/proc.rb

@@ -31,8 +31,12 @@ module NRSER
   # 
   # @return [NRSER::Message]
   # 
-  def self.message symbol, *args, &block
-    NRSER::Message.new symbol, *args, &block
+  def self.message *args, &block
+    if args.length == 1 && args[0].is_a?( Message )
+      args[0]
+    else
+      Message.new *args, &block
+    end
   end # #message
   
   singleton_class.send :alias_method, :msg, :message
@@ -102,7 +106,7 @@ module NRSER
   # @return [Proc]
   # 
   def self.chainer mappable, publicly: true
-    messages = mappable.map { |value| NRSER::Message.new *value }
+    messages = mappable.map { |value| message *value }
     
     ->( receiver ) {
       messages.reduce( receiver ) { |receiver, message|

data/lib/nrser/refinements/array.rb

@@ -25,6 +25,11 @@ module NRSER
     end # #rest
     
     
+    def extract! &block
+      NRSER.extract_from_array! self, &block
+    end
+    
+    
     # `to_*` Converters
     # =====================================================================
     

data/lib/nrser/refinements/enumerable.rb

@@ -37,6 +37,11 @@ module NRSER::Refinements::Enumerable
     NRSER.enumerate_as_values self
   end
   
+  # Calls {NRSER.only} on `self`.
+  def only **options
+    NRSER.only self, **options
+  end
+  
   # See {NRSER.only!}
   def only!
     NRSER.only! self

data/lib/nrser/refinements/hash.rb

@@ -58,24 +58,32 @@ module NRSER
       NRSER.symbolize_keys! self
     end
     
+    alias_method :sym_keys!, :symbolize_keys!
+    
     
     # See {NRSER.symbolize_keys}
     def symbolize_keys
       NRSER.symbolize_keys self
     end
     
+    alias_method :sym_keys, :symbolize_keys
+    
     
     # See {NRSER.stringify_keys!}
     def stringify_keys!
       NRSER.stringify_keys! self
     end
     
+    alias_method :str_keys!, :stringify_keys!
+    
     
     # See {NRSER.stringify_keys}
     def stringify_keys
       NRSER.stringify_keys self
     end
     
+    alias_method :str_keys, :stringify_keys
+    
     
     # See {NRSER.map_hash_keys}
     def map_keys &block

data/lib/nrser/refinements/object.rb

@@ -19,10 +19,20 @@ module NRSER
   refine Object do
     # Yield `self`. Analogous to {#tap} but returns the result of the invoked
     # block.
-    def pipe
+    def thru
       yield self
     end
     
+    # Older name, depreciated because though 'pipe' was the natural name to me,
+    # it was probably a poor choice... it's widely used and usually denotes
+    # streaming of some sort (and rightfully so given Unix pipes).
+    # 
+    # I think I want to move over to {Object#thru}, but will leave the old
+    # name for the moment.
+    # 
+    alias_method :pipe, :thru
+    
+    
     # See {NRSER.truthy?}.
     def truthy?
       NRSER.truthy? self

data/lib/nrser/refinements/string.rb

@@ -1,27 +1,35 @@
 require 'pathname'
 
+require 'nrser/string'
+require 'nrser/text'
+
 module NRSER
   refine String do
     def squish
       NRSER.squish self
     end
     
+    
     def unblock
       NRSER.unblock self
     end
-
+    
+    
     def dedent
       NRSER.dedent self
     end
-
+    
+    
     def indent *args
       NRSER.indent self, *args
     end
-
+    
+    
     def truncate *args
       NRSER.truncate self, *args
     end
     
+    
     # See {NRSER.constantize}
     def constantize
       NRSER.constantize self
@@ -29,6 +37,7 @@ module NRSER
     
     alias_method :to_const, :constantize
     
+    
     # @return [Pathname]
     #   Convert self into a {Pathname}
     # 
@@ -36,5 +45,10 @@ module NRSER
       Pathname.new self
     end
     
+    
+    def whitespace?
+      NRSER.whitespace? self
+    end
+    
   end # refine String
 end # NRSER

data/lib/nrser/refinements/symbol.rb

@@ -1,6 +1,7 @@
 module NRSER
   refine ::Symbol do
     
+    # See {NRSER.retriever}.
     def to_retriever
       NRSER.retriever self
     end
@@ -8,5 +9,12 @@ module NRSER
     alias_method :retriever, :to_retriever
     alias_method :rtvr, :to_retriever
     
+    
+    # Alias 'sender' methods to built-in {#to_proc} so symbols can behave like
+    # arrays in this way
+    alias_method :to_sender,  :to_proc
+    alias_method :sender,     :to_sender
+    alias_method :sndr,       :to_sender
+    
   end # refine ::Symbol
 end # NRSER

data/lib/nrser/refinements/tree.rb

@@ -32,10 +32,32 @@ module NRSER::Refinements::Tree
   end # #leaves
   
   
+  # Calls {NRSER.map_leaves} on `self` with `&block`.
+  # 
+  def map_leaves &block
+    NRSER.map_leaves self, &block
+  end
+  
+  
   # Sends `self` and the optional `block` to {NRSER.each_branch}.
+  # 
   def each_branch &block
     NRSER.each_branch self, &block
   end
   
+  
+  # Calls {NRSER.map_branches} on `self` with `&block`.
+  # 
+  def map_branches &block
+    NRSER.map_branches self, &block
+  end # #map_branches
+  
+  
+  # Calls {NRSER.map_tree} on `self` with `&block`.
+  # 
+  def map_tree **options, &block
+    NRSER.map_tree self, **options, &block
+  end
+  
 end # module NRSER::Refinements::Tree
 

data/lib/nrser/rspex.rb

@@ -22,7 +22,8 @@
 
 # Project / Package
 # -----------------------------------------------------------------------
-require_relative './message'
+require 'nrser/message'
+require 'nrser/rspex/shared_examples'
 
 
 # Helpers
@@ -83,23 +84,214 @@ def unwrap obj, context: nil
   end
 end
 
+
+def List *args
+  NRSER::RSpex::List.new args
+end
+
+def Args *args
+  NRSER::RSpex::Args.new args
+end
+
 # Extensions
 # =====================================================================
 
 module NRSER; end
 
-module NRSER::RSpex
-  PREFIXES = {
-    # module: "𝓜 𝓸𝓭𝓾𝓵𝓮",
-    module: "𝞛",
+module NRSER::RSpex  
+  
+  # Constants
+  # =====================================================================
+  
+  
+  # Symbols
+  # ---------------------------------------------------------------------
+  # 
+  # Sources:
+  # 
+  # -   https://en.wikipedia.org/wiki/Mathematical_operators_and_symbols_in_Unicode
+  # 
+  
+  PREFIXES_BASE = {
     section: '§',
-    method: '𝞴',
+    group: '•',
+    invocation: '⟮⟯',
   }
   
+  PREFIXES_MATH_ITALIC = PREFIXES_BASE.merge(
+    module:       '𝑀',
+    method:       '𝑚',
+    class:        '𝐶',
+    attribute:    '𝑎',
+    file:         '𝐹',
+  )
+  
+  PREFIXES_MATH_CURSIVE_WORDS = PREFIXES_BASE.merge(
+    module:       '𝓜 𝓸𝓭𝓾𝓵𝓮',
+    method:       '𝓶𝓮𝓽',
+    class:        '𝐶',
+    attribute:    '𝑎',
+    file:         '𝐹',
+  )
+  
+  # PREFIXES_MATH_GREEK = PREFIXES_BASE.merge(
+  #   # module: "𝓜 𝓸𝓭𝓾𝓵𝓮",
+  #   module:       '𝛭',
+  #   method:       '𝜆',
+  #   class:        '𝛤',
+  #   attribute:    '𝛼',
+  # )
+  
+  PREFIXES = PREFIXES_MATH_ITALIC
+  
+  
+  # Module (Class) Functions
+  # =====================================================================
+  
+  
+  # @todo Document short_s method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.short_s value, max = 64
+    NRSER.smart_ellipsis value.inspect, max
+  end # .short_s
+  
+  
+  
+  # @todo Document format_type method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.format_type type, description
+    prefixes = RSpec.configuration.x_type_prefixes
+    
+    return description if type.nil? || !prefixes.key?( type )
+    
+    "#{ prefixes[type] } #{ description }"
+  end # .format_type
+  
+  
+  
+  # @todo Document format method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.format *parts, type: nil
+    format_type \
+      type,
+      parts.
+        map { |part|
+          if part.respond_to? :to_desc
+            part.to_desc
+          elsif part.is_a? String
+            part
+          else
+            short_s part
+          end
+        }.
+        join( ' ' )
+  end # .format
+  
+  
+  class List < Array
+    def to_desc max = nil
+      max = [16, 64 / self.length].max if max.nil?
+      map { |entry| NRSER::RSpex.short_s entry, max }.join ", "
+    end
+  end
+  
+  
+  class Opts < Hash
+    def to_desc max = nil
+      max = [16, ( 64 / self.count )].max if max.nil?
+      
+      map { |key, value|
+        if key.is_a? Symbol
+          "#{ key }: #{ NRSER::RSpex.short_s value, max }"
+        else
+          "#{ NRSER::RSpex.short_s key, max } => #{ NRSER::RSpex.short_s value, max }"
+        end
+      }.join( ", " )
+    end
+  end
+  
+  
+  class Args < Array
+    def to_desc max = nil
+      if last.is_a?( Hash )
+        [
+          List.new( self[0..-2] ).to_desc,
+          Opts[ last ].to_desc,
+        ].reject( &:empty? ).join( ", " )
+      else
+        super
+      end
+    end
+  end
+  
+  
   # Instance methods to extend example groups with.
   # 
   module ExampleGroup
     
+    
+    # @todo Document describe_x method.
+    # 
+    # @param [type] arg_name
+    #   @todo Add name param description.
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    def describe_x_type *description_parts,
+                        type:,
+                        metadata: {},
+                        subject_block: nil,
+                        &body
+      
+      description = NRSER::RSpex.format *description_parts, type: type
+      
+      describe description, **metadata, type: type do
+        subject( &subject_block ) if subject_block
+        instance_exec &body
+      end # description, 
+      
+    end # #describe_x
+    
+    
+    # @todo Document describe_instance method.
+    # 
+    # @param [type] arg_name
+    #   @todo Add name param description.
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    def describe_instance *constructor_args, &body
+      describe_x_type ".new(", Args(*constructor_args), ")",
+        type: :instance,
+        metadata: {
+          constructor_args: constructor_args,
+        },
+        # subject_block: -> { super().new *described_args },
+        subject_block: -> { super().new *described_constructor_args },
+        &body
+    end # #describe_instance
+    
+    
     # Create a new {RSpec.describe} section where the subject is set by
     # calling the parent subject with `args` and evaluate `block` in it.
     # 
@@ -119,11 +311,11 @@ module NRSER::RSpex
     #   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
+    def describe_called_with *args, &body
+      describe_x_type  "called with", List(*args),
+        type: :invocation,
+        subject_block: -> { super().call *args },
+        &body
     end # #describe_called_with
     
     # Aliases to other names I was using at first... not preferring their use
@@ -137,7 +329,7 @@ module NRSER::RSpex
     
     def describe_message symbol, *args, &body
       description = \
-        "message #{ [symbol, *args].map( &:inspect ).join( ', ' ) }"
+        "message #{ [symbol, *args].map( &NRSER::RSpex.method( :short_s ) ).join( ', ' ) }"
       
       describe description, type: :message do
         subject { NRSER::Message.new symbol, *args }
@@ -182,6 +374,16 @@ module NRSER::RSpex
     alias_method :when_sent_to, :describe_sent_to
     
     
+    def describe_return_value *args, &body
+      msg = NRSER::Message.from *args
+      
+      describe "return value from #{ msg }" do
+        subject { msg.send_to super() }
+        instance_exec &body
+      end # "return value from #{ msg }"
+    end
+    
+    
     # Describe a "section". Just like {RSpec.describe} except it:
     # 
     # 1.  Expects a string title.
@@ -216,6 +418,20 @@ module NRSER::RSpex
     alias_method :describe_topic, :describe_section
     
     
+    def describe_file path, **metadata, &body
+      title = path
+      
+      describe(
+        "#{ NRSER::RSpex::PREFIXES[:file] } #{ title }",
+        type: :file,
+        file: path,
+        **metadata
+      ) do
+        instance_exec &body
+      end
+    end
+    
+    
     def describe_module mod, **metadata, &block
       describe(
         "#{ NRSER::RSpex::PREFIXES[:module] } #{ mod.name }",
@@ -227,15 +443,69 @@ module NRSER::RSpex
     end # #describe_module
     
     
+    def describe_class klass, bind_subject: true, **metadata, &block
+      description = "#{ NRSER::RSpex::PREFIXES[:class] } #{ klass.name }"
+      
+      describe(
+        description,
+        type: :class,
+        class: klass,
+        **metadata
+      ) do
+        if bind_subject
+          subject { klass }
+        end
+        
+        instance_exec &block
+      end
+    end # #describe_class
+    
+    
+    def described_class
+      metadata[:class] || super()
+    end
+    
+    
+    def describe_group title, **metadata, &block
+      describe(
+        "#{ NRSER::RSpex::PREFIXES[:group] } #{ title }",
+        type: :group,
+        **metadata
+      ) do
+        instance_exec &block
+      end
+    end # #describe_class
+    
+    
     def describe_method name, **metadata, &block
       describe(
         "#{ NRSER::RSpex::PREFIXES[:method] } #{ name }",
         type: :method,
+        method_name: name,
         **metadata
       ) do
+        if name.is_a? Symbol
+          subject { super().method name }
+        end
+        
         instance_exec &block
       end
-    end # #describe_section
+    end # #describe_method
+    
+    
+    def describe_attribute symbol, **metadata, &block
+      describe(
+        "#{ NRSER::RSpex::PREFIXES[:attribute] } ##{ symbol }",
+        type: :attribute,
+        **metadata
+      ) do
+        subject { super().public_send symbol }
+        instance_exec &block
+      end
+    end # #describe_attribute
+    
+    # Shorter name
+    alias_method :describe_attr, :describe_attribute
     
     
     # Define a `context` block with `let` bindings and evaluate the `body`
@@ -250,12 +520,15 @@ module NRSER::RSpex
     # @return
     #   Whatever `context` returns.
     # 
-    def context_where **bindings, &body
-      description = bindings.map { |name, value|
-        "let #{ name } = #{ value }"
-      }.join( ',  ' )
+    def context_where description = nil, **bindings, &body
       
-      context "| #{ description } |", type: :where do
+      if description.nil?
+        description = bindings.map { |name, value|
+          "#{ name }: #{ NRSER::RSpex.short_s value }"
+        }.join( ", " )
+      end
+      
+      context "△ #{ description }", type: :where do
         bindings.each { |name, value|
           let( name ) { unwrap value, context: self }
         }
@@ -267,63 +540,32 @@ module NRSER::RSpex
     
   end # module ExampleGroup
   
+  
+  # Extensions available in examples themselves via RSpec's `config.include`.
+  # 
+  module Example
+    def described_class
+      self.class.metadata[:class] || super
+    end
+    
+    def described_constructor_args
+      self.class.metadata[:constructor_args]
+    end
+    
+  end
+  
 end # module NRSER:RSpex
 
+
 RSpec.configure do |config|
   config.extend NRSER::RSpex::ExampleGroup
+  config.include NRSER::RSpex::Example
+  
+  config.add_setting :x_type_prefixes
+  config.x_type_prefixes = \
+    NRSER::RSpex::PREFIXES_BASE.merge( NRSER::RSpex::PREFIXES_MATH_ITALIC )
 end
 
-
+# Make available at the top-level
 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
-