strict_ivars 0.6.0 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e1244d297abc3e3ade0882ca3a8767b63701c42721a7199803ad75b46c566ed
-  data.tar.gz: c141c19397e2942a40bb049ca77790ca9b29a6de9e0cd30e218162b1e51c4ee7
+  metadata.gz: b910c7decefccc4495a320886042153d9178c12f76cda7ccb549c304be2b6725
+  data.tar.gz: 8af1c060ed4ad3b1eef1b306c336a5bac415018f19bc73954e056bb47f9d86ce
 SHA512:
-  metadata.gz: 8cd2d471ca00c86a910843da2cacf803d71f30d48c946f469a5f18ef34c23b54d99d20897501a769695ff37114b677b8ce25c927a135876d99f1202324ad2e8f
-  data.tar.gz: ab6d3154078514bb0bd9615bae2cecdda743cb7a3dcd5f55d8571fae1f5201f94d090ebffd582881876f3b66bdcfd2035e4d600b77b7fa3350759f33deb4850a
+  metadata.gz: 957162900af7f34fe4e111065f8af1886327a3a3ae5ebdc8de4529869b02d4d71b1d2b27fdbf21ac5aba316e150463d990bdb4c065658b7381d599c520026a9b
+  data.tar.gz: 7748495c8e7a2e7cdddbd39b46bcb4e4d217db9b1f4f070fb810445f17b2fcd260356376ee5a7e936790410f83017dc0fdc232a69bdd1da8515204d39e8401ff

data/README.md

@@ -1,6 +1,35 @@
 # Strict Ivars
 
-Strict Ivars is a tiny pre-processor for Ruby that guards your instance variable reads, ensuring the instance variable is actually defined. This helps catch typos nice and early. It‘s especially good when used with [Literal](https://literal.fun).
+Strict Ivars is a tiny pre-processor for Ruby that guards your instance variable reads, ensuring the instance variable is actually defined. This helps catch typos nice and early. It‘s especially good when used with [Literal](https://literal.fun) and [Phlex](https://www.phlex.fun), though it also works with ERB.
+
+> [!NOTE]  
+> JRuby and TruffleRuby are not currently supported.
+
+## Setup
+
+Strict Ivars should be used in apps not libraries. Though you could use it in your library’s test suite.
+
+Install the gem by adding it to your `Gemfile` and running `bundle install`. You’ll probably want to set it to `require: false` here because you should require it manually at precisely the right moment.
+
+```ruby
+gem "strict_ivars", require: false
+```
+
+Now the gem is installed, you should require and initialize the gem as early as possible in your boot process. Ideally, this should be right after Bootsnap is set up. In Rails, this will be in your `boot.rb` file.
+
+```ruby
+require "strict_ivars"
+```
+
+You can pass an array of globs to `StrictIvars.init` as `include:` and `exclude:`
+
+```ruby
+StrictIvars.init(include: ["#{Dir.pwd}/**/*"], exclude: ["#{Dir.pwd}/vendor/**/*"])
+```
+
+This example include everything in the current directory apart from the `./vendor` folder (which is where GitHub Actions installs gems).
+
+If you’re using Bootsnap, you should clear your bootsnap cache by deleting the folder `tmp/cache/bootsnap`.
 
 ## How does it work?
 
@@ -24,8 +53,6 @@ end
 
 The replacement happens on load, so you never see this in your source code. It’s also always wrapped in parentheses and takes up a single line, so it won’t mess up the line numbers in exceptions.
 
-The real guard is a little uglier than this. It uses `::Kernel.raise` so it’s compatible with `BasicObject`. It also raises a `StrictIvars::NameError` with a helpful message mentioning the name of the instance variable, and that inherits from `NameError`, allowing you to rescue either `NameError` or `StrictIvars::NameError`.
-
 **Writes:**
 
 Strict Ivars doesn’t apply to writes, since these are considered the authoritative source of the instance variable definitions.
@@ -36,7 +63,7 @@ Strict Ivars doesn’t apply to writes, since these are considered the authorita
 
 **Or-writes:**
 
-This is considered a definition and not guarded.
+Or-writes are considered an authoritative definition, not a read.
 
 ```ruby
 @foo ||= 1
@@ -44,47 +71,67 @@ This is considered a definition and not guarded.
 
 **And-writes:**
 
-This is considered a definition and not guarded.
+And-writes are considered an authoritative definition, not a read.
 
 ```ruby
 @foo &&= 1
 ```
 
-## Setup
-
-Install the gem by adding it to your `Gemfile` and running `bundle install`.
+## Common issues
 
-You may want to set it to `require: false` here because you should require it manually at precisely the right moment.
+#### Implicitly depending on undefined instance variables
 
 ```ruby
-gem "strict_ivars", require: false
+def description
+  return @description if @description.present?
+  @description = get_description
+end
 ```
 
-Now the gem is installed, you should require and initialize the gem as early as possible in your boot process. Ideally, this should be right after Bootsnap is set up. In Rails, this will be in your `boot.rb` file.
+This example is relying on Ruby’s behaviour of returning `nil` for undefiend instance variables, which is completely unnecessary. Instead of using `present?`, we could use `defined?` here.
 
 ```ruby
-require "strict_ivars"
+def description
+  return @description if defined?(@description)
+  @description = get_description
+end
+```
 
-StrictIvars.init(include: ["#{Dir.pwd}/**/*"], exclude: ["#{Dir.pwd}/vendor/**/*"])
+Alternatively, as long as `get_description` doesn’t return `nil` and expect us to memoize it, we could use an “or-write” `||=`
+
+```ruby
+def description
+  @description ||= get_description
+end
 ```
 
-You can pass an array of globs to `include:` and `exclude:`.
+#### Rendering instance variables that are only set somtimes
 
-## Compatibility
+It’s common to render an instance variable in an ERB view that you only set on some controllers.
 
-Because Strict Ivars only transforms the source code that matches your include paths and becuase the check happens at runtime, it’s completely compatible with the rest of the Ruby ecosystem.
+```erb
+<div data-favourites="<%= @user_favourites %>"></div>
+```
 
-#### For apps
+The best solution to this to always set it on all controllers, but set it to `nil` in the cases where you don’t have anything to render. This will prevent you from making a typo in your views.
 
-Strict Ivars is really designed for apps, where you control the boot process and you want some extra safety in the code you and your team writes.
+Alternatively, you could update the view to be explicit about the fact this ivar may not be set.
 
-#### For libraries
+```erb
+<div data-favourites="<%= (@user_favourites ||= nil) %>"></div>
+```
 
-You could use Strict Ivars as a dev dependency in your gem’s test suite, but I don’t recommend initializing Strict Ivars in a library directly.
+Better yet, add a `defined?` check:
+
+```erb
+<% if defined?(@user_favourites) %>
+  <div data-favourites="<%= @user_favourites %>"></div>
+<% end %>
+```
 
 ## Performance
 
-#### Startup performance
+#### Boot performance
 
 Using Strict Ivars will impact startup performance since it needs to process each Ruby file you require. However, if you are using Bootsnap, the processed RubyVM::InstructionSequences will be cached and you probably won’t notice the incremental cache misses day-to-day.
 
@@ -92,12 +139,14 @@ Using Strict Ivars will impact startup performance since it needs to process eac
 
 In my benchmarks on Ruby 3.4 with YJIT, it’s difficult to tell if there is any performance difference with or without the `defined?` guards at runtime. Sometimes it’s about 1% faster with the guards than without. Sometimes the other way around.
 
-On my laptop, a method that returns an instance varible takes about 15ns and a method that checks if an instance varible is defined and then returns it takes about 15ns.
+On my laptop, a method that returns an instance varible takes about 15ns and a method that checks if an instance varible is defined and then returns it takes about 15ns. All this is to say, I don’t think there will be any measurable runtime performance impact, at least not in Ruby 3.4.
+
+#### Dynamic evals
 
-All this is to say, I don’t think there will be any measurable runtime performance impact.
+There is a small additional cost to dynamically evaluating code via `eval`, `class_eval`, `module_eval`, `instance_eval` and `binding.eval`. Dynamic evaluation usually only happens at boot time but it can happen at runtime depending on how you use it.
 
 ## Uninstall
 
 Becuase Strict Ivars only ever makes your code safer, you can always back out without anything breaking.
 
-To uninstall Strict Ivars, first remove the require and initialization code from wherever you added it and then remove the gem from your `Gemfile`. If you were using Bootsnap, there’s a good chance it cached some pre-processed code with the instance variable read guards in it. To clear this, you’ll need to delete your bootsnap cache, which should be in `tmp/cache/bootsnap`.
+To uninstall Strict Ivars, first remove the require and initialization code from wherever you added it and then remove the gem from your `Gemfile`. If you are using Bootsnap, there’s a good chance it cached some pre-processed code with the instance variable read guards in it. To clear this, you’ll need to delete your bootsnap cache, which should be in `tmp/cache/bootsnap`.

data/lib/strict_ivars/base_processor.rb

@@ -41,12 +41,12 @@ class StrictIvars::BaseProcessor < Prism::Visitor
 				@annotations.push(
 					[receiver_location.start_character_offset, "(#{receiver_local} = "],
 					[receiver_location.end_character_offset, ")"],
-					[location.start_character_offset, "*(::StrictIvars.process_eval_args(#{receiver_local}, :#{name}, "],
+					[location.start_character_offset, "*(::StrictIvars.__process_eval_args__(#{receiver_local}, :#{name}, "],
 					[location.end_character_offset, "))"]
 				)
 			else
 				@annotations.push(
-					[location.start_character_offset, "*(::StrictIvars.process_eval_args(self, :#{name}, "],
+					[location.start_character_offset, "*(::StrictIvars.__process_eval_args__(self, :#{name}, "],
 					[location.end_character_offset, "))"]
 				)
 			end

data/lib/strict_ivars/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StrictIvars
-	VERSION = "0.6.0"
+	VERSION = "1.0.0.rc1"
 end

data/lib/strict_ivars.rb

@@ -16,6 +16,16 @@ module StrictIvars
 
 	CONFIG = Configuration.new
 
+	# Initializes StrictIvars so that code loaded after this point will be
+	# guarded against undefined instance variable reads. You can pass an array
+	# of globs to `include:` and `exclude:`.
+	#
+	# ```ruby
+	# StrictIvars.init(
+	#   include: ["#{Dir.pwd}/**/*"],
+	#   exclude: ["#{Dir.pwd}/vendor/**/*"]
+	# )
+	# ```
 	#: (include: Array[String], exclude: Array[String]) -> void
 	def self.init(include: EMPTY_ARRAY, exclude: EMPTY_ARRAY)
 		CONFIG.include(*include) unless include.length == 0
@@ -35,7 +45,9 @@ module StrictIvars
 		end
 	end
 
-	def self.process_eval_args(receiver, method_name, *args)
+	# For internal use only. This method pre-processes arguments to an eval method.
+	#: (Object, Symbol, *untyped)
+	def self.__process_eval_args__(receiver, method_name, *args)
 		method = METHOD_METHOD.bind_call(receiver, method_name)
 		owner = method.owner
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strict_ivars
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0.rc1
 platform: ruby
 authors:
 - Joel Drapper