nrser 0.2.2 → 0.3.0

data/lib/nrser/props/storage/instance_variable.rb

@@ -0,0 +1,85 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+
+# Declarations
+# =======================================================================
+
+module NRSER::Props::Storage; end
+
+
+# Definitions
+# =======================================================================
+
+# @todo document NRSER::Props::Storage::Key module.
+class NRSER::Props::Storage::InstanceVariable
+  
+  DEFAULT_VAR_NAME = :@__NRSER_prop_values
+  
+  # TODO document `var_name` attribute.
+  # 
+  # @return [Symbol]
+  #     
+  attr_reader :var_name
+  
+  
+  # TODO document `sub_storage` attribute.
+  # 
+  # @return [attr_type]
+  #     
+  attr_reader :sub_storage
+  
+  
+  def initialize  var_name: DEFAULT_VAR_NAME,
+                  sub_storage:
+    @var_name = var_name.to_sym
+    @sub_storage = sub_storage
+  end
+  
+  # Instance Methods
+  # ======================================================================
+  
+  
+  def init instance, collection
+    if init? instance
+      raise NRSER::ConflictError.new binding.erb <<~END
+        Already initialized!
+        
+        Instance:
+        
+            <%= instance.pretty_inspect %>
+        
+        Collection:
+        
+            <%= collection.pretty_inspect %>
+        
+      END
+    end
+    
+    instance.instance_variable_set @var_name, collection
+  end
+  
+  
+  def immutable?
+    sub_storage.immutable?
+  end
+  
+  
+  def init? instance
+    instance.instance_variable_defined? @var_name
+  end
+  
+  
+  def get instance, prop
+    sub_storage.get instance.instance_variable_get( @var_name ), prop
+  end
+  
+  
+  def put instance, prop, value
+    sub_storage.put \
+      instance.instance_variable_get( @var_name ),
+      prop,
+      value
+  end
+  
+end

data/lib/nrser/props/storage/instance_variables.rb

@@ -0,0 +1,67 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+
+# Declarations
+# =======================================================================
+
+module NRSER::Props::Storage; end
+
+
+# Definitions
+# =======================================================================
+
+# @todo document NRSER::Props::Storage::Key module.
+class NRSER::Props::Storage::InstanceVariables
+  
+  def initialize immutable:
+    @immutable = !!immutable
+  end
+  
+  
+  def immutable?
+    @immutable
+  end
+  
+  
+  def get instance, prop
+    instance.instance_variable_get "@#{ prop.name }"
+  end
+  
+  
+  def put instance, prop, value
+    if immutable?
+      raise RuntimeError.new binding.erb <<~END
+        Properties of #{ instance.class.safe_name } are immutable.
+        
+        Tried to set prop #{ prop.name } to value
+        
+            <%= value.pretty_inspect %>
+        
+        in instance
+        
+            <%= instance.pretty_inspect %>
+        
+      END
+    end
+    
+    instance.instance_variable_set "@#{ prop.name }", value
+  end
+  
+end

data/lib/nrser/props/storage/key.rb

@@ -0,0 +1,88 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+
+# Declarations
+# =======================================================================
+
+module NRSER::Props::Storage; end
+
+
+# Definitions
+# =======================================================================
+
+# @todo document NRSER::Props::Storage::Key module.
+class NRSER::Props::Storage::Key
+  
+  def initialize immutable:, key_type:, get: :[], put: :[]=
+    @immutable = !!immutable
+    @key_type = key_type
+    @get_method_name = get
+    @put_method_name = put
+  end
+  
+  # Instance Methods
+  # ======================================================================
+  
+  def immutable?
+    @immutable
+  end
+  
+  
+  def key_for prop
+    case @key_type
+    when :name
+      prop.name
+    when :index
+      prop.index
+    end
+  end
+  
+  
+  def get instance, prop
+    instance.send @get_method_name, key_for( prop )
+  end
+  
+  
+  def put instance, prop, value
+    key = key_for prop
+    
+    if immutable?
+      raise RuntimeError.new binding.erb <<~END
+        Properties of #{ instance.class.safe_name } are immutable.
+        
+        Tried to set key
+        
+            <%= key.pretty_inspect %>
+        
+        to value
+        
+            <%= value.pretty_inspect %>
+        
+        in instance
+        
+            <%= instance.pretty_inspect %>
+        
+      END
+    end
+    
+    instance.send @put_method_name, key, value
+  end
+  
+end # class NRSER::Props::Storage::Key

data/lib/nrser/props.rb

@@ -0,0 +1,9 @@
+require_relative './props/class_methods'
+require_relative './props/instance_methods'
+
+module NRSER::Props
+  def self.included base
+    base.include  NRSER::Props::InstanceMethods
+    base.extend   NRSER::Props::ClassMethods
+  end
+end

data/lib/nrser/refinements/sugar.rb

@@ -0,0 +1,41 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+# Need {NRSER::MethodMissingForwarder}
+require 'nrser/sugar/method_missing_forwarder'
+
+
+# Definitions
+# =======================================================================
+
+# Some sugary sweet stuff that I find nice but seems irresponsible to
+# monkey-patch in, so it's available as refinements.
+# 
+module NRSER::Sugar
+  
+  refine Object do
+    
+    # Get {Method} objects using concise syntax.
+    # 
+    # @example
+    #   text = 'bee!'
+    #   ['a', 'b', 'c'].any? { |char| text.meth.start_with? }
+    # 
+    # @return [NRSER::MethodMissingForwarder]
+    #   That forwards `#method_missing( symbol )` to `self.method( symbol )`.
+    # 
+    def meth
+      NRSER::MethodMissingForwarder.new do |symbol|
+        self.method symbol
+      end
+    end
+    
+  end # refine Object
+  
+end # module NRSER::Sugar

data/lib/nrser/refinements/types.rb

@@ -1,5 +1,5 @@
-module NRSER 
-  module Types 
+module NRSER
+  module Types
     refine Object do
       def t
         NRSER::Types

data/lib/nrser/refinements.rb

@@ -1,17 +1,15 @@
-# Declare the module
-module NRSER::Refinements; end
+# TODO Remove me
 
-# Require all refinements
-require_relative './refinements/object'
-require_relative './refinements/string'
-require_relative './refinements/array'
-require_relative './refinements/hash'
-require_relative './refinements/pathname'
-require_relative './refinements/exception'
-require_relative './refinements/binding'
-require_relative './refinements/set'
-require_relative './refinements/open_struct'
-require_relative './refinements/enumerator'
-require_relative './refinements/symbol'
-require_relative './refinements/types'
-require_relative './refinements/module'
+require_relative './log'
+
+NRSER.logger.warn <<~END
+  DEPRECIATED - `require 'nrser/refinements'` is now a no-op,
+  please remove the calls.
+  
+  Require specific refinements, like:
+  
+      require 'nrser/refinements/types'
+      require 'nrser/refinements/sugar'
+  
+  Thank you, the management.
+END

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

@@ -0,0 +1,24 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module NRSER::RSpex::ExampleGroup
+  
+  # Describe an attribute of the parent subject.
+  # 
+  # @return [void]
+  # 
+  def describe_attribute symbol, **metadata, &body
+    describe_x \
+      NRSER::RSpex::Format.md_code_quote( "##{ symbol }" ),
+      type: :attribute,
+      metadata: metadata,
+      subject_block: -> {
+        super().public_send symbol
+      },
+      &body
+  end # #describe_attribute
+
+  # Shorter name
+  alias_method :describe_attr, :describe_attribute
+  
+end # module NRSER::RSpex::ExampleGroup

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

@@ -31,12 +31,7 @@ module NRSER::RSpex::ExampleGroup
       &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.
+  # Short / old name
   alias_method :called_with, :describe_called_with
-  alias_method :when_called_with, :describe_called_with
   
 end # module NRSER::RSpex::ExampleGroup

data/lib/nrser/rspex/example_group/{describe_use_case.rb → describe_case.rb}

@@ -6,13 +6,16 @@ module NRSER::RSpex::ExampleGroup
   # 
   # @return [void]
   # 
-  def describe_use_case *description, where: {}, **metadata, &body
+  def describe_case *description, where: {}, **metadata, &body
     describe_x \
       *description,
-      type: :use_case,
+      type: :case,
       bindings: where,
       metadata: metadata,
       &body
-  end # #describe_use_case
+  end # #describe_case
+  
+  # Older name
+  alias_method :describe_use_case, :describe_case
   
 end # module NRSER::RSpex::ExampleGroup

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

@@ -18,6 +18,7 @@ module NRSER::RSpex::ExampleGroup
     
     describe_x \
       NRSER::RSpex::Format.md_code_quote( klass.name ),
+      klass.source_location,
       *description,
       type: :class,
       metadata: {

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

@@ -0,0 +1,29 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module NRSER::RSpex::ExampleGroup
+  
+  # Describe a "group". Doesn't really do much. Didn't end up getting used
+  # much. Probably not long for this world.
+  # 
+  # @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}.
+  # 
+  # @param &body          (see #describe_x)
+  # 
+  # @return (see #describe_x)
+  # 
+  def describe_group *description, **metadata, &body
+    # Pass up to {#describe_x}
+    describe_x \
+      *description,
+      type: :group,
+      metadata: metadata,
+      &body
+  end # #describe_group
+  
+end # module NRSER::RSpex::ExampleGroup

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

@@ -4,8 +4,8 @@ module NRSER::RSpex::ExampleGroup
   
   def describe_instance_method name, **metadata, &block
     describe(
-      "#{ NRSER::RSpex::PREFIXES[:method] } #{ name }",
-      type: :method,
+      "##{ name }",
+      type: :instance_method,
       method_name: name,
       **metadata
     ) do

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

@@ -0,0 +1,35 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module NRSER::RSpex::ExampleGroup
+  
+  # Describe a {NRSER::Message}. Useful when you have a message that you want
+  # to send to many receivers (see {#describe_sent_to}).
+  # 
+  # @note
+  #   Since the block is used for the example group body, if you want to
+  #   describe a message with a {NRSER::Message#block} your need to create
+  #   the message yourself and pass it as the only argument.
+  # 
+  # @see #describe_x
+  #
+  # @param [Array] *args
+  #   Passed to {NRSER::Message.from} to get or create the message instance.
+  # 
+  # @param &body (see #describe_x)
+  # 
+  # @return (see #describe_x)
+  # 
+  def describe_message *args, &body
+    message = NRSER::Message.from *args
+    
+    describe_x \
+      description,
+      type: :message,
+      metadata: {
+        message: message,
+      },
+      &body
+  end
+  
+end # module NRSER::RSpex::ExampleGroup

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

@@ -3,7 +3,7 @@
 
 module NRSER::RSpex::ExampleGroup
   
-  # @todo Document describe_method method.
+  # Describe a method of the parent subject.
   # 
   # @return [void]
   # 
@@ -23,11 +23,32 @@ module NRSER::RSpex::ExampleGroup
       '.'
     end
     
+    method = if self.try( :metadata )
+      getter = if self.metadata.key?( :constructor_args )
+        :instance_method
+      else
+        :method
+      end
+      
+      target = self.metadata[:class] || self.metadata[:module]
+      
+      if target
+        begin
+          target.public_send getter, method_name
+        rescue
+          nil
+        end
+      end
+    end
+    
     name_string = NRSER::RSpex::Format.md_code_quote \
       "#{ name_prefix }#{ method_name }"
     
     # Create the RSpec example group context
-    describe_x name_string, *description,
+    describe_x \
+      name_string,
+      NRSER::Meta::Source::Location.new( method ),
+      *description,
       type: :method,
       metadata: {
         **metadata,

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

@@ -0,0 +1,19 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module NRSER::RSpex::ExampleGroup
+  
+  def describe_module mod, bind_subject: true, **metadata, &body
+    describe_x \
+      mod,
+      type: :module,
+      metadata: {
+        module: mod,
+        **metadata,
+      },
+      bind_subject: bind_subject,
+      subject_block: -> { mod },
+      &body
+  end # #describe_module
+  
+end # module NRSER::RSpex::ExampleGroup

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

@@ -0,0 +1,32 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module NRSER::RSpex::ExampleGroup
+  
+  # Describe the response of the subject to a {NRSER::Message}.
+  # 
+  # Pretty much a short-cut for nesting {#describe_method} /
+  # {#describe_called_with}. Meh.
+  # 
+  # @param [Array] *args
+  #   Passed to {NRSER::Message.from} to get or create the message instance.
+  # 
+  # @param &body          (see #describe_x)
+  # 
+  # @return (see #describe_x)
+  # 
+  def describe_response_to *args, &body
+    msg = NRSER::Message.from *args
+    
+    # Pass up to {#describe_x}
+    describe_x \
+      msg,
+      type: :response_to,
+      subject_block: -> { msg.send_to super() },
+      &body
+  end # #describe_response_to
+  
+  # Old name
+  alias_method :describe_return_value, :describe_response_to
+  
+end # module NRSER::RSpex::ExampleGroup

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

@@ -0,0 +1,38 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module NRSER::RSpex::ExampleGroup
+  
+  # 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 *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}.
+  #   
+  # @param &body (see #describe_x)
+  # 
+  # @return (see #describe_x)
+  # 
+  def describe_section *description, **metadata, &body
+    # Pass up to {#describe_x}
+    describe_x \
+      *description,
+      type: :section,
+      metadata: metadata,
+      &body
+  end # #describe_section
+  
+  # Old name
+  alias_method :describe_topic, :describe_section
+  
+end # module NRSER::RSpex::ExampleGroup

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

@@ -0,0 +1,52 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module NRSER::RSpex::ExampleGroup
+  
+  # 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.
+  #   
+  #   If it's a {Wrapper} it will be unwrapped in example contexts of the
+  #   new example group.
+  # 
+  # @param [Boolean] publicly:
+  #   Send message publicly via {Object#public_send} (default) or privately
+  #   via {Object.send}.
+  # 
+  # @param bind_subject:  (see #describe_x)
+  # @param &body          (see #describe_x)
+  # 
+  # @return (see #describe_x)
+  # 
+  def describe_sent_to  receiver,
+                        publicly: true,
+                        bind_subject: true,
+                        &body
+    mode = if publicly
+      "publicly"
+    else
+      "privately"
+    end
+    
+    describe_x \
+      receiver,
+      "(#{ mode })",
+      type: :sent_to,
+      bind_subject: bind_subject,
+      subject_block: -> {
+        super().send_to \
+          unwrap( receiver, context: self ),
+          publicly: publicly
+      },
+      &body
+  end # #describe_sent_to
+  
+  # Aliases to other names I was using at first... not preferring their use
+  # at the moment.
+  alias_method :sent_to, :describe_sent_to
+  
+end # module NRSER::RSpex::ExampleGroup