naught 1.1.0 → 2.0.0

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

@@ -1,17 +1,29 @@
-require 'forwardable'
-require 'naught/null_class_builder/command'
+require "naught/null_class_builder/command"
 
 module Naught
   class NullClassBuilder
     module Commands
-      class DefineExplicitConversions < ::Naught::NullClassBuilder::Command
+      # Adds explicit conversion methods delegating to nil
+      #
+      # These methods return the same values that nil returns:
+      # - to_a => []
+      # - to_c => (0+0i)
+      # - to_f => 0.0
+      # - to_h => {}
+      # - to_i => 0
+      # - to_r => (0/1)
+      # - to_s => ""
+      #
+      # @api private
+      class DefineExplicitConversions < Command
+        METHODS = %i[to_a to_c to_f to_h to_i to_r to_s].freeze
+        private_constant :METHODS
+
+        # Install explicit conversion methods
+        # @return [void]
+        # @api private
         def call
-          defer do |subject|
-            subject.module_eval do
-              extend Forwardable
-              def_delegators :nil, :to_a, :to_c, :to_f, :to_h, :to_i, :to_r, :to_s
-            end
-          end
+          defer { |subject| METHODS.each { |name| subject.define_method(name) { nil.public_send(name) } } }
         end
       end
     end

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

@@ -1,29 +1,27 @@
-require 'naught/null_class_builder/command'
+require "naught/null_class_builder/command"
 
 module Naught
   class NullClassBuilder
     module Commands
-      class DefineImplicitConversions < ::Naught::NullClassBuilder::Command
-        def call
-          defer do |subject|
-            subject.module_eval do
-              def to_ary
-                []
-              end
-
-              def to_hash
-                {}
-              end
+      # Adds implicit conversion methods to the null class
+      #
+      # @api private
+      class DefineImplicitConversions < Command
+        EMPTY_ARRAY = [] #: Array[untyped]
+        EMPTY_HASH = {} #: Hash[untyped, untyped]
+        RETURN_VALUES = {
+          to_ary: EMPTY_ARRAY.freeze,
+          to_hash: EMPTY_HASH.freeze,
+          to_int: 0,
+          to_str: "".freeze
+        }.freeze
+        private_constant :EMPTY_ARRAY, :EMPTY_HASH, :RETURN_VALUES
 
-              def to_int
-                0
-              end
-
-              def to_str
-                ''
-              end
-            end
-          end
+        # Install implicit conversion methods
+        # @return [void]
+        # @api private
+        def call
+          defer { |subject| RETURN_VALUES.each { |name, value| subject.define_method(name) { value } } }
         end
       end
     end

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

@@ -1,7 +1,19 @@
 module Naught
   class NullClassBuilder
     module Commands
-      class Impersonate < Naught::NullClassBuilder::Commands::Mimic
+      # Build a null class that impersonates a given class
+      #
+      # Unlike Mimic, Impersonate makes the null class inherit from the target,
+      # so `is_a?` checks will pass.
+      #
+      # @api private
+      class Impersonate < Mimic
+        # Create an impersonate command for a class
+        #
+        # @param builder [NullClassBuilder]
+        # @param class_to_impersonate [Class]
+        # @param options [Hash]
+        # @api private
         def initialize(builder, class_to_impersonate, options = {})
           super
           builder.base_class = class_to_impersonate

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

@@ -1,53 +1,97 @@
-require 'naught/basic_object'
-require 'naught/null_class_builder/command'
+require "naught/basic_object"
+require "naught/null_class_builder/command"
 
 module Naught
   class NullClassBuilder
     module Commands
-      class Mimic < Naught::NullClassBuilder::Command
-        NULL_SINGLETON_CLASS = (class << Object.new; self; end)
+      # Build a null class that mimics an existing class or instance
+      #
+      # @api private
+      class Mimic < Command
+        # Methods that should never be mimicked as they interfere with
+        # other Naught features like predicates_return
+        # @see https://github.com/avdi/naught/issues/55
+        METHODS_TO_SKIP = (%i[method_missing respond_to? respond_to_missing?] + Object.instance_methods).freeze
+        private_constant :METHODS_TO_SKIP
 
-        attr_reader :class_to_mimic, :include_super, :singleton_class
+        # Singleton class placeholder used when no instance is provided
+        NULL_SINGLETON_CLASS = Object.new.singleton_class.freeze
+        private_constant :NULL_SINGLETON_CLASS
 
+        # The class being mimicked by the null object
+        # @return [Class] class being mimicked
+        attr_reader :class_to_mimic
+
+        # Whether to include superclass methods when mimicking
+        # @return [Boolean] whether to include superclass methods
+        attr_reader :include_super
+
+        # The singleton class being mimicked (for instance-based mimicking)
+        # @return [Class] singleton class being mimicked
+        attr_reader :singleton_class
+
+        # Create a mimic command for a class or instance
+        #
+        # @param builder [NullClassBuilder]
+        # @param class_to_mimic_or_options [Class, Hash]
+        # @param options [Hash]
+        # @api private
         def initialize(builder, class_to_mimic_or_options, options = {})
           super(builder)
+          parse_arguments(class_to_mimic_or_options, options)
+          configure_builder
+        end
+
+        # Install stubbed methods from the target class or instance
+        #
+        # @return [void]
+        # @api private
+        def call
+          defer { |subject| methods_to_stub.each { |name| builder.stub_method(subject, name) } }
+        end
+
+        private
 
+        # Parse the arguments to determine what to mimic
+        #
+        # @param class_to_mimic_or_options [Class, Hash] class or options hash
+        # @param options [Hash] additional options
+        # @return [void]
+        def parse_arguments(class_to_mimic_or_options, options)
           if class_to_mimic_or_options.is_a?(Hash)
-            options          = class_to_mimic_or_options.merge(options)
-            instance         = options.fetch(:example)
-            @singleton_class = (class << instance; self; end)
-            @class_to_mimic  = instance.class
+            options = class_to_mimic_or_options.merge(options)
+            instance = options.fetch(:example)
+            @singleton_class = instance.singleton_class
+            @class_to_mimic = instance.class
           else
             @singleton_class = NULL_SINGLETON_CLASS
-            @class_to_mimic  = class_to_mimic_or_options
+            @class_to_mimic = class_to_mimic_or_options
           end
-          @include_super = options.fetch(:include_super) { true }
-
-          builder.base_class   = root_class_of(@class_to_mimic)
-          class_to_mimic       = @class_to_mimic
-          builder.inspect_proc = lambda { "<null:#{class_to_mimic}>" }
-          builder.interface_defined = true
+          @include_super = options.fetch(:include_super, true)
         end
 
-        def call
-          defer do |subject|
-            methods_to_stub.each do |method_name|
-              builder.stub_method(subject, method_name)
-            end
-          end
+        # Configure the builder with the mimicked class's properties
+        #
+        # @return [void]
+        def configure_builder
+          builder.base_class = root_class_of(class_to_mimic)
+          klass = class_to_mimic
+          builder.inspect_proc = -> { "<null:#{klass}>" }
+          builder.interface_defined = true
         end
 
-      private
-
-        def root_class_of(klass)
-          klass.ancestors.include?(Object) ? Object : Naught::BasicObject
-        end
+        # Determine the root class to inherit from
+        #
+        # @param klass [Class] the class to analyze
+        # @return [Class] Object or Naught::BasicObject
+        def root_class_of(klass) = klass.ancestors.include?(Object) ? Object : Naught::BasicObject
 
+        # Compute the list of methods to stub on the null object
+        #
+        # @return [Array<Symbol>] methods to stub
         def methods_to_stub
-          methods_to_mimic =
-            class_to_mimic.instance_methods(include_super) |
-            singleton_class.instance_methods(false)
-          methods_to_mimic - Object.instance_methods
+          all_methods = class_to_mimic.instance_methods(include_super) | singleton_class.instance_methods(false)
+          all_methods - METHODS_TO_SKIP
         end
       end
     end

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

@@ -0,0 +1,92 @@
+require "naught/null_class_builder/command"
+
+module Naught
+  class NullClassBuilder
+    module Commands
+      # Enables null-safe proxy wrapping via the NullSafe() conversion function
+      #
+      # When enabled, the generated null class gains a NullSafe() function that
+      # wraps any value in a proxy. The proxy intercepts all method calls and
+      # wraps return values, replacing nil with the null object.
+      #
+      # @example Enable null-safe proxy
+      #   NullObject = Naught.build do |config|
+      #     config.null_safe_proxy
+      #   end
+      #
+      #   include NullObject::Conversions
+      #
+      #   user = nil
+      #   NullSafe(user).name.upcase      # => <null>
+      #
+      #   user = OpenStruct.new(name: nil)
+      #   NullSafe(user).name.upcase      # => <null>
+      #
+      #   user = OpenStruct.new(name: "Bob")
+      #   NullSafe(user).name.upcase      # => "BOB"
+      #
+      # @api private
+      class NullSafeProxy < Command
+        # Install the NullSafe conversion function
+        # @return [void]
+        # @api private
+        def call
+          null_equivs = builder.null_equivalents
+          defer_class do |null_class|
+            proxy_class = build_proxy_class(null_class, null_equivs)
+            null_class.const_set(:NullSafeProxy, proxy_class)
+            install_null_safe_conversion(null_class, proxy_class, null_equivs)
+          end
+        end
+
+        private
+
+        # Build the proxy class that wraps objects for null-safe access
+        #
+        # @param null_class [Class] the null object class
+        # @param null_equivs [Array<Object>] values treated as null-equivalent
+        # @return [Class] the proxy class
+        # @api private
+        def build_proxy_class(null_class, null_equivs)
+          Class.new(::Naught::BasicObject) do
+            include ::Naught::NullSafeProxyTag
+
+            define_method(:initialize) { |target| @target = target }
+            define_method(:__target__) { @target }
+            define_method(:respond_to?) { |method_name, include_private = false| @target.respond_to?(method_name, include_private) }
+            define_method(:inspect) { "<null-safe-proxy(#{@target.inspect})>" }
+
+            define_method(:method_missing) do |method_name, *args, &block|
+              result = @target.__send__(method_name, *args, &block)
+              case result
+              when ::Naught::NullObjectTag then result
+              when *null_equivs then null_class.get
+              else self.class.new(result)
+              end
+            end
+
+            klass = self
+            define_method(:class) { klass }
+          end
+        end
+
+        # Install the NullSafe conversion method on the Conversions module
+        #
+        # @param null_class [Class] the null object class
+        # @param proxy_class [Class] the proxy class
+        # @param null_equivs [Array<Object>] values treated as null-equivalent
+        # @return [void]
+        # @api private
+        def install_null_safe_conversion(null_class, proxy_class, null_equivs)
+          null_class.const_get(:Conversions).define_method(:NullSafe) do |object|
+            case object
+            when ::Naught::NullObjectTag then object
+            when *null_equivs then null_class.get
+            else proxy_class.new(object)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,29 +1,33 @@
-require 'naught/null_class_builder/command'
+require "naught/null_class_builder/command"
 
 module Naught
   class NullClassBuilder
     module Commands
-      class Pebble < ::Naught::NullClassBuilder::Command
+      # Logs missing method calls and their call sites
+      #
+      # @api private
+      class Pebble < Command
+        # Create a pebble command with optional output stream
+        #
+        # @param builder [NullClassBuilder]
+        # @param output [#puts] output stream for log lines
+        # @api private
         def initialize(builder, output = $stdout)
-          @builder = builder
+          super(builder)
           @output = output
         end
 
+        # Install the logging method_missing hook
+        # @return [void]
+        # @api private
         def call
-          defer do |subject|
-            subject.module_exec(@output) do |output|
-              define_method(:method_missing) do |method_name, *args|
-                pretty_args = args.collect(&:inspect).join(', ').tr("\"", "'")
-                output.puts "#{method_name}(#{pretty_args}) from #{parse_caller}"
-                self
-              end
-
-              def parse_caller
-                caller = Kernel.caller(2).first
-                method_name = caller.match(/\`([\w\s]+(\(\d+\s\w+\))?[\w\s]*)/)
-                method_name ? method_name[1] : caller
-              end
-              private :parse_caller
+          output = @output
+          defer_prepend_module do
+            define_method(:method_missing) do |method_name, *args|
+              pretty_args = args.map(&:inspect).join(", ").tr('"', "'")
+              caller_desc = Naught::CallerInfo.format_caller_for_pebble(Kernel.caller(1))
+              output.puts "#{method_name}(#{pretty_args}) from #{caller_desc}"
+              self
             end
           end
         end

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

@@ -1,45 +1,63 @@
-require 'naught/null_class_builder/command'
+require "naught/null_class_builder/command"
 
 module Naught
   class NullClassBuilder
     module Commands
-      class PredicatesReturn < Naught::NullClassBuilder::Command
+      # Overrides predicate methods to return a fixed value
+      #
+      # @api private
+      class PredicatesReturn < Command
+        # Create a predicates_return command with the given value
+        #
+        # @param builder [NullClassBuilder]
+        # @param return_value [Object] value to return for predicate methods
+        # @api private
         def initialize(builder, return_value)
           super(builder)
-          @predicate_return_value = return_value
+          @return_value = return_value
         end
 
+        # Apply predicate overrides
+        # @return [void]
+        # @api private
         def call
-          defer do |subject|
-            define_method_missing(subject)
-            define_predicate_methods(subject)
-          end
+          install_method_missing_override
+          install_predicate_method_overrides
         end
 
-      private
+        private
 
-        def define_method_missing(subject)
-          subject.module_exec(@predicate_return_value) do |return_value|
-            next unless subject.method_defined?(:method_missing)
-            original_method_missing = instance_method(:method_missing)
+        # Install method_missing override for predicate methods
+        # @return [void]
+        # @api private
+        def install_method_missing_override
+          return_value = @return_value
+          defer_prepend_module do
             define_method(:method_missing) do |method_name, *args, &block|
-              if method_name.to_s.end_with?('?')
-                return_value
-              else
-                original_method_missing.bind(self).call(method_name, *args, &block)
-              end
+              method_name.to_s.end_with?("?") ? return_value : super(method_name, *args, &block)
+            end
+
+            define_method(:respond_to?) do |method_name, include_private = false|
+              method_name.to_s.end_with?("?") || super(method_name, include_private)
             end
           end
         end
 
-        def define_predicate_methods(subject)
-          subject.module_exec(@predicate_return_value) do |return_value|
-            instance_methods.each do |method_name|
-              next unless method_name.to_s.end_with?('?')
-              define_method(method_name) do |*|
-                return_value
-              end
+        # Override existing predicate methods to return the configured value
+        # @return [void]
+        # @api private
+        def install_predicate_method_overrides
+          return_value = @return_value
+          defer do |subject|
+            predicate_methods = subject.instance_methods.select do |name|
+              name.to_s.end_with?("?") && name != :respond_to?
+            end
+            next if predicate_methods.empty?
+
+            predicate_mod = Module.new do
+              predicate_methods.each { |name| define_method(name) { |*| return_value } }
             end
+            subject.prepend(predicate_mod)
           end
         end
       end

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

@@ -1,25 +1,22 @@
-require 'naught/null_class_builder/command'
+require "singleton"
+require "naught/null_class_builder/command"
 
 module Naught
   class NullClassBuilder
     module Commands
-      class Singleton < Naught::NullClassBuilder::Command
+      # Turns the null class into a Singleton
+      #
+      # @api private
+      class Singleton < Command
+        # Install Singleton behavior on the null class
+        # @return [void]
+        # @api private
         def call
-          defer(:class => true) do |subject|
-            require 'singleton'
-            subject.module_eval do
-              include ::Singleton
-
-              def self.get(*)
-                instance
-              end
-
-              %w(dup clone).each do |method_name|
-                define_method method_name do
-                  self
-                end
-              end
-            end
+          defer_class do |klass|
+            klass.include(::Singleton)
+            klass.singleton_class.undef_method(:get)
+            klass.define_singleton_method(:get) { |*| instance }
+            %i[dup clone].each { |name| klass.define_method(name) { self } }
           end
         end
       end

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

@@ -1,20 +1,25 @@
-require 'naught/null_class_builder/command'
+require "naught/null_class_builder/command"
 
 module Naught
   class NullClassBuilder
     module Commands
-      class Traceable < Naught::NullClassBuilder::Command
+      # Records the source location where a null object was created
+      #
+      # @api private
+      class Traceable < Command
+        # Install the traceable initializer
+        # @return [void]
+        # @api private
         def call
-          defer do |subject|
-            subject.module_eval do
-              attr_reader :__file__, :__line__
+          defer_prepend_module do
+            attr_reader :__file__, :__line__
 
-              def initialize(options = {})
-                range = (RUBY_VERSION.to_f == 1.9 && RUBY_PLATFORM != 'java') ? 4 : 3
-                backtrace = options.fetch(:caller) { Kernel.caller(range) }
-                @__file__, line = backtrace[0].split(':')
-                @__line__ = line.to_i
-              end
+            define_method(:initialize) do |options = {}|
+              backtrace = options.fetch(:caller) { Kernel.caller(3) }
+              caller_data = Naught::CallerInfo.parse(backtrace[0])
+              @__file__ = caller_data[:path]
+              @__line__ = caller_data[:lineno]
+              super(options)
             end
           end
         end

data/lib/naught/null_class_builder/commands.rb

@@ -1,8 +1,10 @@
-require 'naught/null_class_builder/commands/define_explicit_conversions'
-require 'naught/null_class_builder/commands/define_implicit_conversions'
-require 'naught/null_class_builder/commands/pebble'
-require 'naught/null_class_builder/commands/predicates_return'
-require 'naught/null_class_builder/commands/singleton'
-require 'naught/null_class_builder/commands/traceable'
-require 'naught/null_class_builder/commands/mimic'
-require 'naught/null_class_builder/commands/impersonate'
+require "naught/null_class_builder/commands/callstack"
+require "naught/null_class_builder/commands/define_explicit_conversions"
+require "naught/null_class_builder/commands/define_implicit_conversions"
+require "naught/null_class_builder/commands/null_safe_proxy"
+require "naught/null_class_builder/commands/pebble"
+require "naught/null_class_builder/commands/predicates_return"
+require "naught/null_class_builder/commands/singleton"
+require "naught/null_class_builder/commands/traceable"
+require "naught/null_class_builder/commands/mimic"
+require "naught/null_class_builder/commands/impersonate"