naught 2.1.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e4aa0e2eddca2722a669cb141655ed975ad91535158d9d0cb09566f6971de8f
-  data.tar.gz: 2872a770d1b8d58336cee9b29be4b6108511893615c1e2c621ac2e9f8a321e56
+  metadata.gz: 7695d34e478428fe2a3dbb3164159c3ad5cbf9acea047fa38cdf8067e40edbe6
+  data.tar.gz: fe8fd997afe43bb28ddb77f926d8c5d27ab916ab74260214551b2bf0f7744da9
 SHA512:
-  metadata.gz: c2cf48a809f2777cb2a39c598aac6643bc765b44d39e29c6dbf8c539a394f134f27cced5517f84ca4e7590ec43e0ee01f9b896987c5c48a5b8d08c4793128fad
-  data.tar.gz: 8eaa91494482d1a081c1fa6c95b4c54d6e2f5cf6d1cc424bcf86cfd9a09c65618ba5fb46ca7151d2c6d288806aadc578116b97bf85c6f4df14211bf20ce0c5d0
+  metadata.gz: cb254309968a424a1e41a8c477cfd580958f3200b352fa86db071707c8df63c712a14eb276b60dd75f346bdf7ccd884c6fd963c5a74a41c1fd683312c382f2fa
+  data.tar.gz: 82a275df524b7984d23a3bd8d87c3660d96abe4ff710d6635566a9f2b7d7c2a07bff999da06349dc9c1cafc8864c9efd9e12fbdf59e7c6b59a81e80587d4326f

data/lib/naught/version.rb

@@ -1,5 +1,5 @@
 # Top-level namespace for Naught
 module Naught
   # Gem version
-  VERSION = "2.1.0"
+  VERSION = "2.3.0"
 end

data/sig/naught.rbs

@@ -0,0 +1,299 @@
+# Type signature for Naught - a toolkit for building Null Objects in Ruby
+
+module Naught
+  VERSION: String
+
+  # Lightweight proxy for tracking chained method calls
+  class ChainProxy < BasicObject
+    def initialize: (untyped root, Array[CallLocation] current_trace) -> void
+    def method_missing: (Symbol method_name, *untyped args) ?{ () -> untyped } -> ChainProxy
+    def respond_to?: (*untyped, **untyped) -> true
+    def inspect: () -> String
+    def class: () -> Class
+  end
+
+  # Utility for parsing Ruby caller/backtrace information
+  module CallerInfo
+    # module_function methods are both instance and singleton methods
+    def self?.parse: (String caller_string) -> { path: String?, lineno: Integer, base_label: String? }
+    def self?.extract_base_label: (String? method_part) -> String?
+    def self?.extract_signature: (String? method_part) -> String?
+    def self?.split_signature: (String signature) -> Array[String?]
+    def self?.format_caller_for_pebble: (Array[String] stack) -> String?
+    def self?.count_block_levels: (Array[String] stack, String target_method) -> Integer
+
+    private
+
+    def self?.parse_signature: (String signature) -> Array[String?]
+    def self?.adjusted_block_info: (String? block_info, Array[String] stack, String method_name) -> String?
+    def self?.simple_block?: (String? block_info) -> bool
+  end
+
+  # Represents a single method call in a null object's call trace
+  class CallLocation
+    def self.from_caller: (Symbol | String method_name, Array[untyped] args, String? caller_string) -> CallLocation
+
+    attr_reader label: String
+    attr_reader args: Array[untyped]
+    attr_reader path: String
+    attr_reader lineno: Integer
+    attr_reader base_label: String?
+
+    def absolute_path: () -> String
+
+    def initialize: (label: Symbol | String, args: Array[untyped], path: String, lineno: Integer, ?base_label: String?) -> void
+    def to_s: () -> String
+    def inspect: () -> String
+    def ==: (untyped other) -> bool
+    def eql?: (untyped other) -> bool
+    def hash: () -> Integer
+  end
+
+  # Build a null object class using the builder DSL
+  def self.build: () { (NullClassBuilder) -> void } -> Class
+                | () -> Class
+
+  # Marker module mixed into generated null objects
+  module NullObjectTag
+  end
+
+  # Marker module for null-safe proxy wrappers
+  module NullSafeProxyTag
+  end
+
+  # BasicObject subclass used as a minimal base for null objects
+  class BasicObject < ::BasicObject
+  end
+
+  # Helper conversion API available on generated null classes
+  module Conversions
+    # Configure a Conversions module for a specific null class
+    def self.configure: (Module mod, null_class: Class, null_equivs: Array[untyped]) -> void
+
+    # Return a null object for object if it is null-equivalent
+    def Null: (?untyped object) -> untyped
+
+    # Return a null object for null-equivalent values, otherwise the value
+    def Maybe: (?untyped object) -> untyped
+             | [T] () { () -> T } -> (T | untyped)
+
+    # Return the value if not null-equivalent, otherwise raise
+    def Just: (?untyped object) -> untyped
+            | [T] () { () -> T } -> T
+
+    # Return nil for null objects, otherwise return the value
+    def Actual: (?untyped object) -> untyped
+              | [T] () { () -> T } -> T?
+
+    private
+
+    def __null_class__: () -> Class
+    def __null_equivs__: () -> Array[untyped]
+    def null_object?: (untyped object) -> bool
+    def null_equivalent?: (untyped object, ?include_nothing: bool) -> bool
+    def make_null: (Integer caller_offset) -> untyped
+  end
+
+  # Strategies for stubbing methods on null objects
+  module StubStrategy
+    # Stub that returns nil from any method
+    module ReturnNil
+      def self.apply: (Module subject, Symbol name) -> void
+    end
+
+    # Stub that returns self from any method (black hole)
+    module ReturnSelf
+      def self.apply: (Module subject, Symbol name) -> void
+    end
+  end
+
+  # Builds customized null object classes via a small DSL
+  class NullClassBuilder
+    # Namespace for builder command classes
+    module Commands
+    end
+
+    type stub_strategy = singleton(StubStrategy::ReturnNil) | singleton(StubStrategy::ReturnSelf)
+    type deferred_operation = ^(untyped) -> void
+
+    attr_accessor base_class: Class
+    attr_accessor inspect_proc: ^() -> String
+    attr_accessor interface_defined: bool
+
+    def interface_defined?: () -> bool
+
+    def initialize: () -> void
+
+    # Apply a customization block to this builder
+    def customize: () { (NullClassBuilder) -> void } -> void
+                 | () -> void
+
+    # Module that holds customization methods
+    def customization_module: () -> Module
+
+    # Values treated as null-equivalent
+    def null_equivalents: () -> Array[untyped]
+
+    # Generate the null object class based on queued operations
+    def generate_class: () -> Class
+
+    # Configure method stubs to return self (black hole behavior)
+    def black_hole: () -> void
+
+    # DSL methods dispatched via method_missing to command classes
+    def define_explicit_conversions: () -> void
+    def define_implicit_conversions: () -> void
+    def predicates_return: (untyped value) -> void
+    def mimic: (Class class_to_mimic, ?{ ?include_super: bool, ?include_dynamic: bool } options) -> void
+             | ({ example: untyped, ?include_super: bool, ?include_dynamic: bool } options) -> void
+    def impersonate: (Class class_to_impersonate, ?{ ?include_super: bool, ?include_dynamic: bool } options) -> void
+    def pebble: (?Naught::NullClassBuilder::Commands::Pebble::_Output output) -> void
+    def singleton: () -> void
+    def traceable: () -> void
+    def callstack: () -> void
+    def null_safe_proxy: () -> void
+
+    # Make null objects respond to any message and stub method_missing
+    def respond_to_any_message: () -> void
+
+    # Queue a deferred operation to be applied during class generation
+    # Block is evaluated in module context via module_eval
+    def defer: (?Hash[Symbol, bool] options) { (untyped) -> untyped } -> void
+
+    # Prepend a module generated from the given block
+    # Block is evaluated in module context via Module.new
+    def defer_prepend_module: () { () -> untyped } -> void
+
+    # Stub a method using the current stub strategy
+    def stub_method: (untyped subject, Symbol name) -> void
+
+    private
+
+    def build_null_class: (Module generation_mod) -> Class
+    def define_basic_methods: () -> void
+    def apply_operations: (Array[deferred_operation] operations, untyped module_or_class) -> void
+    def define_basic_instance_methods: () -> void
+    def define_basic_class_methods: () -> void
+    def class_operations: () -> Array[deferred_operation]
+    def operations: () -> Array[deferred_operation]
+    def prepend_modules: () -> Array[Module]
+    def lookup_command: (Symbol method_name) -> singleton(Command)?
+    def camelize: (Symbol | String name) -> String
+
+    # Base class for builder command implementations
+    class Command
+      attr_reader builder: NullClassBuilder
+
+      def initialize: (NullClassBuilder builder, *untyped, **untyped) ?{ () -> untyped } -> void
+      def call: () -> void
+
+      private
+
+      def defer: (?Hash[Symbol, bool] options) { (untyped) -> untyped } -> void
+      def defer_class: () { (untyped) -> untyped } -> void
+      def defer_prepend_module: () { () -> untyped } -> void
+    end
+  end
+end
+
+# Command classes under the Commands namespace
+module Naught
+  class NullClassBuilder
+    module Commands
+      class DefineExplicitConversions < Naught::NullClassBuilder::Command
+        def initialize: (NullClassBuilder builder, *untyped, **untyped) ?{ () -> untyped } -> void
+        def call: () -> void
+      end
+
+      class DefineImplicitConversions < Naught::NullClassBuilder::Command
+        EMPTY_ARRAY: Array[untyped]
+        EMPTY_HASH: Hash[untyped, untyped]
+        RETURN_VALUES: Hash[Symbol, untyped]
+
+        def initialize: (NullClassBuilder builder, *untyped, **untyped) ?{ () -> untyped } -> void
+        def call: () -> void
+      end
+
+      class Mimic < Naught::NullClassBuilder::Command
+        METHODS_TO_SKIP: Array[Symbol]
+        NULL_SINGLETON_CLASS: Class
+
+        attr_reader class_to_mimic: Class
+        attr_reader include_super: bool
+        attr_reader singleton_class: Class
+        attr_reader example_instance: untyped
+        attr_reader include_dynamic: bool
+
+        def initialize: (NullClassBuilder builder, Class | Hash[Symbol, untyped] class_to_mimic_or_options, ?Hash[Symbol, untyped] options) ?{ () -> untyped } -> void
+        def call: () -> void
+
+        private
+
+        def parse_arguments: (Class | Hash[Symbol, untyped] class_to_mimic_or_options, Hash[Symbol, untyped] options) -> void
+        def configure_builder: () -> void
+        def root_class_of: (Class klass) -> Class
+        def methods_to_stub: () -> Array[Symbol]
+        def dynamic_methods: () -> Array[Symbol]
+        def discover_method_candidates: () -> Array[Symbol]
+      end
+
+      class Impersonate < Naught::NullClassBuilder::Commands::Mimic
+        def initialize: (NullClassBuilder builder, Class class_to_impersonate, ?Hash[Symbol, untyped] options) ?{ () -> untyped } -> void
+      end
+
+      class Pebble < Naught::NullClassBuilder::Command
+        interface _Output
+          def puts: (String) -> void
+        end
+
+        @output: _Output
+
+        def initialize: (NullClassBuilder builder, ?_Output output) ?{ () -> untyped } -> void
+        def call: () -> void
+      end
+
+      class PredicatesReturn < Naught::NullClassBuilder::Command
+        @return_value: untyped
+
+        def initialize: (NullClassBuilder builder, untyped return_value) ?{ () -> untyped } -> void
+        def call: () -> void
+
+        private
+
+        def install_method_missing_override: () -> void
+        def install_predicate_method_overrides: () -> void
+      end
+
+      class Singleton < Naught::NullClassBuilder::Command
+        def initialize: (NullClassBuilder builder, *untyped, **untyped) ?{ () -> untyped } -> void
+        def call: () -> void
+      end
+
+      class Traceable < Naught::NullClassBuilder::Command
+        def initialize: (NullClassBuilder builder, *untyped, **untyped) ?{ () -> untyped } -> void
+        def call: () -> void
+      end
+
+      class NullSafeProxy < Naught::NullClassBuilder::Command
+        def initialize: (NullClassBuilder builder, *untyped, **untyped) ?{ () -> untyped } -> void
+        def call: () -> void
+
+        private
+
+        def build_proxy_class: (Class null_class, Array[untyped] null_equivs) -> Class
+        def install_null_safe_conversion: (Class null_class, Class proxy_class, Array[untyped] null_equivs) -> void
+      end
+
+      class Callstack < Naught::NullClassBuilder::Command
+        def initialize: (NullClassBuilder builder, *untyped, **untyped) ?{ () -> untyped } -> void
+        def call: () -> void
+
+        private
+
+        def install_call_trace_accessor: () -> void
+        def install_method_missing_tracking: () -> void
+        def install_chain_proxy_class: () -> void
+      end
+    end
+  end
+end

metadata

@@ -1,42 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: naught
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Avdi Grimm
 bindir: bin
 cert_chain: []
 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: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        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'
+dependencies: []
 description: Naught is a toolkit for building Null Objects
 email:
 - avdi@avdi.org
@@ -66,6 +38,7 @@ files:
 - lib/naught/null_class_builder/commands/traceable.rb
 - lib/naught/stub_strategy.rb
 - lib/naught/version.rb
+- sig/naught.rbs
 homepage: https://github.com/avdi/naught
 licenses:
 - MIT
@@ -88,7 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.7
 specification_version: 4
 summary: Naught is a toolkit for building Null Objects
 test_files: []