nrser 0.2.2 → 0.3.0

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

@@ -0,0 +1,49 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module NRSER::RSpex::ExampleGroup
+  
+  # Create an example group covering a source file.
+  # 
+  # Useful for when method implementations are spread out across multiple
+  # files but you want to group examples by the source file they're in.
+  # 
+  # @note
+  #   Honestly, now that modules, classes and methods described through RSpex
+  #   add their source locations, this is not all that useful. But it was
+  #   there from before that, which is why for the moment it's still here.
+  # 
+  # @see #describe_x
+  #
+  # @param [String | Pathname] path
+  #   File path.
+  # 
+  # @param *description (see #describe_x)
+  # 
+  # @param [Hash<Symbol, Object>] **metadata
+  #   RSpec metadata to set for the example group.
+  #   
+  #   See the `metadata` keyword argument to {#describe_x}.
+  #   
+  #   A `file` key is added pointed to the {Pathname} for `path` before
+  #   passing up to {#describe_x}.
+  # 
+  # @param &body (see #describe_x)
+  # 
+  # @return (see #describe_x)
+  # 
+  def describe_source_file path, *description, **metadata, &body
+    path = path.to_pn
+    
+    describe_x \
+      path,
+      *description,
+      type: :source_file,
+      metadata: {
+        source_file: path,
+        **metadata,
+      },
+      &body
+  end
+  
+end # module NRSER::RSpex::ExampleGroup

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

@@ -4,6 +4,26 @@ using NRSER
 
 module NRSER::RSpex::ExampleGroup
   
+  def dive_x current, *rest, **kwds, &body
+    type, data = current
+    
+    method_name = "describe_#{ type }"
+    
+    block = if rest.empty?
+      body
+    else
+      -> { dive_x *rest, &body }
+    end
+    
+    begin
+      public_send method_name, data, **kwds, &block
+    rescue NoMethodError => error
+      pp self.methods
+      raise error
+    end
+  end
+  
+  
   # **EXPERIMENTAL**
   # 
   # Example group helper for use at the top level of each spec file to
@@ -26,7 +46,7 @@ module NRSER::RSpex::ExampleGroup
   #   
   #   Probably possible to extract this somehow without having to provide it?
   # 
-  # @return [nil]
+  # @return (see #describe_x)
   # 
   def describe_spec_file  description: nil,
                           spec_path:,
@@ -34,118 +54,31 @@ module NRSER::RSpex::ExampleGroup
                           **metadata,
                           &body
     
-    if metadata[:module] && metadata[:method]
-      meth = metadata[:module].method metadata[:method]
-      file, line = meth.source_location
-      path = Pathname.new file
-      loc = "./#{ path.relative_path_from Pathname.getwd }:#{ line }"
-      
-      spec_rel_path = \
-        "./#{ Pathname.new( spec_path ).relative_path_from Pathname.getwd }"
-      
-      desc = [
-        "#{ metadata[:module].name }.#{ metadata[:method] }",
-        "(#{ loc })",
-        description,
-        "Spec (#{ spec_rel_path})"
-      ].compact.join " "
-      
-      subj = meth
+    chain = []
     
-    elsif metadata[:class]
-      klass = metadata[:class]
-      
-      if metadata[:instance_method]
-        instance_method = klass.instance_method metadata[:instance_method]
-        
-        file, line = instance_method.source_location
-        
-        name = "#{ klass.name }##{ metadata[:instance_method] }"
-        
-      elsif metadata[:method]
-        # Class method
-        meth = metadata[:class].method metadata[:method]
-        file, line = meth.source_location
-        path = Pathname.new file
-        loc = "./#{ path.relative_path_from Pathname.getwd }:#{ line }"
-
-        spec_rel_path = \
-          "./#{ Pathname.new( spec_path ).relative_path_from Pathname.getwd }"
-
-        desc = [
-          "#{ metadata[:class].name }.#{ metadata[:method] }",
-          "(#{ loc })",
-          description,
-          "Spec (#{ spec_rel_path})"
-        ].compact.join " "
-
-        subj = meth
-        
-      else
-        name = klass.name
-        
-        # Get a reasonable file and line for the class
-        file, line = klass.
-          # Get an array of all instance methods, excluding inherited ones
-          # (the `false` arg)
-          instance_methods( false ).
-          # Add `#initialize` since it isn't in `#instance_methods` for some
-          # reason
-          <<( :initialize ).
-          # Map those to their {UnboundMethod} objects
-          map { |sym| klass.instance_method sym }.
-          # Toss any `nil` values
-          compact.
-          # Get the source locations
-          map( &:source_location ).
-          # Get rid of `[nil, nil]` results, which seems to come from C exts
-          reject { |(path, line)| path.nil? || line.nil? }.
-          # Get the first line in the shortest path
-          min_by { |(path, line)| [path.length, line] }
-          
-          # Another approach I thought of... (untested)
-          # 
-          # Get the path
-          # # Get frequency of the paths
-          # count_by { |(path, line)| path }.
-          # # Get the one with the most occurrences
-          # max_by { |path, count| count }.
-          # # Get just the path (not the count)
-          # first
-      end
-      
-      location = if file
-        "(#{ NRSER::RSpex.dot_rel_path file }:#{ line })"
+    [
+      :source_file,
+      :module,
+      :class,
+      :instance,
+      :method,
+      :instance_method,
+      :called_with,
+      :attribute,
+    ].each do |type|
+      if data = metadata.delete( type )
+        chain << [type, data]
       end
-      
-      desc = [
-        "𝑆𝑃𝐸𝐶 𝐹𝐼𝐿𝐸 `#{ NRSER::RSpex.dot_rel_path spec_path }` 𝐹𝑂𝑅",
-        name,
-        location,
-        description,
-      ].compact.join " "
-      
-      subj = klass
-      
-    else
-      # TODO  Make this work!
-      raise ArgumentError.new binding.erb <<-END
-        Not yet able to handle metadata:
-        
-            <%= metadata.pretty_inspect %>
-        
-      END
     end
     
-    describe desc, **metadata do
-      if bind_subject
-        subject { subj }
-      end
-      
-      module_exec &body
+    describe_x(
+      NRSER::RSpex.dot_rel_path( spec_path ),
+      *description,
+      type: :spec_file,
+      metadata: metadata,
+    ) do
+      dive_x *chain, bind_subject: bind_subject, &body
     end
-    
-    nil
   end # #describe_spec_file
   
 end # module NRSER::RSpex::ExampleGroup

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

@@ -1,18 +1,20 @@
+# encoding: UTF-8
 # frozen_string_literal: true
 
 module NRSER::RSpex::ExampleGroup
   
-  # Define a example group block with `let` bindings and evaluate the `body`
-  # block in it.
+  # Define a example group with the keyword args as bindings.
+  # 
+  # @see #describe_x
+  # 
+  # @param *description (see #describe_x)
   # 
   # @param [Hash<Symbol, Object>] **bindings
-  #   Map of symbol names to value to bind using `let`.
+  #   See the `bindings` keyword arg in {#describe_x}.
   # 
-  # @param [#call] &body
-  #   Body block to evaluate in the context.
+  # @param &body (see #describe_x)
   # 
-  # @return
-  #   Whatever `context` returns.
+  # @return (see #describe_x)
   # 
   def describe_when *description, **bindings, &body
     describe_x \
@@ -22,4 +24,9 @@ module NRSER::RSpex::ExampleGroup
       &body
   end
   
+  # Old name (used to be different method)
+  
+  alias_method :context_where, :describe_when
+  
+  
 end # module NRSER::RSpex::ExampleGroup

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

@@ -23,25 +23,38 @@ module NRSER::RSpex::ExampleGroup
   #   key.
   # 
   # @param [Hash<Symbol, Object>] metadata:
-  #   Metadata to add to the new example group.
+  #   [RSpec 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.
+  #   
+  #   [RSpec metadata]: https://relishapp.com/rspec/rspec-core/docs/metadata/user-defined-metadata
   # 
   # @param [Hash<Symbol, Object>] bindings:
+  #   Name to value pairs to bind in the new example group.
   #   
+  #   All values will be bound at the example group and example levels -
+  #   though if they are {Wrapper}, that wrapper will be available at the
+  #   group level, while they will be automatically unwrapped at the
+  #   example level (as the requisite context is available there).
+  # 
+  # @param [Boolean] bind_subject:
+  #   When `true` (and there is a `subject_block`) bind the `subject` inside
+  #   the new example group.
+  # 
+  # 
   # 
-  # @return [return_type]
-  #   @todo Document return value.
+  # @return [void]
   # 
   def describe_x  *description,
                   type:,
                   metadata: {},
                   bindings: {},
                   add_binding_desc: true,
+                  bind_subject: true,
                   subject_block: nil,
                   &body
     
@@ -67,30 +80,44 @@ module NRSER::RSpex::ExampleGroup
       END
     end
     
+    # Add description of the bindings, if we have any and were told to
     unless bindings.empty? || add_binding_desc == false
-      # bindings_desc = NRSER::RSpex::Opts[bindings].to_desc
-      bindings_desc = ["(", bindings.ai( multiline: false ), ")"]
+      bindings_desc =  NRSER::RSpex::Format.md_code_quote \
+        bindings.map { |name, value|
+          "#{ name } = #{ value.inspect }"
+        }.join( '; ' )
       
       if description.empty?
-        description = bindings.ai( multiline: false )
+        description = bindings_desc
       else
-        description += ["(", bindings.ai( multiline: false ), ")"]
+        description << "(" + bindings_desc + ")"
       end
     end
     
-    formatted = NRSER::RSpex::Format.description *description, type: type
-    
-    describe formatted, **metadata, type: type do
-      subject( &subject_block ) if subject_block
+    # Call up to RSpec's `#describe` method
+    describe(
+      NRSER::RSpex::Format.description( *description, type: type ),
+      **metadata,
+      type: type,
+    ) do
+      if subject_block && bind_subject
+        subject &subject_block
+      end
       
+      # Bind bindings
       unless bindings.empty?
         bindings.each { |name, value|
+          # Example-level binding
           let( name ) { unwrap value, context: self }
+          
+          # Example group-level binding (which may return a {Wrapper} that
+          # of course can not be unwrapped at the group level)
+          define_singleton_method( name ) { value }
         }
       end
       
       module_exec &body
-    end # description,
+    end # describe
     
   end # #describe_x
   

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+
+# Definitions
+# =======================================================================
+
+module NRSER::RSpex::ExampleGroup
+  
+  # HACK HACK HACK-ITY HACK - Allow for overriding RSpec methods
+  # 
+  # Yeah, it has to do with mixin mixing-in ordering - seems to be that when
+  # 
+  #     config.extend NRSER::RSpex::ExampleGroup
+  # 
+  # {NRSER::RSpex::ExampleGroup} gets mixed in *very early* in the chain,
+  # before {RSpec::Core::ExampleGroup}... why you would provide an explicit
+  # extension mechanism and not give those extensions priority I'm not sure,
+  # but I'm sure I shouldn't be looking into it right now, so here we are:
+  # 
+  # It turns out that {NRSER::RSpex::Example}, which gets mixed with
+  # 
+  #     config.include NRSER::RSpex::Example
+  # 
+  # gets mixed *last*, so by using it's {NRSER::RSpex::Example.included}
+  # hook we can use
+  # 
+  #   base#extend NRSER::RSpex::ExampleGroup::Overrides
+  # 
+  # to mix these guys over the top of RSpec's methods.
+  # 
+  # Seems like we could just mix all of {NRSER::RSpex::ExampleGroup} there
+  # to get the behavior I would have expected all along, but maybe it's better
+  # to have these explicit notes for the moment and not change much else until
+  # I get the chance to really check out what's going on.
+  # 
+  # And really it's all to override `.described_class` to pick up our
+  # metadata if it's there, but that approach is in quite a bit of use at
+  # this point, and, no, I have no idea how it seemed to work up until this
+  # point :/
+  # 
+  module Overrides
+    
+    # Override {RSpec::Core::ExampleGroup.described_class} to use RSpex's
+    # `:class` metadata if it's present.
+    # 
+    # Because I can't figure out how to feed RSpec the described class
+    # without it being the description, and we want better descriptions.
+    # 
+    # Some hackery could def do it, this is RUBY after all, but whatever this
+    # works for now and may even be less fragile.
+    # 
+    # @return [Class]
+    #   If there's a `:class` in the metadata, or if RSpec has on through the
+    #   standard means (`describe MyClass do ...`).
+    # 
+    # @return [nil]
+    #   If we don't have a class context around.
+    # 
+    def described_class
+      metadata[:class] || super()
+    end
+    
+  end # module Overrides
+  
+end # module NRSER:RSpex::ExampleGroup