ivar 0.2.0 → 0.4.6

data/README.md

@@ -1,343 +1,408 @@
 # Ivar
 
-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.
+Ivar is a Ruby gem that automatically checks for typos in instance variables.
 
-Why not have the best of both worlds? Ivar lets you use plain-old instance variables, and automatically checks for typos.
-
-Ivar waits until an instance is created to do the checking, then uses Prism to look for variables that don't match what was set in initialization. So it's a little bit 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.
-
-
-## Usage
-
-### Manual Validation
+## Synopsis
 
 ```ruby
-# sandwich.rb
-require "ivar"
+require "ivar/check_all" if $VERBOSE
 
-class Sandwich
-  include Ivar::Validation
-
-  def initialize
-    @bread = "wheat"
-    @cheese = "muenster"
-    @condiments = ["mayo", "mustard"]
-    check_ivars(add: [:@side])
+class Pizza
+  def initialize(toppings)
+    @toppings = toppings
   end
 
   def to_s
-    "A #{@bread} sandwich with #{@chese} and #{@condiments.join(", ")}" \
-    (@side ? "and a side of #{@side}" : "")
+    "A pizza with #{@topings.join(", ")}"
   end
 end
 
-Sandwich.new
+Pizza.new(["pepperoni", "mushrooms"])
 ```
 
 ```shell
-$ ruby sandwich.rb -w
-sandwich.rb:22: warning: unknown instance variable @chese. Did you mean: @cheese?
+$ ruby -w pizza.rb
+pizza.rb:10: warning: unknown instance variable @topings. Did you mean: @toppings?
 ```
 
-### Automatic Validation (Every Instance)
+## Introduction
 
-```ruby
-# sandwich_automatic.rb
-require "ivar"
+> OK I read the synopsis but I don't get it.
 
-class Sandwich
-  include Ivar::Checked
+That's because what Ivar does seems so basic that it's almost a surprise it isn't part of the language. Do you see that warning about an unkown instance variable? That's Ivar, helping you avoid a bug.
 
-  def initialize
-    @bread = "white"
-    @cheese = "havarti"
-    @condiments = ["mayo", "mustard"]
-    # no need for explicit check_ivars call
-  end
+> Oh! Because in Ruby, any unset instance variable ("ivar") you reference just returns `nil`, with no error or warning.
 
-  def to_s
-    "A #{@bread} sandwich with #{@chese} and #{@condiments.join(", ")}"
+Exactly.
+
+> Yeah what's up with that anyway.
+
+It's actually one of the conveniences of the language: when you realize you need to store a field you just do it, without having to go back and declare it somewhere else in the class:
+
+```ruby
+class MyClass
+  # ...
+  def increment_usage_count!
+    (@usage_count ||= 0) += 1
   end
+  # ...
 end
-
-Sandwich.new
 ```
 
-```shell
-$ ruby sandwich_automatic.rb -w
-sandwich_automatic.rb:15: warning: unknown instance variable @chese. Did you mean: @cheese?
+> Right but there is no protection against typos.
+
+Also true. If we later do this:
+
+```ruby
+class MyClass
+  # ...
+  def usage_count
+    @usag_count
+  end
+  # ...
+end
 ```
 
-The `Checked` module automatically calls `check_ivars` after initialization, which means it will emit warnings for every instance of the class.
+...there's nothing to tell us we got the variable wrong.
 
-### Automatic Validation (Once Per Class)
+> I thought that's why we're supposed to use attr_reader and friends.
 
-Too many warnings? Try this:
+Yes, this is why a lot of people recommend using `attr_reader`/`_writer`/`attr_accessor` pervasively. Only ever reading or writing ivars through accessors. But this gives up the convenience, informality, and conciseness of Ruby's instance variables. And it also puts you at risk of Ruby's all-time favorite gotcha: forgetting to put `self.` in front a setter call.
 
 ```ruby
-# sandwich_once.rb
-require "ivar"
+class MyClass
+  attr_accessor :usage_count
 
-class Sandwich
-  include Ivar::Checked
-  ivar_check_policy :warn_once
-
-  def initialize
-    @bread = "white"
-    @cheese = "havarti"
-    @condiments = ["mayo", "mustard"]
-    # no need for explicit check_ivars call
+  def increment_usage_count!
+    usage_count += 1  # oops, incremented a local, not the ivar
   end
+end
+```
 
-  def to_s
-    "A #{@bread} sandwich with #{@chese} and #{@condiments.join(", ")}"
+> Ouch, bad memories.
+
+Yeah. Personally I've gone through phases with this. For many years I followed and advocated the advice to use accessors everywhere. But lately I've kind of gone back to my roots on using unadorned ivars directly when I'm not setting up a public interface.
+
+Then I ran into Joel Drapper's [`strict_ivars`](https://github.com/joeldrapper/strict_ivars) gem and it got my wheels turning. I preferred a warning to a hard error, and I didn't necessarily want to have to change methods that intentionally referenced unset ivars. It got me wondering, though: what would it look like to have Ruby warn about possible typos in ivar names, the same way it warns about other potential oopsies? What even would the heuristic be to determine if an ivar reference might be a typo?
+
+> Well obviously you found a way to do it. What heuristics does Ivar use?
+
+At the moment there are two ways to give an ivar the stamp of approval. The first is the most un-intrusive: set it in the initializer.
+
+> Oh, like in that first example, you set `@toppings` in the initializer.
+
+```ruby
+require "ivar/check_all" if $VERBOSE
+
+class Pizza
+  def initialize(toppings)
+    @toppings = toppings
   end
+  # ...
 end
 
-Sandwich.new
 ```
 
-```shell
-$ ruby sandwich_once.rb -w
-sandwich_once.rb:15: warning: unknown instance variable @chese. Did you mean: @cheese?
-```
-
-Setting `ivar_check_policy :warn_once` makes `check_ivars` use the `warn_once` policy, which means it will emit warnings only for the first instance of each class.
+Exactly.
 
-### Pre-declaring Instance Variables
+> And then what... spooky magic happens?
 
-Normally we "declare" variables by setting them in `initialize`. But if you don't have any reason to set them in the initializer, you can still declare them so they won't be flagged.
+Well, let's use a slightly more explicit version.
 
 ```ruby
-# sandwich_with_ivar_macro.rb
 require "ivar"
 
-class SandwichWithIvarMacro
+class Pizza
   include Ivar::Checked
 
-  # Pre-declare only instance variables that might be referenced before being set
-  # You don't need to include variables that are always set in initialize
-  ivar :@side
-
-  def initialize
-    @bread = "wheat"
-    @cheese = "muenster"
-    @condiments = ["mayo", "mustard"]
-    # Note: @side is not set here, but it's pre-initialized to nil
+  def initialize(toppings)
+    @toppings = toppings
   end
+  # ...
+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
-    result
-  end
+That's what `ivar/check_all` implicitly does under the hood: adds `Ivar::Checked` to classes.
+
+> Which does what, exactly?
+
+Let's use an even more explicit version to demonstrate:
+
+```ruby
+require "ivar"
 
-  def add_side(side)
-    @side = side
+class Pizza
+  include Ivar::Validation
+
+  def initialize(toppings)
+    @toppings = toppings
+    check_ivars
   end
+  # ...
 end
+```
 
-sandwich = SandwichWithIvarMacro.new
-puts sandwich.to_s  # No warning about @side
+> So `check_ivars` is the magic method that does the checking?
 
-sandwich.add_side("chips")
-puts sandwich.to_s
-```
+Exactly. `Ivar::Checked` just arranges to automatically call it after your `initialize` methods finish.
+
+> And what, precisely, does `check_ivars` do?
+
+Well, it first notes all currently set ivars, and stamps them as "known". Then it kicks off a just-in-time static analysis of the class using [Prism](https://github.com/ruby/prism), to find all ivar references. And then it compares the two lists and generates warnings for any references that don't match a known ivar.
+
+> And it does this when an instance is created?
 
-Note: this WILL set the variable to `nil` before `initialize` runs, so if you have code that depends on `defined?(@var)` it may break. If folks want it we might look into non-setting predeclaration.
+Yep!
 
-### Setting ivars from initializer keyword arguments
+> OK I have some concerns about that but I'll save them for later. My next question is: what if I want to use an ivar without first initializing it in the `initialize` method?
 
-While we're messing around with ivars, let's fix Ruby's oldest missing convenience feature:
+Well, if you're using the explicit `check_ivars` version you can stamp some additional ivars as "known" by passing them in as an argument:
 
 ```ruby
-# sandwich_with_kwarg.rb
 require "ivar"
 
-class SandwichWithKwarg
-  include Ivar::Checked
-
-  ivar kwarg: [:@bread, :@cheese, :@condiments, :@pickles, :@side]
+class Pizza
+  include Ivar::Validation
 
-  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
+  def initialize(toppings)
+    @toppings = toppings
+    check_ivars(add: [:@extra_cheese])
   end
+  # ...
 end
+```
 
-# Create a sandwich with keyword arguments
-sandwich = SandwichWithKwarg.new(
-  bread: "wheat",
-  cheese: "muenster",
-  condiments: ["mayo", "mustard"],
-  side: "chips"
-)
+But the canonical way to do it is with the `ivar` macro:
 
-puts sandwich.to_s  # Outputs: A wheat sandwich with muenster and mayo, mustard and a side of chips
-```
+```ruby
+require "ivar"
 
-Ta-da, no more tedious setting of instance variables from arguments of the same name.
+class Pizza
+  include Ivar::Checked
 
-TODO: Find a positional args version of this that makes sense.
+  ivar :@minutes_waiting
 
-### Inheritance
+  def increment_wait_time
+    (@minutes_waiting ||= 0) += 1
+  end
+  # ...
+end
+```
 
-This stuff works with inheritance:
+This is purely a declaration: the variable will not be set. But as a convenience, you *can* also initialize it with a value:
 
 ```ruby
-class BaseSandwich
+require "ivar"
+
+class Pizza
   include Ivar::Checked
 
-  # Pre-declare only variables that might be referenced before being set
-  # Variables set in initialize (@bread, @cheese) don't need to be pre-declared
-  ivar :@optional_topping
+  ivar :@minutes_waiting, value: 0
 
-  def initialize
-    @bread = "wheat"
-    @cheese = "muenster"
+  def increment_wait_time
+    @minutes_waiting += 1
   end
+  # ...
 end
+```
 
-class SpecialtySandwich < BaseSandwich
-  # Add more pre-declared instance variables as needed
-  # @condiments is set in initialize, so it doesn't need to be pre-declared
-  ivar :@special_sauce
+> Can I initialize it with a different value for each instance?
 
-  def initialize
-    super
-    @condiments = ["mayo", "mustard"]
-  end
+Yes, you can pass a block that generates the value:
 
-  def to_s
-    result = "A #{@bread} sandwich with #{@cheese} and #{@condimants.join(", ")}"
-    # @special_sauce is pre-declared, so this won't trigger a warning
-    result += " with #{@special_sauce}" if @special_sauce
-    # @optional_topping is inherited from the parent class
-    result += " and #{@optional_topping}" if @optional_topping
-    result
-  end
-end
+```ruby
+require "ivar"
 
-SpecialtySandwich.new
-```
+class Pizza
+  include Ivar::Checked
 
-```shell
-$ ruby inheritance_example.rb -w
-inheritance_example.rb:17: warning: unknown instance variable @condimants. Did you mean: @condiments?
+  ivar(:@order_time) { Time.now }
+  # ...
+end
 ```
 
-## Checking Policies
+This block will be passed the ivar name as an argument, if you want to do something fancy like share one dynamic initialization block between multiple ivars:
 
-Ivar supports different policies for handling unknown instance variables. You can specify a policy at the global level, class level, or per-check level.
+```ruby
+require "ivar"
 
-### Available Policies
+class Pizza
+  include Ivar::Checked
 
-- `:warn` - Emit warnings for all unknown instance variables (default)
-- `:warn_once` - Emit warnings only once per class
-- `:raise` - Raise an exception for unknown instance variables
-- `:log` - Log unknown instance variables to a logger
+  ivar :@order_time, :@delivery_time do |ivar_name|
+   Time.now + (ivar_name == :@order_time ? 0 : 30)
+  end
+  # ...
+end
+```
 
-### Setting a Global Policy
+Which, yes, you can declare multiple ivars in one `ivar` call, if you want. You can also split them between individual `ivar` declarations.
+
+> But what if I want to initialize an ivar from a constructor argument? Do I need to go back to the `initialize` method for that?
+
+No you don't! One of the coolest conveniences that `ivar` adds is the ability to mark an ivar as initializable from a constructor argument:
 
 ```ruby
-# Set the global policy to raise exceptions
-Ivar.check_policy = :raise
+require "ivar"
 
 class Sandwich
-  include Ivar::Validation
+  include Ivar::Checked
 
-  def initialize
-    @bread = "wheat"
-    check_ivars
-  end
+  ivar :@bread, init: :kwarg
+  ivar :@cheese, init: :kwarg
+  ivar :@condiments, init: :kwarg
 
   def to_s
-    "A #{@bread} sandwich with #{@chese}"  # This will raise an exception
+    "A #{@bread} sandwich with #{@cheese} and #{@condiments.join(", ")}"
   end
 end
 
-Sandwich.new  # Raises: NameError: test_file.rb:2: unknown instance variable @chese. Did you mean: @cheese?
+s = Sandwich.new(bread: "wheat", cheese: "muenster", condiments: ["mayo"])
+s.to_s  # => "A wheat sandwich with muenster and mayo"
 ```
 
-### Setting a Class-Level Policy
+Notice the lack of an initialize method, and the lack of the usual Ruby repetition of `@ivar_name = ivar_name`.
+
+> Whoah.
+
+Right??? Oh yeah we've got positional arguments too if you like those better.
 
 ```ruby
-class Sandwich
-  include Ivar::Validation
-  extend Ivar::CheckPolicy
+require "ivar"
 
-  # Set the class-level policy to log
-  ivar_check_policy :log, logger: Logger.new($stderr)
+class Sandwich
+  include Ivar::Checked
 
-  def initialize
-    @bread = "wheat"
-    check_ivars
-  end
+  ivar :@bread, init: :arg
+  ivar :@cheese, init: :arg
+  ivar :@condiments, init: :arg
 
   def to_s
-    "A #{@bread} sandwich with #{@chese}"  # This will log a warning
+    "A #{@bread} sandwich with #{@cheese} and #{@condiments.join(", ")}"
   end
 end
 
-Sandwich.new  # Logs: W, [2023-06-01T12:34:56.789123 #12345] WARN -- : test_file.rb:2: unknown instance variable @chese. Did you mean: @cheese?
+s = Sandwich.new("wheat", "muenster", ["mayo"])
+s.to_s  # => "A wheat sandwich with muenster and mayo"
 ```
 
-### Setting a Per-Check Policy
+> What if I also want external accessor methods?
+
+Gotcha covered.
 
 ```ruby
-class Sandwich
-  include Ivar::Validation
+require "ivar"
 
-  def initialize
-    @bread = "wheat"
-    # Use the raise policy for this check
-    check_ivars(policy: :raise)
-  end
+class Sandwich
+  include Ivar::Checked
 
-  def to_s
-    "A #{@bread} sandwich with #{@chese}"
-  end
+  ivar :@bread, init: :kwarg, reader: true
+  ivar :@cheese, init: :kwarg, reader: true
+  ivar :@condiments, init: :kwarg, accessor: true
 end
 
-Sandwich.new  # Raises: NameError: test_file.rb:2: unknown instance variable @chese. Did you mean: @cheese?
+s = Sandwich.new(bread: "wheat", cheese: "muenster", condiments: ["mayo"])
+s.bread  # => "wheat"
+s.cheese  # => "muenster"
+s.condiments = ["mustard"]
+s.condiments  # => ["mustard"]
 ```
 
-### Using the Checked Module with Policies
+> This seems like it's more than just about detecting ivar typos at this point.
+
+Yeah, well, I knew that in order to determine typos I'd have to have some kind of declaration mechanism. And once I have that, I might as well make it useful. And use it to gain back some of the convenience lost to having to write the declaration in the first place.
+
+> Fair enough.
+
+Any other questions?
+
+> What about inheritance? Can I use these tools in both parent and child clases?
 
-The `Checked` module sets a default policy:
+Yes, `ivar` goes to a fair amount of trouble to "just work" in ways you'll (hopefully) expect when it comes to inheritance.
 
-- `Checked` sets the policy to `:warn`
+More questions?
 
-You can override the default policy:
+> Well, earlier you said that checking happens at object-instantiation time. Does this mean I'm going to be flooded with warnings if my code creates a lot of instances?
+
+Excellent question! No, not out of the box. The default policy (`:warn_once`) is to warn only once per class, not per instance.
+
+> Are there other policies?
+
+Yeah, there's `:warn` for warning every time; `:log` for logging warnings, `:raise` for raising an exception, and `:none` for no checking at all.
+
+Policies can be set program-wide:
 
 ```ruby
-class Sandwich
+require "ivar"
+Ivar.check_policy = :log
+```
+
+...or on a per-class basis:
+
+```ruby
+require "ivar"
+
+class Pizza
   include Ivar::Checked
+  ivar_check_policy :none
+  # ...
+end
+```
 
-  # Override the default policy
-  ivar_check_policy :raise
+...or when invoking `check_ivars`:
 
-  def initialize
-    @bread = "wheat"
-  end
+```ruby
+require "ivar"
 
-  def to_s
-    "A #{@bread} sandwich with #{@chese}"  # This will raise an exception
+class Pizza
+  include Ivar::Validation
+
+  def initialize(toppings)
+    @toppings = toppings
+    check_ivars(policy: :raise)
   end
+  # ...
 end
+```
+
+You can check out the source code for more details about check policies.
+
+> I still have some questions. Specifically... what exactly is going on behind the scenes with `ivar/check_all`? That seems... spooky.
+
+Yeah. So when you require `ivar/check_all`, what you're doing is invoking `Ivar.check_all`.
+
+This sets up a TracePoint that watches for class and module definitions. When it detects one, it includes `Ivar::Checked` into that the class or module.
+
+> Wait so it infects every single class I load?
+
+Not quite. It tries pretty hard to only do it for code from your project; not for stuff from gems or the standard library.
+
+> Doesn't a TracePoint have a performance impact?
+
+Yeah probably. That's why I don't necessarily recommend `ivar/check_all` for production use. But there are a couple of alternatives. For one, you can do it like we had in the opening example: only load it when `$VERBOSE` is true.
 
-Sandwich.new  # Raises: NameError: test_file.rb:2: unknown instance variable @chese. Did you mean: @cheese?
+```ruby
+require "ivar/check_all" if $VERBOSE
+```
+
+Or, you can use the block form of `Ivar.check_all`, which will only enable checking for classes defined within the block.
+
+```ruby
+require "ivar"
+
+Ivar.check_all do
+  # load your code here
+end
 ```
 
-# Acknowledgements
+With this version the tracepoint will only be active for the duration of the `check_all` block.
+
+## Acknowledgements
+
+Thanks first to [Joel Draper](https://github.com/joeldrapper) for creating [strict_ivars](https://github.com/joeldrapper/strict_ivars), which inspired this gem. If `ivar` isn't quite what you're looking for, check out `strict_ivars` instead!
 
-Thank you to Joel Drapper, for inspiring me with his 
+Thanks also to [Augment Code](https://www.augmentcode.com/), which served as my "hands" for building this. I'm not at a point in my life where I can actually afford the time to build random passion projects, so this project wouldn't exist without help from the robot.
 
-# TODO
+## Contribution
 
-- Pre-declare "ghost" variables without setting them
-- Add a module for dynamic checking of instance_variable_get/set
+Contributions are welcome! Fair warning, if I accept a bunch of your PRs I may nominate you as a maintainer. I know my limits: I'm better at kicking off projects than at maintaining them.

data/Rakefile

@@ -6,7 +6,7 @@ require "rake/testtask"
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
+  t.test_files = FileList["test/**/test_*.rb"].exclude("test/fixtures/**/*")
 end
 
 require "standard/rake"

data/VERSION.md

@@ -0,0 +1,46 @@
+# Versioning and Release Process
+
+This project follows [Semantic Versioning](https://semver.org/) (SemVer).
+
+## Version Numbers
+
+Version numbers are in the format `MAJOR.MINOR.PATCH`:
+
+- **MAJOR**: Incremented for incompatible API changes
+- **MINOR**: Incremented for new functionality in a backward-compatible manner
+- **PATCH**: Incremented for backward-compatible bug fixes
+
+## Release Process
+
+To release a new version:
+
+1. Make sure all changes are documented in the `CHANGELOG.md` file under the "Unreleased" section
+2. Run the release script with the appropriate version bump type:
+   ```
+   script/release [major|minor|patch] [options]
+   ```
+
+   Available options:
+   - `--yes` or `-y`: Skip confirmation prompt
+   - `--no-push`: Skip pushing changes to remote repository
+
+3. The script will:
+   - Run tests and linter to ensure everything is working
+   - Update the version number in `lib/ivar/version.rb`
+   - Update the `CHANGELOG.md` file with the new version and date
+   - Commit these changes
+   - Create a git tag for the new version
+   - Push the changes and tag to GitHub (unless `--no-push` is specified)
+4. The GitHub Actions workflow will automatically:
+   - Build the gem
+   - Run tests
+   - Publish the gem to RubyGems.org
+
+## Setting Up RubyGems API Key
+
+To allow GitHub Actions to publish to RubyGems.org, you need to add your RubyGems API key as a secret:
+
+1. Get your API key from RubyGems.org (account settings)
+2. Go to your GitHub repository settings
+3. Navigate to "Secrets and variables" → "Actions"
+4. Add a new repository secret named `RUBYGEMS_API_KEY` with your RubyGems API key as the value