nrser 0.1.1 → 0.1.2

data/lib/nrser/rspex/example_group/describe_x.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module NRSER::RSpex::ExampleGroup
+  
+  # The core, mostly internal method that all RSpex's description methods lead
+  # back too (or should / will when refactoring is done).
+  # 
+  # Keyword options are explicitly broken out in this method, versus the sugary
+  # ones that call it, so `metadata` can be set without restriction (save the
+  # `type` key, which is also it's own keyword here). You can use this method
+  # if you want the RSpex functionality but absolutely have to set some
+  # metadata key that we use for something else.
+  # 
+  # @param [Array] *description
+  #   Optional list of elements that compose the custom description.
+  #   
+  #   Will be passed to {NRSER::RSpex::Format.description} to produce the
+  #   string value that is in turn passed to {RSpec.describe}.
+  # 
+  # @param [Symbol] type:
+  #   The RSpex "type" of the example group, which is used to determine the
+  #   prefix of the final description and is assigned to the `:type` metadata
+  #   key.
+  # 
+  # @param [Hash<Symbol, Object>] metadata:
+  #   Metadata to add to the new example group.
+  #   
+  #   In addition to the keys RSpec will reject, we prohibit `:type` *unless*
+  #   it is the same as the `type` keyword argument or `nil`.
+  #   
+  #   In either of these cases, the `type` keyword arg will be used for the new
+  #   example group's `:type` metadata value.
+  # 
+  # @param [Hash<Symbol, Object>] bindings:
+  #   
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def describe_x  *description,
+                  type:,
+                  metadata: {},
+                  bindings: {},
+                  add_binding_desc: true,
+                  subject_block: nil,
+                  &body
+    
+    # Check that `metadata` doesn't have a `:type` value too... although we
+    # allow it if's equal to `type` or `nil` 'cause why not I guess?
+    # 
+    if  metadata.key?( :type ) &&
+        metadata[:type] != nil &&
+        metadata[:type] != type
+      raise ArgumentError.new binding.erb <<-END
+        `metadata:` keyword argument may not have a `:type` key that conflicts
+        with the `type:` keyword argument.
+        
+        Received:
+          `type`:
+          
+              <%= type.inspect %>
+          
+          `metadata[:type]`:
+          
+              <%= metadata[:type].pretty_inspect %>
+        
+      END
+    end
+    
+    unless bindings.empty? || add_binding_desc == false
+      # bindings_desc = NRSER::RSpex::Opts[bindings].to_desc
+      bindings_desc = ["(", bindings.ai( multiline: false ), ")"]
+      
+      if description.empty?
+        description = bindings.ai( multiline: false )
+      else
+        description += ["(", bindings.ai( multiline: false ), ")"]
+      end
+    end
+    
+    formatted = NRSER::RSpex::Format.description *description, type: type
+    
+    describe formatted, **metadata, type: type do
+      subject( &subject_block ) if subject_block
+      
+      unless bindings.empty?
+        bindings.each { |name, value|
+          let( name ) { unwrap value, context: self }
+        }
+      end
+      
+      module_exec &body
+    end # description,
+    
+  end # #describe_x
+  
+  alias_method :describe_x_type, :describe_x
+  
+  
+end # module NRSER::RSpex::ExampleGroup

data/lib/nrser/rspex/example_group.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+# Instance methods to extend examples groups with. Also included globally so
+# they're available at the top-level in files.
+# 
+module NRSER::RSpex::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, &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
+  # 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( &NRSER::RSpex.method( :short_s ) ).join( ', ' ) }"
+    
+    describe description, type: :message do
+      subject { NRSER::Message.new symbol, *args }
+      module_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 ) }
+      module_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
+  
+  
+  def describe_return_value *args, &body
+    msg = NRSER::Message.from *args
+    
+    describe "return value from #{ msg }" do
+      subject { msg.send_to super() }
+      module_exec &body
+    end # "return value from #{ msg }"
+  end
+  
+  
+  # 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
+      module_exec &block
+    end
+  end # #describe_section
+  
+  # Old name
+  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
+      module_exec &body
+    end
+  end
+  
+  
+  def describe_module mod, bind_subject: true, **metadata, &block
+    describe(
+      "#{ NRSER::RSpex::PREFIXES[:module] } #{ mod.name }",
+      type: :module,
+      module: mod,
+      **metadata
+    ) do
+      if bind_subject
+        subject { mod }
+      end
+      
+      module_exec &block
+    end
+  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
+      
+      module_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
+      module_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
+      
+      module_exec &block
+    end
+  end # #describe_method
+  
+  
+  def describe_attribute symbol, **metadata, &block
+    describe(
+      "#{ NRSER::RSpex::PREFIXES[:attribute] } ##{ symbol }",
+      type: :attribute,
+      **metadata
+    ) do
+      subject { super().public_send symbol }
+      module_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`
+  # 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 description = nil, **bindings, &body
+    
+    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 }
+      }
+      
+      module_exec &body
+    end
+  end
+  
+end # module NRSER:RSpex::ExampleGroup
+
+
+# Post-Processing
+# =======================================================================
+
+require_relative './example_group/describe_x'
+require_relative './example_group/describe_spec_file'
+require_relative './example_group/describe_when'
+require_relative './example_group/describe_setup'
+require_relative './example_group/describe_use_case'
+require_relative './example_group/describe_instance'

data/lib/nrser/rspex/format.rb

@@ -0,0 +1,174 @@
+require 'pastel'
+
+using NRSER
+
+# Definitions
+# =======================================================================
+
+# String formatting utilities.
+# 
+module NRSER::RSpex::Format
+
+  
+  PASTEL = Pastel.new
+  
+  def self.transpose_A_z string, lower_a:, upper_a:
+    string
+      .gsub( /[A-Z]/ ) { |char|
+        [upper_a.ord + (char.ord - 'A'.ord)].pack 'U*'
+      }
+      .gsub( /[a-z]/ ) { |char|
+        [lower_a.ord + (char.ord - 'a'.ord)].pack 'U*'
+      }
+  end
+  
+  
+  # Italicize a string
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.unicode_italic string
+    transpose_A_z string, lower_a: '𝑎', upper_a: '𝐴'
+  end # .italic
+  
+  
+  def self.esc_seq_italic string
+    PASTEL.italic string
+  end
+  
+  
+  def self.italic string
+    public_send "#{ RSpec.configuration.x_style }_#{ __method__ }", string
+  end
+  
+  singleton_class.send :alias_method, :i, :italic
+  
+  
+  def self.fix_esc_seq commonmark
+    commonmark.gsub( "\e\\[", "\e[" )
+  end
+  
+  
+  # @todo Document render_commonmark method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.render_shelldown *render_doc_args
+    doc = CommonMarker.render_doc *render_doc_args
+    
+    transformed = transform_node( doc ).only!
+    commonmark = transformed.to_commonmark
+    ansi = fix_esc_seq commonmark
+    ansi
+  end # .render_commonmark
+  
+  
+  def self.text_node string_content
+    CommonMarker::Node.new( :text ).tap { |node|
+      node.string_content = string_content
+    }
+  end
+  
+  
+  def self.pastel_node name
+    text_node PASTEL.lookup( name )
+  end
+  
+  
+  def self.transform_node node
+    case node.type
+    when :emph
+      [
+        pastel_node( :italic ),
+        node.map { |child| transform_node child },
+        pastel_node( :clear ),
+      ].flatten
+    when :strong
+      [
+        pastel_node( :bold ),
+        node.map { |child| transform_node child},
+        pastel_node( :clear ),
+      ].flatten
+    when :text
+      [node]
+    when :code
+      [
+        pastel_node( :magenta ),
+        text_node( node.string_content ),
+        pastel_node( :clear ),
+      ]
+    else
+      new_node = CommonMarker::Node.new node.type
+      
+      # new_node.string_content = node.string_content
+      
+      node.
+        each { |child|
+          transform_node( child ).each { |new_child|
+            new_node.append_child new_child
+          }
+        }
+      
+      [new_node]
+    end
+  end
+  
+  
+  # @todo Document format_type method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.prepend_type type, description
+    return description if type.nil?
+    
+    prefixes = RSpec.configuration.x_type_prefixes
+    
+    prefix = prefixes[type] ||
+              PASTEL.magenta( i( type.to_s.upcase.gsub('_', ' ') ) )
+    
+    "#{ prefix } #{ description }"
+  end # .format_type
+  
+  
+  # @todo Document format method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [String]
+  # 
+  def self.description *parts, type: nil
+    parts.
+      map { |part|
+        if part.respond_to? :to_desc
+          part.to_desc
+        elsif part.is_a? String
+          part
+        else
+          short_s part
+        end
+      }.
+      join( ' ' ).
+      squish.
+      thru { |description|
+        render_shelldown prepend_type( type, description )
+      }
+  end # .description
+  
+end # module NRSER::RSpex::Format
+
+
+# Post-Processing
+# =======================================================================