freezolite 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bed25358ffb5313cf2816282bc8a2e38516a283d7373987808c17d476962a07
-  data.tar.gz: 70c3a3a89ebbb11d3d8c81f40450124c0edfc20026e3deae1456ecde3bd09812
+  metadata.gz: 18bc2494d538e458f1ae9c25fd383df2d9b4c552b00d20680ada3c6ef0ad1b4b
+  data.tar.gz: b7adf7bff785d8a2968706f3229f60fdb2aefc59bfe5ce9c59aa165eb6f7410a
 SHA512:
-  metadata.gz: c41594c8e976f6df02aa30854ac9dc3dab9b601fe73e648946704d3107b046dee1c2e10a072e1bed5d35b6782e783e45e23a4b43ee0de1606a3c549b8c99605b
-  data.tar.gz: 8739d41c3cca71d36ff559de8e6ce5f25b51208af997ff2555ceaeb088bd47e2a2f404db7fe5f682e6c1699a7940d65a4d6faf205133072e842882a81be22ffa
+  metadata.gz: f1636d49db0a5fb812f1f95580ea4fec4742a96093e0bd14fa5b74567e15115190b1e0a23cb0d0666a639c8d01fcc16bcbf7f1a05b34fbc4e542fdf39a1cd535
+  data.tar.gz: 072207d396781631046c8bde02109528ecda9534475593950b7b18703344658efd560d79e931be1c9261f07111284d88f6a35089c35887b4cc1a55c416dff69c

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## master
 
+## 0.5.0 (2024-04-29)
+
+- Add constants freezing via the `# shareable_constant_value: ...` pragma. ([@palkan][])
+
+## 0.4.0 (2023-08-23)
+
+- Upgrade to `require-hooks` 0.2.0. ([@palkan][])
+
 ## 0.3.0 (2023-07-19)
 
 - Ignore `./vendor` by default when using `freezolite/auto`. ([@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.3.0"
+  VERSION = "0.5.0"
 end

data/lib/freezolite.rb

@@ -4,26 +4,32 @@ require "freezolite/version"
 
 module Freezolite
   class << self
-    attr_accessor :patterns, :exclude_patterns
+    attr_reader :experimental_freeze_constants
 
-    def setup(patterns:, exclude_patterns: nil)
-      self.patterns = patterns
-      self.exclude_patterns = exclude_patterns
+    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 do |path, &block|
-        next block.call unless patterns.any? { |pattern| File.fnmatch?(pattern, path) }
-        next block.call if exclude_patterns&.any? { |pattern| File.fnmatch?(pattern, path) }
+      ::RequireHooks.around_load(patterns: patterns, exclude_patterns: exclude_patterns) do |path, &block|
+        was_frozen_string_literal = ::RubyVM::InstructionSequence.compile_option[:frozen_string_literal]
+        ::RubyVM::InstructionSequence.compile_option = {frozen_string_literal: true}
+        block.call
+      ensure
+        ::RubyVM::InstructionSequence.compile_option = {frozen_string_literal: was_frozen_string_literal}
+      end
 
-        begin
-          was_frozen_string_literal = ::RubyVM::InstructionSequence.compile_option[:frozen_string_literal]
-          ::RubyVM::InstructionSequence.compile_option = {frozen_string_literal: true}
-          block.call
-        ensure
-          ::RubyVM::InstructionSequence.compile_option = {frozen_string_literal: was_frozen_string_literal}
+      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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Vladimir Dementyev
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-19 00:00:00.000000000 Z
+date: 2024-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: require-hooks
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -88,7 +88,7 @@ metadata:
   documentation_uri: https://github.com/ruby-next/freezolite
   homepage_uri: https://github.com/ruby-next/freezolite
   source_code_uri: https://github.com/ruby-next/freezolite
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -103,8 +103,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.8
-signing_key:
+rubygems_version: 3.4.19
+signing_key: 
 specification_version: 4
 summary: Example description
 test_files: []