use_context 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fefdb2f5210efd1e2cc56fe41dc465cb61aa711fc658f29d606221335dfcaa51
+  data.tar.gz: 4e429a7afe8d22962dc58109379fbf85cc8135d1713ed1d30b25ce7f16fa1222
+SHA512:
+  metadata.gz: c05082dfc9a79b6f92504d2f1a5928abae3b3fb7d2c38fba6c8c617031d80e0afe5d93dd21c4fe2d07e8fef00420c68fc6e3da824813e762f6f8cae439ce1ad1
+  data.tar.gz: fe5474e402f9bf88b3d1f9738c46b2cb07884adee0cfd9314c5a6273a959a93169375b7097a068b867f30bf421e86af447393ec43756a6b2a0e3cab583616358

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+# 1.0.0
+* Birthday!

data/Gemfile

@@ -0,0 +1,12 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "rake"
+  gem "debug"
+end
+
+group :test do
+  gem "minitest"
+end

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Cameron Dutro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,102 @@
+## use_context
+
+![Unit Tests](https://github.com/camertron/use_context/actions/workflows/unit_tests.yml/badge.svg?branch=main)
+
+## What is this thing?
+
+use_context is a tool for providing block-level context to Ruby programs in a thread-safe and fiber-safe way. Internally it leverages fiber-local storage. It can be used to provide data, etc to parts of your program that might be difficult or inconvenient to reach with eg. normal argument passing.
+
+use_context was inspired by this use-case, and originally proposed as an addition to ViewComponent: https://github.com/ViewComponent/view_component/discussions/2327
+
+## Usage
+
+There are three ways to use this gem. As some folks are understandably uncomfortable using monkeypatches - especially ones applied to core classes and modules - you are free to choose the one that fits your preferences.
+
+### As a monkeypatch
+
+Add the following to your program or application somewhere:
+
+```ruby
+require "use_context/ext/kernel"
+```
+
+This will add two methods to `Kernel` so they are available everywhere: `provide_context`, and `use_context`. Contexts consist of a name and a hash of key/value pairs.
+
+```ruby
+def speak
+  use_context(:welcome) do |context|
+    puts context[:salutation]
+  end
+end
+
+provide_context(:welcome, { salutation: "Hello, world!" }) do
+  speak  # prints "Hello, world!"
+end
+```
+
+Values are available in the current context only for the duration of the block passed to `provide_context`, and reset after the block returns.
+
+### As a refinement
+
+Add the following to your program or application somewhere:
+
+```ruby
+require "use_context/ext/kernel_refinement"
+```
+
+The refinement can be enabled at the class, module, or file level, and adds the same two methods to `Kernel`. Refinements work differently than monkeypatching in that their changes are not globally applied and are only visible within the scope they are enabled in.
+
+```ruby
+# Makes provide_context and use_context available on Kernel, but only within this file
+using UseContext::KernelRefinement
+
+provide_context(:welcome, { salutation: "Hello, world!" }) do
+  ...
+end
+```
+
+### No magic
+
+If you'd rather avoid modifying `Kernel` altogether, use_context can also be used via the `UseContext` constant.
+
+Add the following to your program or application somewhere:
+
+```ruby
+require "use_context"
+```
+
+Then simply call `UseContext.provide_context` and `UseContext.use_context`:
+
+```ruby
+UseContext.provide_context(:welcome, { salutation: "Hello, world!" }) do
+  UseContext.use_context(:welcome) do |context|
+    puts context[:salutation]  # prints "Hello, world!"
+  end
+end
+```
+
+## Overriding context
+
+If a key already exists in the current context, it will be overridden, but only for the duration of the block:
+
+```ruby
+provide_context(:welcome, { salutation: "Hello, world!" }) do
+  provide_context(:welcome, { salutation: "Hola, mundo!" }) do
+    speak  # prints "Hola, mundo!"
+  end
+
+  speak  # prints "Hello, world!"
+end
+```
+
+## Running Tests
+
+`bundle exec rake` should do the trick.
+
+## License
+
+Licensed under the MIT license. See LICENSE for details.
+
+## Authors
+
+* Cameron C. Dutro: http://github.com/camertron

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+require "rubygems/package_task"
+
+Bundler::GemHelper.install_tasks
+
+Rake::TestTask.new("test") do |t|
+  t.warning = false
+  t.libs << "test"
+  t.test_files = FileList[
+    "test/**/*_test.rb"
+  ]
+end
+
+task default: [:test]

data/lib/use_context/ext/kernel.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "use_context"
+
+module Kernel
+  include UseContext::ContextMethods
+  extend UseContext::ContextMethods
+end

data/lib/use_context/ext/kernel_refinement.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "use_context"
+
+module UseContext
+  module KernelRefinement
+    refine Kernel do
+      def provide_context(...)
+        UseContext.provide_context(...)
+      end
+
+      def use_context(...)
+        UseContext.use_context(...)
+      end
+    end
+  end
+end

data/lib/use_context/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module UseContext
+  VERSION = "1.0.0"
+end

data/lib/use_context.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module UseContext
+  Fiber.attr_accessor :uc_context
+
+  class << self
+    def current
+      Fiber.current
+    end
+
+    def context
+      current.uc_context ||= {}
+    end
+  end
+
+  class EmptyContext
+    include Singleton
+
+    def [](_key)
+      nil
+    end
+  end
+
+  class Context
+    def initialize(stack)
+      @stack = stack
+    end
+
+    def [](key)
+      @stack.reverse_each do |context_hash|
+        if context_hash.include?(key)
+          return context_hash[key]
+        end
+      end
+
+      nil
+    end
+  end
+
+  class ContextStack
+    attr_reader :context
+
+    def initialize
+      @stack = []
+      @context = Context.new(@stack)
+    end
+
+    def push(context_hash)
+      @stack << context_hash
+    end
+
+    def pop
+      @stack.pop
+    end
+  end
+
+  module ContextMethods
+    def provide_context(name, context_hash)
+      context = UseContext.context[name] ||= ContextStack.new
+      context.push(context_hash)
+      yield
+    ensure
+      context.pop if context
+    end
+
+    def use_context(name)
+      yield UseContext.context[name]&.context || EmptyContext.instance
+    end
+  end
+
+  extend ContextMethods
+end

data/test/kernel_test.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# Use the refinement here rather than the monkeypatch, since we want to test both altering Kernel _and_ not altering it.
+# Depending on test order, applying the monkeypatch here could affect other tests and lead to false positives.
+using UseContext::KernelRefinement
+
+def __uc_provide_context_for_tests(&block)
+  provide_context(:test, { key: :top_level_value }, &block)
+end
+
+def __uc_use_context_for_tests
+  use_context(:test) do |context|
+    context[:key]
+  end
+end
+
+class KernelTest < Minitest::Test
+  class Provider
+    def self.provide(&block)
+      provide_context(:test, { key: :class_value }, &block)
+    end
+
+    def provide(&block)
+      provide_context(:test, { key: :instance_value }, &block)
+    end
+  end
+
+  class User
+    def self.use
+      use_context(:test) do |context|
+        context[:key]
+      end
+    end
+
+    def use
+      use_context(:test) do |context|
+        context[:key]
+      end
+    end
+  end
+
+  define_method(:provide_context_from_dynamically_defined_method) do |&block|
+    provide_context(:test, { key: :value_from_dynamically_defined_method }, &block)
+  end
+
+  define_method(:use_context_from_dynamically_defined_method) do
+    use_context(:test) do |context|
+      context[:key]
+    end
+  end
+
+  def test_provide_context
+    value = provide_context(:test, { key: :inline_value }) do
+      use_context(:test) do |context|
+        context[:key]
+      end
+    end
+
+    assert_equal :inline_value, value
+  end
+
+  def test_provide_context_from_top_level
+    value = __uc_provide_context_for_tests do
+      __uc_use_context_for_tests
+    end
+
+    assert_equal :top_level_value, value
+  end
+
+  def test_provide_context_from_dynamically_defined_method
+    value = provide_context_from_dynamically_defined_method do
+      use_context_from_dynamically_defined_method
+    end
+
+    assert_equal :value_from_dynamically_defined_method, value
+  end
+
+  def test_provide_context_from_instance
+    assert_equal :instance_value, Provider.new.provide { User.new.use }
+  end
+
+  def test_provide_context_from_class
+    assert_equal :class_value, Provider.provide { User.use }
+  end
+
+  def test_context_can_be_overridden
+    provide_context(:test, { setting1: :a, setting2: :a }) do
+      use_context(:test) do |context|
+        assert_equal :a, context[:setting1]
+        assert_equal :a, context[:setting2]
+
+        provide_context(:test, { setting1: :b }) do
+          use_context(:test) do |context|
+            assert_equal :b, context[:setting1]
+            assert_equal :a, context[:setting2]
+          end
+        end
+      end
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "use_context/ext/kernel_refinement"
+require "minitest/autorun"

data/test/use_context_test.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class UseContextTest < Minitest::Test
+  def test_provide_context_from_uc_constant
+    value = UseContext.provide_context(:test, { key: :value_from_uc_constant }) do
+      UseContext.use_context(:test) do |context|
+        context[:key]
+      end
+    end
+
+    assert_equal :value_from_uc_constant, value
+  end
+end

data/use_context.gemspec

@@ -0,0 +1,16 @@
+$:.unshift File.join(File.dirname(__FILE__), 'lib')
+require 'use_context/version'
+
+Gem::Specification.new do |s|
+  s.name     = 'use_context'
+  s.version  = ::UseContext::VERSION
+  s.authors  = ['Cameron Dutro']
+  s.email    = ['camertron@gmail.com']
+  s.homepage = 'http://github.com/camertron/use_context'
+  s.description = s.summary = 'Easily provide block-scoped context values in your Ruby code.'
+  s.platform = Gem::Platform::RUBY
+
+  s.require_path = 'lib'
+
+  s.files = Dir['{lib,test}/**/*', 'Gemfile', 'LICENSE', 'CHANGELOG.md', 'README.md', 'Rakefile', 'use_context.gemspec']
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: use_context
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Cameron Dutro
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Easily provide block-scoped context values in your Ruby code.
+email:
+- camertron@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/use_context.rb
+- lib/use_context/ext/kernel.rb
+- lib/use_context/ext/kernel_refinement.rb
+- lib/use_context/version.rb
+- test/kernel_test.rb
+- test/test_helper.rb
+- test/use_context_test.rb
+- use_context.gemspec
+homepage: http://github.com/camertron/use_context
+licenses: []
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Easily provide block-scoped context values in your Ruby code.
+test_files: []