freezolite 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba7e6d9681a85534191c401f217c1d8f184dc86d1f2ac520972352db9d4b7f47
-  data.tar.gz: 4f92015d4bb62e597f707dc2fc512730bbeb2c06fc652f6b3b20b9bfaa38379c
+  metadata.gz: acdc74401331aa64455f0c39ae90d0e770c458d90c373ed4b295079c60357357
+  data.tar.gz: 2bd75df12e02beb4fab14c454264f6512c903155d873fc5e52b182da3be96770
 SHA512:
-  metadata.gz: 71499e074c60a508d907b0fa2e983ad870668fa74430bee8fcc06cbe34ed1d591ae5b6f86e9e0d71d2571d963263a8ad028f745c7be01f2d7b733f09d11a03e2
-  data.tar.gz: fb213aaa5f7677908f65154888cb511883ef3e97a2a59b53a7831c8dfc2e9e3a0e9244e465a09677645fd62e6e3d15c1fa45c6a6c41a227e61b60c1e4eadaf09
+  metadata.gz: a2907ed214bafd60f15c43144ecf7529799eb21d060f82ddeea1c05ef06c835ce5ccb71e705f6e861c762f26e5a0f9daf0440091b40095843d5ed17c2426ecb2
+  data.tar.gz: 86bcac5bafdabc27728a410b802c6f69ca6bf9481061db49c1fb97241e14859ed4952df85000d1fc5948f3ba46be5f57f1c0d85e7e8bb30c70b021b53ccb0f10

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## master
 
+## 0.6.0 (2025-03-07)
+
+- Ruby 3.4 support. ([@palkan][])
+
+## 0.5.0
+
+- Add constants freezing via the `# shareable_constant_value: ...` pragma. ([@palkan][])
+
 ## 0.4.0 (2023-08-23)
 
 - Upgrade to `require-hooks` 0.2.0. ([@palkan][])

data/README.md

@@ -5,7 +5,11 @@
 
 Tired of adding `# frozen_string_literals: true` to every file in your project or running `rubocop -A` to make it do that for you? What if I told you that you can just add a single gem to your project and activate this option **for the project's files** automatically (without enabling it globally)?
 
-Freezolite is a gem that turn the `frozen_string_literal` compile option on only for the specified files. Thus, it's like running Ruby with `--enable=frozen-string-literal` but only for the files you own.
+Freezolite is a gem that turns the `frozen_string_literal` compile option on only for the specified files. Thus it's like running Ruby with `--enable=frozen-string-literal` but only for the files you own.
+
+> 📖 Read more about the motivation behind this project in ["Freezolite: the magic gem for keeping Ruby literals safely frozen"](https://evilmartians.com/chronicles/freezolite-the-magic-gem-for-keeping-ruby-literals-safely-frozen) post.
+
+Freezolite also comes with experimental support for [freezing constants](#freezing-constants).
 
 ## Usage
 
@@ -15,7 +19,7 @@ Add the gem to your Gemfile:
 gem "freezolite"
 ```
 
-And drop the following line to your application entry-point **after loading dependencies** and before loading your application code. For example, in Rails, you can put it to `config/application.rb` after the `Bundler.require(...)` call:
+And drop the following line into your application entry-point **after loading dependencies** and before loading your application code. For example, in Rails, you can put it in `config/application.rb` after the `Bundler.require(...)` call:
 
 ```ruby
 # config/application.rb
@@ -40,12 +44,30 @@ Freezolite.setup(
 )
 ```
 
-**NOTE**: When using auto mode, the `<project-root>/vendor/bundle` folder is excluded automatically. In manual mode, you may want to exclude it yourself.
+> [!NOTE]
+> When using auto mode, the `<project-root>/vendor/bundle` folder is excluded automatically. In manual mode, you may want to exclude it yourself.
 
 ### Using with Bootsnap
 
 Freezolite is compatible with Bootsnap. Just make sure you require it **after** Bootsnap. No manual cache invalidation required.
 
+### Freezing constants
+
+Ruby 3 introduced a new pragma—[`# shareable_constant_value: ...`](https://bugs.ruby-lang.org/issues/17273). It's meant to be used with Ractor-driven applications to easily turn constants into Ractor-shareable objects within a source file. Making Ractor-shareable implies **deep freezing**, thus, we can leverage this pragma to automatically freeze constants!
+
+Freezolite can automatically inject this pragma for you (only for matching files, similarly to frozen literals). You need to opt-in to enable this feature:
+
+```ruby
+require "freezolite"
+# You can also specify specific values, such as literal, experimental_copy, etc.
+# Setting to `true` is equal to the `literal` value.
+Freezolite.experimental_freeze_constants = true
+require "freezolite/auto" # or setup manually
+```
+
+> [!NOTE]
+> This feature is considered experimental for the following reasons: 1) the pragma itself is not widely used and we still need to learn how to use it in our applications; 2) unlike `# frozen_string_literal`, this setting is not a compiler option but a parser context switch; thus, we have to use source transform here, and literally add a line to the source file, thus, breaking the line numbers in your stack traces, etc.
+
 ### Supported Ruby versions
 
 - Ruby (MRI) >= 2.7.0

data/lib/freezolite/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Freezolite # :nodoc:
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

data/lib/freezolite.rb

@@ -4,16 +4,32 @@ require "freezolite/version"
 
 module Freezolite
   class << self
+    attr_reader :experimental_freeze_constants
+
+    def experimental_freeze_constants=(val)
+      @experimental_freeze_constants = (val == true) ? :literal : val
+    end
+
     def setup(patterns:, exclude_patterns: nil)
       require "require-hooks/setup"
 
       ::RequireHooks.around_load(patterns: patterns, exclude_patterns: exclude_patterns) do |path, &block|
-        was_frozen_string_literal = ::RubyVM::InstructionSequence.compile_option[:frozen_string_literal]
+        was_frozen_string_literal = ::RubyVM::InstructionSequence.compile_option[:frozen_string_literal] || false
         ::RubyVM::InstructionSequence.compile_option = {frozen_string_literal: true}
         block.call
       ensure
         ::RubyVM::InstructionSequence.compile_option = {frozen_string_literal: was_frozen_string_literal}
       end
+
+      if experimental_freeze_constants
+        val = experimental_freeze_constants
+        RequireHooks.source_transform(patterns: patterns, exclude_patterns: exclude_patterns) do |path, source|
+          source ||= File.read(path)
+          "# shareable_constant_value: #{val}\n#{source}"
+        end
+      end
     end
   end
+
+  self.experimental_freeze_constants = false
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: freezolite
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Vladimir Dementyev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-23 00:00:00.000000000 Z
+date: 2025-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: require-hooks
@@ -103,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.8
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Example description