naught 1.0.0 → 2.0.0

data/lib/naught/null_class_builder.rb

@@ -1,186 +1,283 @@
-require 'naught/basic_object'
-require 'naught/conversions'
+require "naught/basic_object"
+require "naught/conversions"
+require "naught/stub_strategy"
 
 module Naught
+  # Builds customized null object classes via a small DSL
+  #
+  # @api public
   class NullClassBuilder
-    # make sure this module exists
-    module Commands
-    end
+    # Namespace for builder command classes
+    # @api private
+    module Commands; end
+
+    # The base class for generated null objects
+    #
+    # @return [Class] base class for generated null objects
+    # @example
+    #   builder.base_class #=> Naught::BasicObject
+    attr_accessor :base_class
+
+    # The inspect implementation for generated null objects
+    #
+    # @return [Proc] inspect implementation for generated null objects
+    # @example
+    #   builder.inspect_proc.call #=> "<null>"
+    attr_accessor :inspect_proc
 
-    attr_accessor :base_class, :inspect_proc, :interface_defined
+    # Whether a method-missing interface has been defined
+    #
+    # @return [Boolean] whether a method-missing interface has been defined
+    # @example
+    #   builder.interface_defined #=> false
+    attr_accessor :interface_defined
+
+    # @!method interface_defined?
+    #   Check if a method-missing interface has been defined
+    #   @return [Boolean] true if interface is defined
+    #   @example
+    #     builder.interface_defined? #=> false
+    alias_method :interface_defined?, :interface_defined
 
+    # Create a new builder with default configuration
+    # @api private
     def initialize
       @interface_defined = false
-      @base_class        = Naught::BasicObject
-      @inspect_proc      = lambda { '<null>' }
-      @stub_strategy     = :stub_method_returning_nil
+      @base_class = Naught::BasicObject
+      @inspect_proc = -> { "<null>" }
+      @stub_strategy = StubStrategy::ReturnNil
       define_basic_methods
     end
 
-    def interface_defined?
-      !!@interface_defined
-    end
-
-    def customize(&customization_block)
-      return unless customization_block
-      customization_module.module_exec(self, &customization_block)
+    # Apply a customization block to this builder
+    #
+    # @yieldparam builder [NullClassBuilder] builder instance
+    # @return [void]
+    # @example
+    #   builder.customize { |b| b.black_hole }
+    def customize(&)
+      customization_module.module_exec(self, &) if block_given?
     end
 
-    def customization_module
-      @customization_module ||= Module.new
-    end
+    # Returns the module that holds customization methods
+    #
+    # @return [Module] module that holds customization methods
+    # @example
+    #   builder.customization_module #=> #<Module:0x...>
+    def customization_module = @customization_module ||= Module.new
 
-    def null_equivalents
-      @null_equivalents ||= [nil]
-    end
+    # Returns the list of values treated as null-equivalent
+    #
+    # @return [Array<Object>] values treated as null-equivalent
+    # @example
+    #   builder.null_equivalents #=> [nil]
+    def null_equivalents = @null_equivalents ||= [nil]
 
+    # Generate the null object class based on queued operations
+    #
+    # @return [Class] generated null class
+    # @example
+    #   NullClass = builder.generate_class
     def generate_class
       respond_to_any_message unless interface_defined?
-      generation_mod    = Module.new
-      customization_mod = customization_module # get a local binding
-      builder           = self
 
+      generation_mod = Module.new
       apply_operations(operations, generation_mod)
 
-      null_class = Class.new(@base_class) do
-        const_set :GeneratedMethods, generation_mod
-        const_set :Customizations, customization_mod
-        const_set :NULL_EQUIVS, builder.null_equivalents
-        include Conversions
-        remove_const :NULL_EQUIVS
-        Conversions.instance_methods.each do |instance_method|
-          undef_method(instance_method)
-        end
-        const_set :Conversions, Conversions
-
-        include NullObjectTag
-        include generation_mod
-        include customization_mod
-      end
-
+      null_class = build_null_class(generation_mod)
       apply_operations(class_operations, null_class)
 
       null_class
     end
 
-    def method_missing(method_name, *args, &block)
-      command_name = command_name_for_method(method_name)
-      if Commands.const_defined?(command_name)
-        command_class = Commands.const_get(command_name)
-        command_class.new(self, *args, &block).call
-      else
-        super
-      end
-    end
+    # Builder API - see also lib/naught/null_class_builder/commands
 
-    if RUBY_VERSION >= '1.9'
-      def respond_to_missing?(method_name, include_private = false)
-        command_name = command_name_for_method(method_name)
-        Commands.const_defined?(command_name) || super
-      rescue NameError
-        super
-      end
-    else
-      def respond_to?(method_name, include_private = false)
-        command_name = command_name_for_method(method_name)
-        Commands.const_defined?(command_name) || super
-      rescue NameError
-        super
-      end
-    end
-
-    ############################################################################
-    # Builder API
+    # Configure method stubs to return self (black hole behavior)
     #
-    # See also the contents of lib/naught/null_class_builder/commands
-    ############################################################################
-
+    # @see https://github.com/avdi/naught/issues/72
+    # @return [void]
+    # @example
+    #   builder.black_hole
     def black_hole
-      @stub_strategy = :stub_method_returning_self
+      @stub_strategy = StubStrategy::ReturnSelf
+      # Prepend marshal methods to avoid infinite recursion with method_missing
+      defer_prepend_module do
+        define_method(:marshal_dump) { nil }
+        define_method(:marshal_load) { |*| nil }
+      end
     end
 
+    # Make null objects respond to any message
+    #
+    # @return [void]
+    # @example
+    #   builder.respond_to_any_message
     def respond_to_any_message
-      defer(:prepend => true) do |subject|
-        subject.module_eval do
-          def respond_to?(*)
-            true
-          end
-        end
+      defer(prepend: true) do |subject|
+        subject.define_method(:respond_to?) { |*, **| true }
         stub_method(subject, :method_missing)
       end
       @interface_defined = true
     end
 
-    def defer(options = {}, &deferred_operation)
-      list = options[:class] ? class_operations : operations
-      if options[:prepend]
-        list.unshift(deferred_operation)
-      else
-        list << deferred_operation
-      end
+    # Queue a deferred operation to be applied during class generation
+    #
+    # @param options [Hash] :class for class-level, :prepend to add at front
+    # @yieldparam subject [Module, Class] target of the operation
+    # @return [void]
+    # @example
+    #   builder.defer { |subject| subject.define_method(:foo) { "bar" } }
+    def defer(options = {}, &operation)
+      target = options[:class] ? class_operations : operations
+      options[:prepend] ? target.unshift(operation) : target.push(operation)
     end
 
+    # Prepend a module generated from the given block
+    #
+    # @return [void]
+    # @example
+    #   builder.defer_prepend_module { define_method(:foo) { "bar" } }
+    def defer_prepend_module(&)
+      prepend_modules << Module.new(&)
+    end
+
+    # Stub a method using the current stub strategy
+    #
+    # @param subject [Module, Class] target to define method on
+    # @param name [Symbol] method name to stub
+    # @return [void]
+    # @example
+    #   builder.stub_method(some_module, :foo)
     def stub_method(subject, name)
-      send(@stub_strategy, subject, name)
+      @stub_strategy.apply(subject, name)
+    end
+
+    # Dispatch builder DSL calls to command classes
+    # @return [void]
+    # @api private
+    def method_missing(method_name, *args, &)
+      command_class = lookup_command(method_name)
+      command_class ? command_class.new(self, *args, &).call : super
+    end
+
+    # Check if builder responds to a DSL command
+    #
+    # @param method_name [Symbol] method name to check
+    # @param include_private [Boolean] whether to include private methods
+    # @return [Boolean] true if method_name maps to a known command
+    # @api private
+    def respond_to_missing?(method_name, include_private = false)
+      !lookup_command(method_name).nil? || super
+    rescue NameError
+      super
     end
 
     private
 
+    # Build the null object class with all configured modules
+    #
+    # @param generation_mod [Module] module containing generated methods
+    # @return [Class] the null object class
+    # @api private
+    def build_null_class(generation_mod)
+      customization_mod = customization_module
+      null_equivs = null_equivalents
+      modules_to_prepend = prepend_modules
+
+      Class.new(@base_class) do
+        const_set :GeneratedMethods, generation_mod
+        const_set :Customizations, customization_mod
+
+        conversions_mod = Module.new { include Conversions }
+        Conversions.configure(conversions_mod, null_class: self, null_equivs: null_equivs)
+        const_set :Conversions, conversions_mod
+
+        include NullObjectTag
+        include generation_mod
+        include customization_mod
+
+        modules_to_prepend.each { |mod| prepend mod }
+      end
+    end
+
+    # Define the basic methods required by all null objects
+    #
+    # @return [void]
+    # @api private
     def define_basic_methods
       define_basic_instance_methods
       define_basic_class_methods
     end
 
-    def apply_operations(operations, module_or_class)
-      operations.each do |operation|
-        operation.call(module_or_class)
-      end
+    # Apply deferred operations to the target module or class
+    #
+    # @param ops [Array<Proc>] operations to apply
+    # @param target [Module, Class] target for the operations
+    # @return [void]
+    # @api private
+    def apply_operations(ops, target)
+      ops.each { |op| op.call(target) }
     end
 
+    # Define the basic instance methods for null objects
+    #
+    # @return [void]
+    # @api private
     def define_basic_instance_methods
+      builder = self
       defer do |subject|
-        subject.module_exec(@inspect_proc) do |inspect_proc|
-          define_method(:inspect, &inspect_proc)
-          def initialize(*)
-          end
-        end
+        subject.define_method(:inspect, &builder.inspect_proc)
+        subject.define_method(:initialize) { |*, **, &| }
       end
     end
 
+    # Define the basic class methods for null objects
+    #
+    # @return [void]
+    # @api private
     def define_basic_class_methods
-      defer(:class => true) do |subject|
-        subject.module_eval do
-          class << self
-            alias_method :get, :new
-          end
-          klass = self
-          define_method(:class) { klass }
+      defer(class: true) do |klass|
+        klass.define_singleton_method(:get) do |*args, **kwargs, &block|
+          kw = kwargs #: Hash[Symbol, untyped]
+          new(*args, **kw, &block)
         end
+        klass.define_method(:class) { klass }
       end
     end
 
-    def class_operations
-      @class_operations ||= []
-    end
+    # Returns the list of class-level operations
+    #
+    # @return [Array<Proc>] class-level operations
+    # @api private
+    def class_operations = @class_operations ||= []
 
-    def operations
-      @operations ||= []
-    end
+    # Returns the list of instance-level operations
+    #
+    # @return [Array<Proc>] instance-level operations
+    # @api private
+    def operations = @operations ||= []
 
-    def stub_method_returning_nil(subject, name)
-      subject.module_eval do
-        define_method(name) { |*| nil }
-      end
-    end
+    # Returns the list of modules to prepend
+    #
+    # @return [Array<Module>] modules to prepend to the null class
+    # @api private
+    def prepend_modules = @prepend_modules ||= []
 
-    def stub_method_returning_self(subject, name)
-      subject.module_eval do
-        define_method(name) { |*| self }
-      end
+    # Look up a command class by method name
+    #
+    # @param method_name [Symbol] method name to look up
+    # @return [Class, nil] command class if found, nil otherwise
+    # @api private
+    def lookup_command(method_name)
+      command_name = camelize(method_name)
+      Commands.const_get(command_name) if Commands.const_defined?(command_name)
     end
 
-    def command_name_for_method(method_name)
-      method_name.to_s.gsub(/(?:^|_)([a-z])/) { Regexp.last_match[1].upcase }
-    end
+    # Convert a snake_case method name to CamelCase
+    #
+    # @param name [Symbol, String] the name to convert
+    # @return [String] the CamelCase version
+    # @api private
+    def camelize(name) = name.to_s.gsub(/(?:^|_)([a-z])/) { ::Regexp.last_match(1).upcase }
   end
 end

data/lib/naught/stub_strategy.rb

@@ -0,0 +1,30 @@
+module Naught
+  # Strategies for stubbing methods on null objects
+  #
+  # @api private
+  module StubStrategy
+    # Stub that returns nil from any method
+    module ReturnNil
+      # Define a method that returns nil
+      #
+      # @param subject [Module, Class] target to define method on
+      # @param name [Symbol] method name to define
+      # @return [void]
+      def self.apply(subject, name)
+        subject.define_method(name) { |*, **, &| nil }
+      end
+    end
+
+    # Stub that returns self from any method (black hole)
+    module ReturnSelf
+      # Define a method that returns self
+      #
+      # @param subject [Module, Class] target to define method on
+      # @param name [Symbol] method name to define
+      # @return [void]
+      def self.apply(subject, name)
+        subject.define_method(name) { |*, **, &| self }
+      end
+    end
+  end
+end

data/lib/naught/version.rb

@@ -1,3 +1,5 @@
+# Top-level namespace for Naught
 module Naught
-  VERSION = '1.0.0'
+  # Gem version
+  VERSION = "2.0.0"
 end

data/lib/naught.rb

@@ -1,13 +1,37 @@
-require 'naught/version'
-require 'naught/null_class_builder'
-require 'naught/null_class_builder/commands'
+require "naught/version"
+require "naught/caller_info"
+require "naught/null_class_builder"
+require "naught/null_class_builder/commands"
 
+# Top-level namespace for Naught null object helpers
+#
+# @example Create a basic null object class
+#   NullObject = Naught.build
+#   null = NullObject.new
+#   null.foo  #=> nil
+#
+# @example Create a black hole null object
+#   BlackHole = Naught.build(&:black_hole)
+#   BlackHole.new.foo.bar.baz  #=> <null>
+#
+# @api public
 module Naught
-  def self.build(&customization_block)
+  # Build a null object class using the builder DSL
+  #
+  # @example
+  #   NullObject = Naught.build { |b| b.black_hole }
+  #
+  # @yieldparam builder [Naught::NullClassBuilder] builder DSL instance
+  # @return [Class] generated null class
+  def self.build(&)
     builder = NullClassBuilder.new
-    builder.customize(&customization_block)
+    builder.customize(&)
     builder.generate_class
   end
-  module NullObjectTag
-  end
+
+  # Marker module mixed into generated null objects
+  module NullObjectTag; end
+
+  # Marker module for null-safe proxy wrappers
+  module NullSafeProxyTag; end
 end

metadata

@@ -1,29 +1,42 @@
 --- !ruby/object:Gem::Specification
 name: naught
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Avdi Grimm
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
 description: Naught is a toolkit for building Null Objects
 email:
 - avdi@avdi.org
@@ -31,58 +44,36 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rspec"
-- ".rubocop.yml"
-- ".travis.yml"
-- Changelog.md
-- Gemfile
-- Guardfile
 - LICENSE.txt
-- README.markdown
-- Rakefile
 - lib/naught.rb
 - lib/naught/basic_object.rb
+- lib/naught/call_location.rb
+- lib/naught/caller_info.rb
+- lib/naught/chain_proxy.rb
 - lib/naught/conversions.rb
 - lib/naught/null_class_builder.rb
 - lib/naught/null_class_builder/command.rb
 - lib/naught/null_class_builder/commands.rb
+- lib/naught/null_class_builder/commands/callstack.rb
 - lib/naught/null_class_builder/commands/define_explicit_conversions.rb
 - lib/naught/null_class_builder/commands/define_implicit_conversions.rb
 - lib/naught/null_class_builder/commands/impersonate.rb
 - lib/naught/null_class_builder/commands/mimic.rb
+- lib/naught/null_class_builder/commands/null_safe_proxy.rb
 - lib/naught/null_class_builder/commands/pebble.rb
 - lib/naught/null_class_builder/commands/predicates_return.rb
 - lib/naught/null_class_builder/commands/singleton.rb
 - lib/naught/null_class_builder/commands/traceable.rb
+- lib/naught/stub_strategy.rb
 - lib/naught/version.rb
-- naught.gemspec
-- spec/base_object_spec.rb
-- spec/basic_null_object_spec.rb
-- spec/blackhole_spec.rb
-- spec/explicit_conversions_spec.rb
-- spec/functions/actual_spec.rb
-- spec/functions/just_spec.rb
-- spec/functions/maybe_spec.rb
-- spec/functions/null_spec.rb
-- spec/implicit_conversions_spec.rb
-- spec/mimic_spec.rb
-- spec/naught/null_object_builder/command_spec.rb
-- spec/naught/null_object_builder_spec.rb
-- spec/naught_spec.rb
-- spec/pebble_spec.rb
-- spec/predicate_spec.rb
-- spec/singleton_null_object_spec.rb
-- spec/spec_helper.rb
-- spec/support/convertable_null.rb
-- spec/support/jruby.rb
-- spec/support/rubinius.rb
-- spec/support/ruby_18.rb
 homepage: https://github.com/avdi/naught
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  homepage_uri: https://github.com/avdi/naught
+  source_code_uri: https://github.com/avdi/naught
+  changelog_uri: https://github.com/avdi/naught/blob/master/Changelog.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -90,37 +81,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.2.1
-signing_key: 
+rubygems_version: 4.0.5
 specification_version: 4
 summary: Naught is a toolkit for building Null Objects
-test_files:
-- spec/base_object_spec.rb
-- spec/basic_null_object_spec.rb
-- spec/blackhole_spec.rb
-- spec/explicit_conversions_spec.rb
-- spec/functions/actual_spec.rb
-- spec/functions/just_spec.rb
-- spec/functions/maybe_spec.rb
-- spec/functions/null_spec.rb
-- spec/implicit_conversions_spec.rb
-- spec/mimic_spec.rb
-- spec/naught/null_object_builder/command_spec.rb
-- spec/naught/null_object_builder_spec.rb
-- spec/naught_spec.rb
-- spec/pebble_spec.rb
-- spec/predicate_spec.rb
-- spec/singleton_null_object_spec.rb
-- spec/spec_helper.rb
-- spec/support/convertable_null.rb
-- spec/support/jruby.rb
-- spec/support/rubinius.rb
-- spec/support/ruby_18.rb
+test_files: []

data/.gitignore

@@ -1,23 +0,0 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
-/naught.org
-/naught.html
-/bin
-/TAGS
-/gems.tags
-/tags

data/.rspec

@@ -1,2 +0,0 @@
---color
---order random