cmdx 1.0.1 → 1.1.1

data/lib/cmdx/core_ext/hash.rb

@@ -2,51 +2,28 @@
 
 module CMDx
   module CoreExt
-    # Extensions to Hash that provide CMDx-specific key access methods.
-    #
-    # HashExtensions adds flexible key access that works with both
-    # string and symbol keys interchangeably. These methods are prefixed
-    # with `__cmdx_` to avoid conflicts with existing Hash methods.
-    #
-    # @example Flexible key access
-    #   hash = {name: "John", "age" => 30}
-    #   hash.__cmdx_fetch(:name)      # => "John" (symbol key)
-    #   hash.__cmdx_fetch("name")     # => "John" (tries symbol fallback)
-    #   hash.__cmdx_fetch(:age)       # => 30 (string fallback)
-    #
-    # @example Key checking
-    #   hash.__cmdx_key?(:name)       # => true (checks both symbol and string)
-    #   hash.__cmdx_key?("age")       # => true (checks both string and symbol)
-    #
-    # @example Method response checking
-    #   hash.__cmdx_respond_to?(:name)   # => true (considers key as method)
-    #
-    # @see Context Context objects that use hash extensions
-    # @see LazyStruct Structs that leverage hash-like behavior
+    # Extensions for Ruby's Hash class that provide flexible key access and querying.
+    # These extensions are automatically included in all hashes when CMDx is loaded, providing
+    # seamless symbol/string key interoperability and enhanced key existence checking.
     module HashExtensions
 
-      # Fetch a value with automatic symbol/string key conversion.
+      # Fetches a value from the hash with flexible key matching.
+      # Tries the exact key first, then attempts symbol/string conversion if not found.
       #
-      # This method provides flexible key access by trying both the original
-      # key and its converted form (symbol to string or string to symbol).
-      # This is particularly useful for parameter hashes that might use
-      # either format.
+      # @param key [Symbol, String, Object] the key to fetch from the hash
       #
-      # @param key [Symbol, String, Object] key to fetch
-      # @return [Object] value for the key or its converted equivalent
+      # @return [Object, nil] the value associated with the key, or nil if not found
       #
-      # @example Symbol to string conversion
-      #   hash = {"name" => "John"}
-      #   hash.__cmdx_fetch(:name)        # => "John" (tries :name, then "name")
+      # @example Fetch with symbol key
+      #   hash = { name: "John", "age" => 30 }
+      #   hash.cmdx_fetch(:name) #=> "John"
+      #   hash.cmdx_fetch(:age)  #=> 30
       #
-      # @example String to symbol conversion
-      #   hash = {name: "John"}
-      #   hash.__cmdx_fetch("name")       # => "John" (tries "name", then :name)
-      #
-      # @example Direct key access
-      #   hash = {id: 123}
-      #   hash.__cmdx_fetch(:id)          # => 123 (direct match)
-      def __cmdx_fetch(key)
+      # @example Fetch with string key
+      #   hash = { name: "John", "age" => 30 }
+      #   hash.cmdx_fetch("name") #=> "John"
+      #   hash.cmdx_fetch("age")  #=> 30
+      def cmdx_fetch(key)
         case key
         when Symbol then fetch(key) { self[key.to_s] }
         when String then fetch(key) { self[key.to_sym] }
@@ -54,21 +31,21 @@ module CMDx
         end
       end
 
-      # Check if a key exists with automatic symbol/string conversion.
+      # Checks if a key exists in the hash with flexible key matching.
+      # Tries the exact key first, then attempts symbol/string conversion.
       #
-      # This method checks for key existence by trying both the original
-      # key and its converted form. Returns true if either variant exists.
+      # @param key [Symbol, String, Object] the key to check for existence
       #
-      # @param key [Symbol, String, Object] key to check
-      # @return [Boolean] true if key exists in either format
+      # @return [Boolean] true if the key exists (in any form), false otherwise
       #
-      # @example Symbol/string checking
-      #   hash = {name: "John", "age" => 30}
-      #   hash.__cmdx_key?(:name)         # => true
-      #   hash.__cmdx_key?("name")        # => true (checks :name fallback)
-      #   hash.__cmdx_key?(:age)          # => true (checks "age" fallback)
-      #   hash.__cmdx_key?(:missing)      # => false
-      def __cmdx_key?(key)
+      # @example Check key existence
+      #   hash = { name: "John", "age" => 30 }
+      #   hash.cmdx_key?(:name)   #=> true
+      #   hash.cmdx_key?("name")  #=> true
+      #   hash.cmdx_key?(:age)    #=> true
+      #   hash.cmdx_key?("age")   #=> true
+      #   hash.cmdx_key?(:missing) #=> false
+      def cmdx_key?(key)
         key?(key) || key?(
           case key
           when Symbol then key.to_s
@@ -79,30 +56,28 @@ module CMDx
         false
       end
 
-      # Check if hash responds to a method or contains a key.
+      # Checks if the hash responds to a method or contains a key.
+      # Combines method existence checking with flexible key existence checking.
       #
-      # This method extends respond_to? behavior to also check if the
-      # hash contains a key that matches the method name. This enables
-      # hash keys to be treated as virtual methods.
+      # @param key [Symbol, String] the method name or key to check
+      # @param include_private [Boolean] whether to include private methods in the check
       #
-      # @param key [Symbol, String] method name to check
-      # @param include_private [Boolean] whether to include private methods
-      # @return [Boolean] true if responds to method or contains key
+      # @return [Boolean] true if the hash responds to the method or contains the key
       #
-      # @example Method response checking
-      #   hash = {name: "John"}
-      #   hash.__cmdx_respond_to?(:name)     # => true (has key :name)
-      #   hash.__cmdx_respond_to?(:keys)     # => true (real Hash method)
-      #   hash.__cmdx_respond_to?(:missing)  # => false
-      def __cmdx_respond_to?(key, include_private = false)
-        respond_to?(key.to_sym, include_private) || __cmdx_key?(key)
+      # @example Check method or key response
+      #   hash = { name: "John", "age" => 30 }
+      #   hash.cmdx_respond_to?(:keys)     #=> true (method exists)
+      #   hash.cmdx_respond_to?(:name)     #=> true (key exists)
+      #   hash.cmdx_respond_to?("age")     #=> true (key exists)
+      #   hash.cmdx_respond_to?(:missing)  #=> false
+      def cmdx_respond_to?(key, include_private = false)
+        respond_to?(key.to_sym, include_private) || cmdx_key?(key)
       rescue NoMethodError
-        __cmdx_key?(key)
+        cmdx_key?(key)
       end
 
     end
   end
 end
 
-# Extend all hashes with CMDx utility methods
 Hash.include(CMDx::CoreExt::HashExtensions)

data/lib/cmdx/core_ext/module.rb

@@ -2,65 +2,39 @@
 
 module CMDx
   module CoreExt
-    # Extensions to Module that provide CMDx-specific metaprogramming capabilities.
-    #
-    # ModuleExtensions adds method delegation and attribute setting functionality
-    # used throughout the CMDx framework. These methods enable declarative
-    # programming patterns and automatic method generation.
-    #
-    # @example Method delegation
-    #   class Task
-    #     __cmdx_attr_delegator :name, :email, to: :user
-    #     __cmdx_attr_delegator :save, to: :record, private: true
-    #   end
-    #
-    # @example Attribute settings
-    #   class Task
-    #     __cmdx_attr_setting :default_options, default: -> { {} }
-    #     __cmdx_attr_setting :configuration, default: {}
-    #   end
-    #
-    # @see Task Tasks that use module extensions for delegation
-    # @see Parameter Parameters that use attribute settings
+    # Extensions for Ruby's Module class that provide attribute delegation and settings functionality.
+    # These extensions are automatically included in all modules when CMDx is loaded.
     module ModuleExtensions
 
-      # Create delegator methods that forward calls to another object.
+      # Creates delegated methods that forward calls to another object or class.
+      # Supports method name prefixing, privacy levels, and optional method existence checking.
       #
-      # This method generates instance methods that delegate to methods on
-      # another object. It supports method visibility controls and optional
-      # missing method handling.
-      #
-      # @param methods [Array<Symbol>] method names to delegate
+      # @param methods [Array<Symbol>] the method names to delegate
       # @param options [Hash] delegation options
-      # @option options [Symbol] :to target object method name (required)
-      # @option options [Boolean] :allow_missing whether to allow missing methods
-      # @option options [Boolean] :private make delegated methods private
-      # @option options [Boolean] :protected make delegated methods protected
-      # @return [void]
+      # @option options [Symbol] :to the target object or :class to delegate to
+      # @option options [Boolean] :allow_missing (false) whether to allow delegation to non-existent methods
+      # @option options [Boolean] :protected (false) whether to make the delegated method protected
+      # @option options [Boolean] :private (false) whether to make the delegated method private
+      # @option options [String, Symbol] :prefix optional prefix for the delegated method name
+      # @option options [String, Symbol] :suffix optional suffix for the delegated method name
       #
-      # @example Basic delegation
-      #   class User
-      #     __cmdx_attr_delegator :first_name, :last_name, to: :profile
-      #     # Creates: def first_name; profile.first_name; end
-      #   end
+      # @return [void]
+      # @raise [NoMethodError] when delegating to a non-existent method and :allow_missing is false
       #
-      # @example Private delegation
+      # @example Delegate methods to an instance variable
       #   class Task
-      #     __cmdx_attr_delegator :validate, to: :validator, private: true
-      #   end
+      #     def initialize
+      #       @logger = Logger.new
+      #     end
       #
-      # @example Class delegation
-      #   class Task
-      #     __cmdx_attr_delegator :configuration, to: :class
+      #     cmdx_attr_delegator :info, :warn, :error, to: :@logger
       #   end
       #
-      # @example With missing method handling
-      #   class Task
-      #     __cmdx_attr_delegator :optional_method, to: :service, allow_missing: true
+      # @example Delegate with prefix and privacy
+      #   class Workflow
+      #     cmdx_attr_delegator :perform, to: :task, prefix: 'execute_', private: true
       #   end
-      #
-      # @raise [NoMethodError] if target object doesn't respond to method and allow_missing is false
-      def __cmdx_attr_delegator(*methods, **options)
+      def cmdx_attr_delegator(*methods, **options)
         methods.each do |method|
           method_name = Utils::NameAffix.call(method, options.fetch(:to), options)
 
@@ -83,53 +57,36 @@ module CMDx
         end
       end
 
-      # Create class-level attribute accessor with lazy evaluation and inheritance.
+      # Creates a singleton method for accessing inheritable settings with caching and default values.
+      # Settings are inherited from superclass and can have default values via blocks or static values.
       #
-      # This method generates a class method that provides lazy-loaded attribute
-      # access with inheritance support. Values are cached and can be initialized
-      # with default values or procs.
+      # @param method [Symbol] the name of the setting method to create
+      # @param options [Hash] setting options
+      # @option options [Object, Proc] :default the default value or a proc that returns the default value
       #
-      # @param method [Symbol] name of the attribute method
-      # @param options [Hash] attribute options
-      # @option options [Object, Proc] :default default value or proc to generate value
       # @return [void]
       #
-      # @example Simple attribute setting
-      #   class Task
-      #     __cmdx_attr_setting :timeout, default: 30
-      #   end
-      #   # Task.timeout => 30
-      #
-      # @example Dynamic default with proc
-      #   class Task
-      #     __cmdx_attr_setting :timestamp, default: -> { Time.now }
-      #   end
-      #   # Task.timestamp => current time (evaluated lazily)
-      #
-      # @example Inherited settings
+      # @example Define a setting with a default value
       #   class BaseTask
-      #     __cmdx_attr_setting :options, default: {retry: 3}
+      #     cmdx_attr_setting :timeout, default: 30
       #   end
       #
-      #   class ProcessTask < BaseTask
-      #   end
-      #   # ProcessTask.options => {retry: 3} (inherited from BaseTask)
+      #   BaseTask.timeout #=> 30
       #
-      # @example Hash settings (automatically duplicated)
+      # @example Define a setting with a dynamic default
       #   class Task
-      #     __cmdx_attr_setting :config, default: {}
+      #     cmdx_attr_setting :retry_count, default: -> { ENV['RETRY_COUNT']&.to_i || 3 }
       #   end
-      #   # Each class gets its own copy of the hash
-      def __cmdx_attr_setting(method, **options)
+      def cmdx_attr_setting(method, **options)
         define_singleton_method(method) do
           @cmd_facets ||= {}
           return @cmd_facets[method] if @cmd_facets.key?(method)
 
-          value = superclass.__cmdx_try(method)
+          value = superclass.cmdx_try(method)
           return @cmd_facets[method] = value.dup unless value.nil?
 
           default = options[:default]
-          value   = default.__cmdx_call
+          value   = default.cmdx_call
           @cmd_facets[method] = default.is_a?(Proc) ? value : value.dup
         end
       end
@@ -138,5 +95,4 @@ module CMDx
   end
 end
 
-# Extend all modules with CMDx utility methods
 Module.include(CMDx::CoreExt::ModuleExtensions)

data/lib/cmdx/core_ext/object.rb

@@ -2,151 +2,117 @@
 
 module CMDx
   module CoreExt
-    # Extensions to Object that provide CMDx-specific utility methods.
-    #
-    # ObjectExtensions adds safe method calling, conditional evaluation,
-    # and value yielding capabilities to all Ruby objects. These methods
-    # are prefixed with `__cmdx_` to avoid conflicts with existing methods.
-    #
-    # @example Safe method calling
-    #   object.__cmdx_try(:some_method)  # Returns nil if method doesn't exist
-    #   object.__cmdx_try(proc { expensive_calculation })  # Calls proc safely
-    #
-    # @example Conditional evaluation
-    #   object.__cmdx_eval(if: :valid?)       # True if object.valid? is true
-    #   object.__cmdx_eval(unless: :empty?)   # True unless object.empty? is true
-    #   object.__cmdx_eval(if: :valid?, unless: :processed?)  # Combined conditions
-    #
-    # @example Value yielding
-    #   object.__cmdx_yield(:name)           # Returns object.name if method exists, otherwise :name
-    #   object.__cmdx_yield(-> { compute })  # Executes lambda and returns result
-    #
-    # @see Task Tasks that use these object extensions
-    # @see Parameter Parameters that leverage object extensions
+    # Extensions for Ruby's Object class that provide flexible method calling and evaluation utilities.
+    # These extensions are automatically included in all objects when CMDx is loaded, providing
+    # safe method invocation, conditional evaluation, and dynamic yielding capabilities.
     module ObjectExtensions
 
-      # Store original respond_to? method before aliasing
-      alias __cmdx_respond_to? respond_to?
+      alias cmdx_respond_to? respond_to?
 
-      # Safely attempt to call a method or execute a proc on an object.
+      # Safely tries to call a method, evaluate a proc, or access a hash key.
+      # Provides flexible invocation that handles different types of callables gracefully.
       #
-      # This method provides safe method calling with fallback behavior.
-      # It handles method calls, proc execution, and hash key access gracefully.
+      # @param key [Symbol, String, Proc, Object] the method name, proc, or hash key to try
+      # @param args [Array] arguments to pass to the method or proc
       #
-      # @param key [Symbol, String, Proc] method name or callable to attempt
-      # @param args [Array] arguments to pass to the method/proc (passed via splat)
-      # @return [Object, nil] result of method call, proc execution, or nil if not possible
+      # @return [Object, nil] the result of the method call, proc evaluation, or hash access; nil if not found
       #
-      # @example Method calling
-      #   user.__cmdx_try(:name)              # => "John" or nil
-      #   user.__cmdx_try(:age, 25)           # => calls user.age(25) or nil
+      # @example Try calling a method
+      #   "hello".cmdx_try(:upcase) #=> "HELLO"
+      #   "hello".cmdx_try(:missing) #=> nil
       #
-      # @example Proc execution
-      #   user.__cmdx_try(-> { expensive_calc }) # => executes lambda
-      #   user.__cmdx_try(proc { |x| x * 2 }, 5) # => 10
+      # @example Try evaluating a proc
+      #   obj.cmdx_try(-> { self.class.name }) #=> "String"
       #
-      # @example Hash access
-      #   hash = {name: "John"}
-      #   hash.__cmdx_try(:name)              # => "John"
-      def __cmdx_try(key, ...)
+      # @example Try accessing a hash key
+      #   {name: "John"}.cmdx_try(:name) #=> "John"
+      def cmdx_try(key, *args, **kwargs, &)
         if key.is_a?(Proc)
           return instance_eval(&key) unless is_a?(Module) || key.inspect.include?("(lambda)")
 
-          key.call(...)
+          if key.arity.positive? && args.empty?
+            key.call(self, *args, **kwargs, &)
+          else
+            key.call(*args, **kwargs, &)
+          end
         elsif respond_to?(key, true)
-          send(key, ...)
+          send(key, *args, **kwargs, &)
         elsif is_a?(Hash)
-          __cmdx_fetch(key)
+          cmdx_fetch(key)
         end
       end
 
-      # Evaluate conditional options for execution control.
+      # Evaluates conditional options using :if and :unless logic.
+      # Supports both method names and procs for conditional evaluation.
       #
-      # This method evaluates :if and :unless conditions to determine
-      # whether something should proceed. Used extensively in callbacks
-      # and conditional parameter processing.
+      # @param options [Hash] evaluation options
+      # @option options [Symbol, Proc] :if condition that must be truthy
+      # @option options [Symbol, Proc] :unless condition that must be falsy
+      # @option options [Object] :default (true) default value when no conditions are specified
       #
-      # @param options [Hash] conditional options
-      # @option options [Symbol, Proc] :if condition that must be true
-      # @option options [Symbol, Proc] :unless condition that must be false
-      # @option options [Boolean] :default default value if no conditions (default: true)
-      # @return [Boolean] true if conditions are met
+      # @return [Boolean] true if conditions are met, false otherwise
       #
-      # @example Simple conditions
-      #   user.__cmdx_eval(if: :admin?)       # => true if user.admin? is true
-      #   user.__cmdx_eval(unless: :guest?)   # => true unless user.guest? is true
+      # @example Evaluate with if condition
+      #   user.cmdx_eval(if: :active?) #=> true if user.active? is truthy
       #
-      # @example Combined conditions
-      #   user.__cmdx_eval(if: :active?, unless: :banned?)  # => active AND not banned
+      # @example Evaluate with unless condition
+      #   user.cmdx_eval(unless: :banned?) #=> true if user.banned? is falsy
       #
-      # @example With procs
-      #   user.__cmdx_eval(if: -> { Time.now.monday? }) # => true if today is Monday
-      def __cmdx_eval(options = {})
+      # @example Evaluate with both conditions
+      #   user.cmdx_eval(if: :active?, unless: :banned?) #=> true if active and not banned
+      def cmdx_eval(options = {})
         if options[:if] && options[:unless]
-          __cmdx_try(options[:if]) && !__cmdx_try(options[:unless])
+          cmdx_try(options[:if]) && !cmdx_try(options[:unless])
         elsif options[:if]
-          __cmdx_try(options[:if])
+          cmdx_try(options[:if])
         elsif options[:unless]
-          !__cmdx_try(options[:unless])
+          !cmdx_try(options[:unless])
         else
           options.fetch(:default, true)
         end
       end
 
-      # Yield a value by attempting to call it as a method or executing it.
+      # Yields or returns a value based on its type, with smart method calling.
+      # Handles symbols/strings as method names, procs/hashes via cmdx_try, and returns other values as-is.
       #
-      # This method provides intelligent value resolution - if the key is
-      # a method name and the object responds to it, call the method.
-      # Otherwise, try to execute it as a proc or return the value as-is.
+      # @param key [Symbol, String, Proc, Hash, Object] the value to yield or method to call
+      # @param args [Array] arguments to pass to method calls
       #
-      # @param key [Object] value to yield, method name, or callable
-      # @param args [Array] arguments to pass if calling method/proc (passed via splat)
-      # @return [Object] yielded value
+      # @return [Object] the result of method call, proc evaluation, or the value itself
       #
-      # @example Method yielding
-      #   user.__cmdx_yield(:name)           # => calls user.name if method exists, otherwise returns :name
-      #   user.__cmdx_yield("email")         # => calls user.email if method exists, otherwise returns "email"
+      # @example Yield a method call
+      #   "hello".cmdx_yield(:upcase) #=> "HELLO"
       #
-      # @example Proc yielding
-      #   user.__cmdx_yield(-> { timestamp }) # => executes lambda
-      #   hash.__cmdx_yield({key: "value"})   # => tries hash access
+      # @example Yield a static value
+      #   obj.cmdx_yield("static") #=> "static"
       #
-      # @example Direct values
-      #   user.__cmdx_yield(42)              # => 42
-      #   user.__cmdx_yield("literal")       # => "literal"
-      def __cmdx_yield(key, ...)
+      # @example Yield a proc
+      #   obj.cmdx_yield(-> { Time.now }) #=> 2023-01-01 12:00:00 UTC
+      def cmdx_yield(key, ...)
         if key.is_a?(Symbol) || key.is_a?(String)
           return key unless respond_to?(key, true)
 
           send(key, ...)
         elsif is_a?(Hash) || key.is_a?(Proc)
-          __cmdx_try(key, ...)
+          cmdx_try(key, ...)
         else
           key
         end
       end
 
-      # Call an object if it responds to call, otherwise return itself.
-      #
-      # This method provides safe callable execution - if the object
-      # can be called (like a proc or lambda), call it with the given
-      # arguments. Otherwise, return the object unchanged.
+      # Invokes the object if it responds to :call, otherwise returns the object itself.
+      # Useful for handling both callable and non-callable objects uniformly.
       #
-      # @param args [Array] arguments to pass to call method (passed via splat)
-      # @return [Object] result of calling or the object itself
+      # @param args [Array] arguments to pass to the call method
       #
-      # @example Callable objects
-      #   proc = -> { "Hello" }
-      #   proc.__cmdx_call                   # => "Hello"
+      # @return [Object] the result of calling the object, or the object itself if not callable
       #
-      # @example Non-callable objects
-      #   string = "Hello"
-      #   string.__cmdx_call                 # => "Hello"
+      # @example Invoke a proc
+      #   proc { "hello" }.cmdx_call #=> "hello"
       #
-      # @example With arguments
-      #   adder = ->(a, b) { a + b }
-      #   adder.__cmdx_call(2, 3)           # => 5
-      def __cmdx_call(...)
+      # @example Invoke a non-callable object
+      #   "hello".cmdx_call #=> "hello"
+      def cmdx_call(...)
         return self unless respond_to?(:call)
 
         call(...)
@@ -156,5 +122,4 @@ module CMDx
   end
 end
 
-# Extend all objects with CMDx utility methods
 Object.include(CMDx::CoreExt::ObjectExtensions)