freezolite 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba7e6d9681a85534191c401f217c1d8f184dc86d1f2ac520972352db9d4b7f47
-  data.tar.gz: 4f92015d4bb62e597f707dc2fc512730bbeb2c06fc652f6b3b20b9bfaa38379c
+  metadata.gz: 18bc2494d538e458f1ae9c25fd383df2d9b4c552b00d20680ada3c6ef0ad1b4b
+  data.tar.gz: b7adf7bff785d8a2968706f3229f60fdb2aefc59bfe5ce9c59aa165eb6f7410a
 SHA512:
-  metadata.gz: 71499e074c60a508d907b0fa2e983ad870668fa74430bee8fcc06cbe34ed1d591ae5b6f86e9e0d71d2571d963263a8ad028f745c7be01f2d7b733f09d11a03e2
-  data.tar.gz: fb213aaa5f7677908f65154888cb511883ef3e97a2a59b53a7831c8dfc2e9e3a0e9244e465a09677645fd62e6e3d15c1fa45c6a6c41a227e61b60c1e4eadaf09
+  metadata.gz: f1636d49db0a5fb812f1f95580ea4fec4742a96093e0bd14fa5b74567e15115190b1e0a23cb0d0666a639c8d01fcc16bcbf7f1a05b34fbc4e542fdf39a1cd535
+  data.tar.gz: 072207d396781631046c8bde02109528ecda9534475593950b7b18703344658efd560d79e931be1c9261f07111284d88f6a35089c35887b4cc1a55c416dff69c

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 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][])

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.5.0"
 end

data/lib/freezolite.rb

@@ -4,6 +4,12 @@ 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"
 
@@ -14,6 +20,16 @@ module Freezolite
       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.5.0
 platform: ruby
 authors:
 - Vladimir Dementyev
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-08-23 00:00:00.000000000 Z
+date: 2024-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: require-hooks
@@ -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: []