ivar 0.2.0 → 0.4.0

data/examples/sandwich_with_block_values.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "ivar"
+
+class SandwichWithBlockValues
+  include Ivar::Checked
+
+  # Declare condiments with a block that generates default values based on the variable name
+  ivar(:@mayo, :@mustard, :@ketchup) { |varname| !varname.include?("mayo") }
+
+  # Declare bread and cheese with individual values
+  ivar "@bread": "wheat", "@cheese": "cheddar"
+
+  # Declare a variable without an initial value
+  ivar :@side
+
+  def initialize(options = {})
+    # Override any condiments based on options
+    @mayo = true if options[:add_mayo]
+    @mustard = false if options[:no_mustard]
+    @ketchup = false if options[:no_ketchup]
+
+    # Set the side if provided
+    @side = options[:side] if options[:side]
+  end
+
+  def to_s
+    result = "A #{@bread} sandwich with #{@cheese}"
+
+    condiments = []
+    condiments << "mayo" if @mayo
+    condiments << "mustard" if @mustard
+    condiments << "ketchup" if @ketchup
+
+    result += " with #{condiments.join(", ")}" unless condiments.empty?
+    result += " and a side of #{@side}" if defined?(@side) && @side
+    result
+  end
+end
+
+# Create a sandwich with default values (no mayo, but has mustard and ketchup)
+sandwich = SandwichWithBlockValues.new
+puts sandwich
+# => "A wheat sandwich with cheddar with mustard, ketchup"
+
+# Create a sandwich with mayo added
+sandwich_with_mayo = SandwichWithBlockValues.new(add_mayo: true)
+puts sandwich_with_mayo
+# => "A wheat sandwich with cheddar with mayo, mustard, ketchup"
+
+# Create a sandwich with a side
+sandwich_with_side = SandwichWithBlockValues.new(side: "chips")
+puts sandwich_with_side
+# => "A wheat sandwich with cheddar with mustard, ketchup and a side of chips"

data/examples/sandwich_with_checked.rb

@@ -9,7 +9,6 @@ class SandwichWithChecked
     @bread = "wheat"
     @cheese = "muenster"
     @condiments = ["mayo", "mustard"]
-    # No need for explicit check_ivars call
   end
 
   def to_s

data/examples/sandwich_with_checked_once.rb

@@ -10,7 +10,6 @@ class SandwichWithCheckedOnce
     @bread = "wheat"
     @cheese = "muenster"
     @condiments = %w[mayo mustard]
-    # No need for explicit check_ivars call
   end
 
   def to_s

data/examples/sandwich_with_initial_values.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "ivar"
+
+class SandwichWithInitialValues
+  include Ivar::Checked
+
+  # Declare instance variables with initial values
+  ivar "@bread": "wheat",
+    "@cheese": "muenster",
+    "@condiments": ["mayo", "mustard"],
+    "@pickles": true
+
+  # Declare a variable without an initial value
+  ivar :@side
+
+  def initialize(extra_condiments = [])
+    # The declared variables are already initialized with their values
+    # We can modify them here
+    @condiments += extra_condiments unless extra_condiments.empty?
+
+    # We can also check if pickles were requested and adjust condiments
+    @condiments.delete("mayo") if @pickles
+  end
+
+  def to_s
+    result = "A #{@bread} sandwich with #{@cheese}"
+    result += " and #{@condiments.join(", ")}" unless @condiments.empty?
+    result += " with pickles" if @pickles
+    result += " and a side of #{@side}" if defined?(@side) && @side
+    result
+  end
+
+  def add_side(side)
+    @side = side
+  end
+end
+
+# Create a sandwich with default values
+sandwich = SandwichWithInitialValues.new
+puts sandwich
+# => "A wheat sandwich with muenster and mustard with pickles"
+
+# Create a sandwich with extra condiments
+sandwich_with_extras = SandwichWithInitialValues.new(["ketchup", "relish"])
+puts sandwich_with_extras
+# => "A wheat sandwich with muenster and mustard, ketchup, relish with pickles"
+
+# Add a side
+sandwich.add_side("chips")
+puts sandwich
+# => "A wheat sandwich with muenster and mustard with pickles and a side of chips"

data/examples/sandwich_with_ivar_block.rb

@@ -5,27 +5,24 @@ require "ivar"
 class SandwichWithIvarBlock
   include Ivar::Checked
 
-  # Pre-declare instance variables with a block that runs before initialization
-  ivar :@side do
-    @pickles = true
-    @condiments = []
-  end
+  # Declare instance variables
+  ivar :@side
 
   def initialize
     @bread = "wheat"
     @cheese = "muenster"
-    # Note: @pickles is already set to true by the ivar block
-    # Note: @condiments is already initialized to an empty array by the ivar block
+    @pickles = true
+    @condiments = []
     @condiments << "mayo" if !@pickles
     @condiments << "mustard"
-    # Note: @side is not set here, but it's pre-initialized to nil
+    # @side is declared but intentionally not initialized here
   end
 
   def to_s
     result = "A #{@bread} sandwich with #{@cheese}"
     result += " and #{@condiments.join(", ")}" unless @condiments.empty?
     result += " with pickles" if @pickles
-    result += " and a side of #{@side}" if @side
+    result += " and a side of #{@side}" if defined?(@side) && @side
     result
   end
 

data/examples/sandwich_with_ivar_macro.rb

@@ -5,7 +5,7 @@ require "ivar"
 class SandwichWithIvarMacro
   include Ivar::Checked
 
-  # Pre-declare only instance variables that might be referenced before being set
+  # Declare instance variables that might be referenced before being set
   # You don't need to include variables that are always set in initialize
   ivar :@side
 
@@ -13,13 +13,13 @@ class SandwichWithIvarMacro
     @bread = "wheat"
     @cheese = "muenster"
     @condiments = %w[mayo mustard]
-    # NOTE: @side is not set here, but it's pre-initialized to nil
+    # @side is declared but intentionally not initialized here
   end
 
   def to_s
     result = "A #{@bread} sandwich with #{@cheese} and #{@condiments.join(", ")}"
-    # This won't trigger a warning because @side is pre-initialized
-    result += " and a side of #{@side}" if @side
+    # Using defined? to safely check for optional @side
+    result += " and a side of #{@side}" if defined?(@side) && @side
     result
   end
 

data/examples/sandwich_with_kwarg_init.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "ivar"
+
+class SandwichWithKwargInit
+  include Ivar::Checked
+
+  # Declare instance variables with keyword argument initialization
+  # and default values in case they're not provided
+  ivar :@bread, init: :kwarg, value: "wheat"
+  ivar :@cheese, init: :kwarg, value: "cheddar"
+
+  # Declare condiments with a default value
+  ivar :@condiments, value: []
+
+  # Declare pickles with both a default value and kwarg initialization
+  ivar :@pickles, value: false, init: :kwarg
+
+  def initialize(extra_condiments: [])
+    # The declared variables are already initialized with their values
+    # from keyword arguments or defaults
+    # Note: bread, cheese, and pickles keywords are "peeled off" and won't be passed to this method
+    # But extra_condiments will be passed through
+
+    # Add default condiments (clear first to avoid duplicates)
+    @condiments = []
+    @condiments << "mayo" unless @pickles
+    @condiments << "mustard"
+
+    # Add any extra condiments
+    @condiments.concat(extra_condiments)
+
+    # For demonstration, we'll print what keywords were actually received
+    received_vars = []
+    local_variables.each do |v|
+      next if v == :_ || binding.local_variable_get(v).nil?
+      received_vars << "#{v}: #{binding.local_variable_get(v).inspect}"
+    end
+    puts "  Initialize received: #{received_vars.join(", ")}"
+  end
+
+  def to_s
+    result = "A #{@bread} sandwich with #{@cheese}"
+    result += " and #{@condiments.join(", ")}" unless @condiments.empty?
+    result += " with pickles" if @pickles
+    result
+  end
+end
+
+# Create a sandwich with default values
+puts "Default sandwich:"
+sandwich = SandwichWithKwargInit.new
+puts sandwich
+# => "A wheat sandwich with cheddar and mayo, mustard"
+
+# Create a sandwich with custom bread and cheese
+puts "\nCustom bread and cheese:"
+custom_sandwich = SandwichWithKwargInit.new(bread: "rye", cheese: "swiss")
+puts custom_sandwich
+# => "A rye sandwich with swiss and mayo, mustard"
+
+# Create a sandwich with pickles
+puts "\nSandwich with pickles:"
+pickle_sandwich = SandwichWithKwargInit.new(pickles: true)
+puts pickle_sandwich
+# => "A wheat sandwich with cheddar and mustard with pickles"
+
+# Create a sandwich with extra condiments (not peeled off)
+puts "\nSandwich with extra condiments:"
+extra_sandwich = SandwichWithKwargInit.new(extra_condiments: ["ketchup", "relish"])
+puts extra_sandwich
+# => "A wheat sandwich with cheddar and mayo, mustard, ketchup, relish"
+
+# Create a sandwich with both peeled off and passed through kwargs
+puts "\nSandwich with both types of kwargs:"
+combo_sandwich = SandwichWithKwargInit.new(bread: "sourdough", pickles: true, extra_condiments: ["hot sauce"])
+puts combo_sandwich
+# => "A sourdough sandwich with cheddar and mustard, hot sauce with pickles"

data/examples/sandwich_with_positional_init.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "ivar"
+
+class SandwichWithPositionalInit
+  include Ivar::Checked
+
+  # Declare instance variables with positional argument initialization
+  # and default values in case they're not provided
+  ivar :@bread, init: :positional, value: "wheat"
+  ivar :@cheese, init: :positional, value: "cheddar"
+
+  # Declare condiments with a default value
+  ivar :@condiments, value: []
+
+  # Declare pickles with both a default value and positional initialization
+  ivar :@pickles, value: false, init: :positional
+
+  # Note: Don't define parameters for the peeled-off positional arguments
+  def initialize(extra_condiments = [])
+    # The declared variables are already initialized with their values
+    # from positional arguments or defaults
+    @condiments += extra_condiments unless extra_condiments.empty?
+
+    # We can also check if pickles were requested and adjust condiments
+    @condiments.delete("mayo") if @pickles
+  end
+
+  def to_s
+    result = "#{@bread} sandwich with #{@cheese} cheese"
+    result += " and pickles" if @pickles
+    result += ", condiments: #{@condiments.join(", ")}" unless @condiments.empty?
+    result
+  end
+end
+
+# Create a sandwich with all positional arguments
+sandwich1 = SandwichWithPositionalInit.new("rye", "swiss", true, ["mustard"])
+puts "Sandwich 1: #{sandwich1}"
+# => "Sandwich 1: rye sandwich with swiss cheese and pickles, condiments: mustard"
+
+# Create a sandwich with some positional arguments
+sandwich2 = SandwichWithPositionalInit.new("sourdough", "provolone", ["mayo", "mustard"])
+puts "Sandwich 2: #{sandwich2}"
+# => "Sandwich 2: sourdough sandwich with provolone cheese, condiments: mayo, mustard"
+
+# Create a sandwich with default values
+sandwich3 = SandwichWithPositionalInit.new
+puts "Sandwich 3: #{sandwich3}"
+# => "Sandwich 3: wheat sandwich with cheddar cheese"

data/examples/sandwich_with_shared_values.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "ivar"
+
+class SandwichWithSharedValues
+  include Ivar::Checked
+
+  # Declare multiple condiments with the same initial value (true)
+  ivar :@mayo, :@mustard, :@ketchup, value: true
+
+  # Declare bread and cheese with individual values
+  ivar "@bread": "wheat", "@cheese": "cheddar"
+
+  # Declare a variable without an initial value
+  ivar :@side
+
+  def initialize(options = {})
+    # Override any condiments based on options
+    @mayo = false if options[:no_mayo]
+    @mustard = false if options[:no_mustard]
+    @ketchup = false if options[:no_ketchup]
+
+    # Set the side if provided
+    @side = options[:side] if options[:side]
+  end
+
+  def to_s
+    result = "A #{@bread} sandwich with #{@cheese}"
+
+    condiments = []
+    condiments << "mayo" if @mayo
+    condiments << "mustard" if @mustard
+    condiments << "ketchup" if @ketchup
+
+    result += " with #{condiments.join(", ")}" unless condiments.empty?
+    result += " and a side of #{@side}" if defined?(@side) && @side
+    result
+  end
+end
+
+# Create a sandwich with default values (all condiments)
+sandwich = SandwichWithSharedValues.new
+puts sandwich
+# => "A wheat sandwich with cheddar with mayo, mustard, ketchup"
+
+# Create a sandwich with no mayo
+sandwich_no_mayo = SandwichWithSharedValues.new(no_mayo: true)
+puts sandwich_no_mayo
+# => "A wheat sandwich with cheddar with mustard, ketchup"
+
+# Create a sandwich with a side
+sandwich_with_side = SandwichWithSharedValues.new(side: "chips")
+puts sandwich_with_side
+# => "A wheat sandwich with cheddar with mayo, mustard, ketchup and a side of chips"

data/hooks/README.md

@@ -0,0 +1,42 @@
+# Git Hooks
+
+This directory contains Git hooks for the ivar project.
+
+## Available Hooks
+
+- **pre-commit**: Automatically checks and fixes linting issues before committing.
+
+## Installation
+
+To install the hooks, run:
+
+```bash
+./hooks/install.sh
+```
+
+This will copy the hooks to your local `.git/hooks` directory and make them executable.
+
+## Automatic Installation
+
+The hooks are automatically installed when you open the project in a devcontainer.
+
+## Manual Installation
+
+If you prefer to install the hooks manually, you can copy them to your `.git/hooks` directory:
+
+```bash
+cp hooks/pre-commit .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+## How the Pre-commit Hook Works
+
+The pre-commit hook:
+
+1. Identifies staged Ruby files
+2. Checks them for linting issues using standardrb
+3. If issues are found, attempts to automatically fix them
+4. Adds the fixed files back to the staging area
+5. Performs a final check to ensure all issues are fixed
+
+If any issues cannot be automatically fixed, the commit will be aborted with an error message.

data/hooks/install.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+# Create hooks directory if it doesn't exist
+mkdir -p .git/hooks
+
+# Copy pre-commit hook
+cp hooks/pre-commit .git/hooks/pre-commit
+
+# Make pre-commit hook executable
+chmod +x .git/hooks/pre-commit
+
+echo "Git hooks installed successfully!"

data/hooks/pre-commit

@@ -0,0 +1,54 @@
+#!/bin/sh
+
+# Get list of staged Ruby files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep "\.rb$")
+
+# Exit if no Ruby files are staged
+if [ -z "$STAGED_FILES" ]; then
+  echo "No Ruby files staged for commit. Skipping linting."
+  exit 0
+fi
+
+# Check if there are any linting issues
+echo "Checking for linting issues..."
+./script/lint $STAGED_FILES
+LINT_RESULT=$?
+
+# If there are linting issues, try to fix them automatically
+if [ $LINT_RESULT -ne 0 ]; then
+  echo "Linting issues found. Attempting to fix automatically..."
+
+  # Stash unstaged changes
+  git stash -q --keep-index
+
+  # Run de-lint to auto-fix
+  ./script/de-lint $STAGED_FILES
+  FIX_RESULT=$?
+
+  # If auto-fix was successful, add the fixed files back to staging
+  if [ $FIX_RESULT -eq 0 ]; then
+    echo "Auto-fix successful. Adding fixed files to staging area..."
+    git add $STAGED_FILES
+  else
+    echo "Auto-fix failed. Please fix the issues manually."
+    # Restore unstaged changes
+    git stash pop -q
+    exit 1
+  fi
+
+  # Restore unstaged changes
+  git stash pop -q 2>/dev/null || true
+fi
+
+# Run a final check to make sure everything is fixed
+echo "Running final linting check..."
+./script/lint $STAGED_FILES
+FINAL_RESULT=$?
+
+if [ $FINAL_RESULT -ne 0 ]; then
+  echo "Linting issues still exist after auto-fix. Please fix them manually."
+  exit 1
+fi
+
+echo "Linting passed. Proceeding with commit."
+exit 0

data/ivar.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.email = ["avdi@avdi.codes"]
 
   spec.summary = "Automatically check instance variables for typos."
-  spec.description = <<~EOF
+  spec.description = <<~DESCRIPTION
     Ruby instance variables are so convenient - you don't even need to declare them!
     But... they are also dangerous, because a mispelled variable name results in `nil`
     instead of an error.
@@ -22,11 +22,11 @@ Gem::Specification.new do |spec|
     dynamic, a little bit static. It doesn't encumber your instance variable reads and
     writes with any extra checking. And with the `:warn_once` policy, it won't overwhelm
     you with output.
-  EOF
+  DESCRIPTION
 
   spec.homepage = "https://github.com/avdi/ivar"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.4.0"
+  spec.required_ruby_version = ">= 3.3.0"
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
@@ -39,7 +39,8 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
       (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile]) ||
+        f.end_with?(".gem")
     end
   end
   spec.require_paths = ["lib"]

data/lib/ivar/check_all.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../ivar"
+
+# Enable automatic inclusion of Ivar::Checked in all classes and modules
+# defined within the project root.
+Ivar.check_all

data/lib/ivar/check_all_manager.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Ivar
+  # Manages automatic inclusion of Ivar::Checked in classes and modules
+  class CheckAllManager
+    def initialize
+      @trace_point = nil
+      @mutex = Mutex.new
+    end
+
+    # Enables automatic inclusion of Ivar::Checked in all classes and modules
+    # defined within the project root.
+    #
+    # @param project_root [String] The project root directory path
+    # @param block [Proc] Optional block. If provided, auto-checking is only active
+    #   for the duration of the block. Otherwise, it remains active indefinitely.
+    # @return [void]
+    def enable(project_root, &block)
+      disable if @trace_point
+      root_pathname = Pathname.new(project_root)
+      @mutex.synchronize do
+        # :end means "end of module or class definition" in TracePoint
+        @trace_point = TracePoint.new(:end) do |tp|
+          next unless tp.path
+          file_path = Pathname.new(File.expand_path(tp.path))
+          if file_path.to_s.start_with?(root_pathname.to_s)
+            klass = tp.self
+            next if klass.included_modules.include?(Ivar::Checked)
+            klass.include(Ivar::Checked)
+          end
+        end
+
+        @trace_point.enable
+      end
+
+      if block
+        begin
+          yield
+        ensure
+          disable
+        end
+      end
+
+      nil
+    end
+
+    # Disables automatic inclusion of Ivar::Checked in classes and modules.
+    # @return [void]
+    def disable
+      @mutex.synchronize do
+        if @trace_point
+          @trace_point.disable
+          @trace_point = nil
+        end
+      end
+    end
+
+    # Returns whether check_all is currently enabled
+    # @return [Boolean] true if check_all is enabled, false otherwise
+    def enabled?
+      @mutex.synchronize { !@trace_point.nil? && @trace_point.enabled? }
+    end
+
+    # Returns the current trace point (mainly for testing)
+    # @return [TracePoint, nil] The current trace point or nil if not enabled
+    def trace_point
+      @mutex.synchronize { @trace_point }
+    end
+  end
+end

data/lib/ivar/check_policy.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ivar
+  # Module for adding instance variable check policy configuration to classes.
+  # This module provides a way to set and inherit check policies for instance variables.
+  # When extended in a class, it allows setting a class-specific policy that overrides
+  # the global Ivar policy.
+  module CheckPolicy
+    # Set or get the check policy for this class
+    # @param policy [Symbol, Policy] The check policy to set
+    # @param options [Hash] Additional options for the policy
+    # @return [Symbol, Policy] The current check policy
+    def ivar_check_policy(policy = nil, **options)
+      if policy.nil?
+        @__ivar_check_policy || Ivar.check_policy
+      else
+        @__ivar_check_policy = options.empty? ? policy : [policy, options]
+      end
+    end
+
+    # Ensure subclasses inherit the check policy from their parent
+    # This method is called automatically when a class is inherited
+    # @param subclass [Class] The subclass that is inheriting from this class
+    def inherited(subclass)
+      super
+      subclass.instance_variable_set(:@__ivar_check_policy, @__ivar_check_policy)
+    end
+  end
+end

data/lib/ivar/checked/class_methods.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "instance_methods"
+
+module Ivar
+  module Checked
+    # Class methods added to the including class.
+    # These methods ensure proper inheritance of Checked functionality.
+    module ClassMethods
+      # Ensure subclasses inherit the Checked functionality
+      # This method is called automatically when a class is inherited
+      # @param subclass [Class] The subclass that is inheriting from this class
+      def inherited(subclass)
+        super
+        subclass.prepend(Ivar::Checked::InstanceMethods)
+      end
+    end
+  end
+end

data/lib/ivar/checked/instance_methods.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Ivar
+  module Checked
+    # Instance methods that will be prepended to the including class.
+    # These methods provide the core functionality for automatic instance variable validation.
+    module InstanceMethods
+      # The semantics of prepend are such that the super method becomes wholly inaccessible. So if we override a method
+      # (like, say, initialize), we have to stash the original method implementation if we ever want to find out its
+      # file and line number.
+      def self.prepend_features(othermod)
+        (instance_methods(false) | private_instance_methods(false)).each do |method_name|
+          Ivar.stash_method(othermod, method_name)
+        end
+        super
+      end
+
+      # Wrap the initialize method to automatically call check_ivars
+      # This method handles the initialization process, including:
+      # 1. Processing manifest declarations before calling super
+      # 3. Checking instance variables for validity
+      def initialize(*args, **kwargs, &block)
+        if @__ivar_skip_init
+          super
+        else
+          @__ivar_skip_init = true
+          manifest = Ivar.get_or_create_manifest(self.class)
+          manifest.process_before_init(self, args, kwargs)
+          super
+          check_ivars
+        end
+      end
+    end
+  end
+end