naught 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 429858c6dc05004904b5c95c8e536587996175fb
-  data.tar.gz: 06ac8cf2ac0868e8b9d12d9cc15ee2c93c30428d
+SHA256:
+  metadata.gz: 8e5ec51ba30d9f41f50f07369961f3a1442339734bb90be85b38a0bc839a6465
+  data.tar.gz: e481b3466ca2ec4c4f48e2cfd37d171f27988d27ec94bb576477ddc3fa6052c0
 SHA512:
-  metadata.gz: 53cc9f5fc1b17d678163f02c7d61e967895a21afb01a93bcddc68963654e036051cfd303eb492f11da7d1b6e67508ccaf8ebe40ee2b45ec0d3884cec11ce123f
-  data.tar.gz: 1bb2ba430a1be17b50394c2ea2f3e035fec669d4b014c61726cfad653f55c1f42217534d1f920bd9d9cb62096ebb574abe8da0f8017e86d6739a5accb1579277
+  metadata.gz: 750f5fcec8d8e344cb17023544d16da82b6358fcf9b557766edb403657ad60cd2cdb015f704d3acc4f7d2a4ed44625b2487e9fab83840f1d0e6e4ab57b340d49
+  data.tar.gz: 3665ffd61394d8ff066aea5702db37eff96d18d49c66783b35d9efd0842860fd6417c6129589c8b349166ebdaa7c144f32a819c0ba7c389a0696049d8a39e4e4

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013 Avdi Grimm
+Copyright (c) 2013-2026 Avdi Grimm, Erik Berlin
 
 MIT License
 

data/lib/naught/basic_object.rb

@@ -1,17 +1,7 @@
 module Naught
-  if defined? ::BasicObject
-    class BasicObject < ::BasicObject
-    end
-  else
-    class BasicObject #:nodoc:
-      keep = %w(
-        ! != == __id__ __send__ equal? instance_eval instance_exec
-        method_missing singleton_method_added singleton_method_removed
-        singleton_method_undefined
-      )
-      instance_methods.each do |method_name|
-        undef_method(method_name) unless keep.include?(method_name)
-      end
-    end
+  # BasicObject subclass used as a minimal base for null objects
+  #
+  # @api private
+  class BasicObject < ::BasicObject
   end
 end

data/lib/naught/call_location.rb

@@ -0,0 +1,131 @@
+module Naught
+  # Represents a single method call in a null object's call trace
+  #
+  # This class provides an interface similar to Thread::Backtrace::Location,
+  # capturing information about where a method was called on a null object.
+  #
+  # @api public
+  class CallLocation
+    # Create a CallLocation from a caller string
+    #
+    # @param method_name [Symbol, String] the method that was called
+    # @param args [Array<Object>] arguments passed to the method
+    # @param caller_string [String, nil] a single entry from Kernel.caller
+    # @return [CallLocation]
+    # @api private
+    def self.from_caller(method_name, args, caller_string)
+      data = CallerInfo.parse(caller_string || "")
+      new(
+        label: method_name,
+        args: args,
+        path: data[:path] || "",
+        lineno: data[:lineno],
+        base_label: data[:base_label]
+      )
+    end
+
+    # The name of the method that was called
+    #
+    # @return [String] the name of the method that was called
+    # @example
+    #   location.label #=> "foo"
+    attr_reader :label
+
+    # Arguments passed to the method call
+    #
+    # @return [Array<Object>] arguments passed to the method call
+    # @example
+    #   location.args #=> [1, 2, 3]
+    attr_reader :args
+
+    # The absolute path to the file where the call originated
+    #
+    # @return [String] the absolute path to the file where the call originated
+    # @example
+    #   location.path #=> "/path/to/file.rb"
+    attr_reader :path
+
+    # @!method absolute_path
+    #   Returns the absolute path (alias for {#path})
+    #   @return [String] the absolute path to the file
+    #   @example
+    #     location.absolute_path #=> "/path/to/file.rb"
+    alias_method :absolute_path, :path
+
+    # The line number where the call originated
+    #
+    # @return [Integer] the line number where the call originated
+    # @example
+    #   location.lineno #=> 42
+    attr_reader :lineno
+
+    # The name of the method that made the call
+    #
+    # @return [String, nil] the name of the method that made the call
+    # @example
+    #   location.base_label #=> "some_method"
+    attr_reader :base_label
+
+    # Initialize a new CallLocation
+    #
+    # @param label [Symbol, String] the method that was called
+    # @param args [Array<Object>] arguments passed to the method
+    # @param path [String] path to the file where the call originated
+    # @param lineno [Integer] line number where the call originated
+    # @param base_label [String, nil] name of the method that made the call
+    # @api private
+    def initialize(label:, args:, path:, lineno:, base_label: nil)
+      @label = label.to_s
+      @args = args.dup.freeze
+      @path = path
+      @lineno = lineno
+      @base_label = base_label
+    end
+
+    # Returns a human-readable string representation of the call
+    #
+    # @return [String] string representation
+    # @example
+    #   location.to_s #=> "/path/to/file.rb:42:in `method' -> foo(1, 2)"
+    def to_s
+      pretty_args = args.map(&:inspect).join(", ")
+      location = base_label ? "#{path}:#{lineno}:in `#{base_label}'" : "#{path}:#{lineno}"
+      "#{location} -> #{label}(#{pretty_args})"
+    end
+
+    # Returns a detailed inspect representation
+    #
+    # @return [String] inspect representation
+    # @example
+    #   location.inspect #=> "#<Naught::CallLocation /path/to/file.rb:42 -> foo(1)>"
+    def inspect = "#<#{self.class} #{self}>"
+
+    # Compare this CallLocation with another for equality
+    #
+    # @param other [CallLocation] the object to compare with
+    # @return [Boolean] true if all attributes match
+    # @example
+    #   location1 == location2 #=> true
+    def ==(other)
+      other.is_a?(CallLocation) &&
+        label == other.label &&
+        args == other.args &&
+        path == other.path &&
+        lineno == other.lineno &&
+        base_label == other.base_label
+    end
+    # @!method eql?
+    #   Compare for equality (alias for {#==})
+    #   @return [Boolean] true if all attributes match
+    #   @example
+    #     location1.eql?(location2) #=> true
+    alias_method :eql?, :==
+
+    # Compute a hash value for this CallLocation
+    #
+    # @return [Integer] hash value based on all attributes
+    # @example
+    #   location.hash #=> 123456789
+    def hash = [label, args, path, lineno, base_label].hash
+  end
+end

data/lib/naught/caller_info.rb

@@ -0,0 +1,128 @@
+module Naught
+  # Utility for parsing Ruby caller/backtrace information
+  #
+  # Extracts structured information from caller strings like:
+  #   "/path/to/file.rb:42:in `method_name'"
+  #   "/path/to/file.rb:42:in `block in method_name'"
+  #   "/path/to/file.rb:42:in `block (2 levels) in method_name'"
+  #
+  # @api private
+  module CallerInfo
+    # Pattern matching quoted method signature in caller strings
+    # Matches both backticks and single quotes for cross-Ruby compatibility
+    SIGNATURE_PATTERN = /['`](?<signature>[^'`]+)['`]$/
+    private_constant :SIGNATURE_PATTERN
+
+    module_function
+
+    # Parse a caller string into structured components
+    #
+    # @param caller_string [String] a single entry from Kernel.caller
+    # @return [Hash] parsed components with keys :path, :lineno, :base_label
+    def parse(caller_string)
+      path, lineno, method_part = caller_string.to_s.split(":", 3)
+      {
+        path: path,
+        lineno: lineno.to_i,
+        base_label: extract_base_label(method_part)
+      }
+    end
+
+    # Format caller information for display in pebble output
+    #
+    # Handles nested block detection by examining the call stack.
+    #
+    # @param stack [Array<String>] the call stack from Kernel.caller
+    # @return [String] formatted caller description
+    def format_caller_for_pebble(stack)
+      caller_line = stack.first
+      signature = extract_signature(caller_line.split(":", 3)[2])
+      return caller_line unless signature
+
+      block_info, method_name = parse_signature(signature)
+      block_info = adjusted_block_info(block_info, stack, method_name)
+
+      block_info ? "#{block_info} #{method_name}" : method_name
+    end
+
+    # Extract the base method name from the method part of a caller string
+    #
+    # @param method_part [String, nil] the third component after splitting on ":"
+    # @return [String, nil] the extracted method name
+    def extract_base_label(method_part)
+      signature = extract_signature(method_part)
+      return nil unless signature
+
+      _block_info, method_name = parse_signature(signature)
+      method_name
+    end
+
+    # Extract the full method signature including block info
+    #
+    # @param method_part [String, nil] the third component after splitting on ":"
+    # @return [String, nil] the full signature
+    def extract_signature(method_part)
+      method_part&.match(SIGNATURE_PATTERN)&.[](:signature)
+    end
+
+    # Split a signature into block info and base method name
+    #
+    # @param signature [String] the method signature
+    # @return [Array(String, String), Array(nil, String)] [block_info, method_name]
+    def split_signature(signature)
+      signature.include?(" in ") ? signature.split(" in ", 2) : [nil, signature]
+    end
+
+    # Count nested block levels in the call stack
+    #
+    # @param stack [Array<String>] the call stack
+    # @param target_method [String] the method name to look for
+    # @return [Integer] the number of nested block levels
+    def count_block_levels(stack, target_method)
+      stack.reduce(0) do |levels, entry|
+        signature = extract_signature(entry.split(":", 3)[2])
+        break levels unless signature
+
+        block_info, method_name = parse_signature(signature)
+
+        if method_name == target_method
+          block_info&.start_with?("block") ? levels + 1 : (break levels)
+        else
+          levels
+        end
+      end
+    end
+
+    # Parse a signature into block info and clean method name
+    #
+    # @param signature [String] the method signature
+    # @return [Array(String, String), Array(nil, String)] [block_info, method_name]
+    def parse_signature(signature)
+      block_info, method_part = split_signature(signature)
+      method_name = method_part.split(/[#.]/).last
+      [block_info, method_name]
+    end
+
+    # Adjust block info to show nested levels if applicable
+    #
+    # @param block_info [String, nil] current block info
+    # @param stack [Array<String>] the call stack
+    # @param method_name [String] the method name to look for
+    # @return [String, nil] adjusted block info
+    def adjusted_block_info(block_info, stack, method_name)
+      return block_info unless simple_block?(block_info)
+
+      levels = count_block_levels(stack, method_name)
+      (levels > 1) ? "block (#{levels} levels)" : block_info
+    end
+
+    # Check if block_info is a simple "block" without level info
+    #
+    # @param block_info [String, nil]
+    # @return [Boolean]
+    def simple_block?(block_info)
+      block_info&.start_with?("block") && !block_info.include?("levels")
+    end
+    private :parse_signature, :adjusted_block_info, :simple_block?
+  end
+end

data/lib/naught/chain_proxy.rb

@@ -0,0 +1,51 @@
+require "naught/basic_object"
+
+module Naught
+  # Lightweight proxy for tracking chained method calls
+  #
+  # Used by the callstack feature to group chained method calls
+  # (e.g., `null.foo.bar.baz`) into a single trace while keeping
+  # separate calls (e.g., `null.foo; null.bar`) in separate traces.
+  #
+  # @api private
+  class ChainProxy < BasicObject
+    # Create a new ChainProxy
+    #
+    # @param root [Object] the original null object being tracked
+    # @param current_trace [Array<CallLocation>] the trace to append calls to
+    def initialize(root, current_trace)
+      @root = root
+      @current_trace = current_trace
+    end
+
+    # Handle method calls by recording them and returning self for chaining
+    #
+    # @param method_name [Symbol] the method being called
+    # @param args [Array] arguments passed to the method
+    # @return [ChainProxy] self for method chaining
+    # rubocop:disable Style/MissingRespondToMissing -- BasicObject doesn't use respond_to_missing?
+    def method_missing(method_name, *args)
+      location = ::Naught::CallLocation.from_caller(
+        method_name, args, ::Kernel.caller(1, 1).first
+      )
+      @current_trace << location
+      self
+    end
+    # rubocop:enable Style/MissingRespondToMissing
+
+    # Check if the proxy responds to a method
+    #
+    # @return [true] chain proxies respond to any method
+    def respond_to?(*, **) = true
+
+    # Return a string representation of the proxy
+    #
+    # @return [String] a simple representation of the proxy
+    def inspect = "<null:chain>"
+
+    # Return the class of the root null object
+    #
+    # @return [Class] the class of the root null object
+    def class = @root.class
+  end
+end

data/lib/naught/conversions.rb

@@ -1,55 +1,129 @@
 module Naught
+  # Helper conversion API available on generated null classes
+  #
+  # This module is designed to be configured per null class via
+  # {Conversions.configure}. Each generated null class gets its
+  # own configured version of these conversion functions.
+  #
+  # @api public
   module Conversions
-    def self.included(null_class)
-      unless class_variable_defined?(:@@included) && @@included
-        @@null_class = null_class
-        @@null_equivs = null_class::NULL_EQUIVS
-        @@included = true
+    # Sentinel value for no argument passed
+    NOTHING_PASSED = Object.new.freeze
+    private_constant :NOTHING_PASSED
+
+    class << self
+      # Configure a Conversions module for a specific null class
+      #
+      # @param mod [Module] module to configure
+      # @param null_class [Class] the generated null class
+      # @param null_equivs [Array] values treated as null-equivalent
+      # @return [void]
+      # @api private
+      def configure(mod, null_class:, null_equivs:)
+        mod.define_method(:__null_class__) { null_class }
+        mod.define_method(:__null_equivs__) { null_equivs }
+        mod.send(:private, :__null_class__, :__null_equivs__)
       end
-      super
     end
 
-    def Null(object = :nothing_passed)
-      case object
-      when NullObjectTag
-        object
-      when :nothing_passed, *@@null_equivs
-        @@null_class.get(:caller => caller(1))
-      else
-        fail(ArgumentError.new("#{object.inspect} is not null!"))
-      end
+    # Return a null object for +object+ if it is null-equivalent
+    #
+    # @example
+    #   include MyNullObject::Conversions
+    #   Null()       #=> <null>
+    #   Null(nil)    #=> <null>
+    #
+    # @param object [Object] candidate object
+    # @return [Object] a null object
+    # @raise [ArgumentError] if +object+ is not null-equivalent
+    def Null(object = NOTHING_PASSED)
+      return object if null_object?(object)
+      return make_null(1) if null_equivalent?(object, include_nothing: true)
+
+      raise ArgumentError, "Null() requires a null-equivalent value, " \
+                           "got #{object.class}: #{object.inspect}"
     end
 
+    # Return a null object for null-equivalent values, otherwise the value
+    #
+    # @example
+    #   Maybe(nil)        #=> <null>
+    #   Maybe("hello")    #=> "hello"
+    #
+    # @param object [Object] candidate object
+    # @yieldreturn [Object] optional lazy value
+    # @return [Object] null object or original value
     def Maybe(object = nil)
       object = yield if block_given?
-      case object
-      when NullObjectTag
-        object
-      when *@@null_equivs
-        @@null_class.get(:caller => caller(1))
-      else
-        object
-      end
+      return object if null_object?(object)
+      return make_null(1) if null_equivalent?(object)
+
+      object
     end
 
+    # Return the value if not null-equivalent, otherwise raise
+    #
+    # @example
+    #   Just("hello")  #=> "hello"
+    #   Just(nil)      # raises ArgumentError
+    #
+    # @param object [Object] candidate object
+    # @yieldreturn [Object] optional lazy value
+    # @return [Object] original value
+    # @raise [ArgumentError] if value is null-equivalent
     def Just(object = nil)
       object = yield if block_given?
-      case object
-      when NullObjectTag, *@@null_equivs
-        fail(ArgumentError.new("Null value: #{object.inspect}"))
-      else
-        object
+      if null_object?(object) || null_equivalent?(object)
+        raise ArgumentError, "Just() requires a non-null value, got: #{object.inspect}"
       end
+
+      object
     end
 
+    # Return +nil+ for null objects, otherwise return the value
+    #
+    # @example
+    #   Actual(null)     #=> nil
+    #   Actual("hello")  #=> "hello"
+    #
+    # @param object [Object] candidate object
+    # @yieldreturn [Object] optional lazy value
+    # @return [Object, nil] actual value or nil
     def Actual(object = nil)
       object = yield if block_given?
-      case object
-      when NullObjectTag
-        nil
-      else
-        object
-      end
+      null_object?(object) ? nil : object
+    end
+
+    private
+
+    # Check if an object is a null object
+    #
+    # @param object [Object] the object to check
+    # @return [Boolean] true if the object is a null object
+    # @api private
+    def null_object?(object)
+      NullObjectTag === object
+    end
+
+    # Check if an object is null-equivalent (nil or custom null equivalents)
+    #
+    # @param object [Object] the object to check
+    # @param include_nothing [Boolean] whether to treat NOTHING_PASSED as null-equivalent
+    # @return [Boolean] true if the object is null-equivalent
+    # @api private
+    def null_equivalent?(object, include_nothing: false)
+      return true if include_nothing && object == NOTHING_PASSED
+
+      __null_equivs__.any? { |equiv| equiv === object }
+    end
+
+    # Create a new null object instance
+    #
+    # @param caller_offset [Integer] additional stack frames to skip
+    # @return [Object] a new null object
+    # @api private
+    def make_null(caller_offset)
+      __null_class__.get(caller: caller(caller_offset + 1))
     end
   end
 end

data/lib/naught/null_class_builder/command.rb

@@ -1,19 +1,57 @@
 module Naught
   class NullClassBuilder
+    # Base class for builder command implementations
+    #
+    # @api private
     class Command
+      # Builder instance for this command
+      # @return [NullClassBuilder]
+      # @api private
       attr_reader :builder
 
+      # Create a command bound to a builder
+      #
+      # @param builder [NullClassBuilder]
+      # @return [void]
+      # @api private
       def initialize(builder)
         @builder = builder
       end
 
+      # Execute the command
+      #
+      # @raise [NotImplementedError] when not overridden
+      # @return [void]
+      # @api private
       def call
-        fail(NotImplementedError.new('Method #call should be overriden in child classes'))
+        raise NotImplementedError, "Method #call should be overridden in child classes"
       end
 
-      def defer(options = {}, &block)
-        @builder.defer(options, &block)
-      end
+      private
+
+      # Delegate a deferred operation to the builder
+      #
+      # @param options [Hash] operation options
+      # @yieldparam subject [Module, Class]
+      # @yieldreturn [void]
+      # @return [void]
+      # @api private
+      def defer(options = {}, &) = builder.defer(options, &)
+
+      # Delegate a deferred class operation to the builder
+      #
+      # @yieldparam subject [Class]
+      # @yieldreturn [void]
+      # @return [void]
+      # @api private
+      def defer_class(&) = builder.defer(class: true, &)
+
+      # Delegate a prepend module operation to the builder
+      #
+      # @yieldreturn [void]
+      # @return [void]
+      # @api private
+      def defer_prepend_module(&) = builder.defer_prepend_module(&)
     end
   end
 end

data/lib/naught/null_class_builder/commands/callstack.rb

@@ -0,0 +1,89 @@
+require "naught/null_class_builder/command"
+require "naught/call_location"
+require "naught/chain_proxy"
+
+module Naught
+  class NullClassBuilder
+    module Commands
+      # Records method calls made on null objects for debugging
+      #
+      # When enabled, each null object instance tracks all method calls made to it,
+      # including the method name, arguments, and source location. Calls are grouped
+      # into "traces" - each time a method is called directly on the original null
+      # object (rather than on a chained result), a new trace begins.
+      #
+      # This uses lightweight proxy objects for chaining so that we can distinguish
+      # between `null.foo.bar` (one trace with two calls) and `null.foo; null.bar`
+      # (two traces with one call each).
+      #
+      # @example Basic usage
+      #   NullObject = Naught.build do |config|
+      #     config.callstack
+      #   end
+      #
+      #   null = NullObject.new
+      #   null.foo(1, 2).bar
+      #   null.baz
+      #
+      #   null.__call_trace__
+      #   # => [
+      #   #      [#<Naught::CallLocation foo(1, 2) at example.rb:8>,
+      #   #       #<Naught::CallLocation bar() at example.rb:8>],
+      #   #      [#<Naught::CallLocation baz() at example.rb:9>]
+      #   #    ]
+      #
+      # @api private
+      class Callstack < Command
+        # Install the callstack tracking mechanism
+        # @return [void]
+        # @api private
+        def call
+          install_call_trace_accessor
+          install_method_missing_tracking
+          install_chain_proxy_class
+        end
+
+        private
+
+        # Install the __call_trace__ accessor on null objects
+        # @return [void]
+        # @api private
+        def install_call_trace_accessor
+          defer_prepend_module do
+            attr_reader :__call_trace__
+
+            define_method(:initialize) do |*args, **kwargs|
+              super(*args, **kwargs)
+              @__call_trace__ = [] #: Array[Array[Naught::CallLocation]]
+            end
+          end
+        end
+
+        # Install method_missing override that records calls
+        # @return [void]
+        # @api private
+        def install_method_missing_tracking
+          defer_prepend_module do
+            define_method(:respond_to?) do |method_name, include_private = false|
+              method_name == :__call_trace__ || super(method_name, include_private)
+            end
+
+            define_method(:method_missing) do |method_name, *args, &block|
+              location = Naught::CallLocation.from_caller(method_name, args, Kernel.caller(1, 1).first)
+              @__call_trace__ ||= [] #: Array[Array[Naught::CallLocation]]
+              @__call_trace__ << [location]
+              Naught::ChainProxy.new(self, @__call_trace__.last)
+            end
+          end
+        end
+
+        # Install the ChainProxy class constant for backwards compatibility
+        # @return [void]
+        # @api private
+        def install_chain_proxy_class
+          defer_class { |null_class| null_class.const_set(:ChainProxy, Naught::ChainProxy) }
+        end
+      end
+    end
+  end
+end