Barn 77 allow context overrides in helper methods

CHANGELOG.md

@@ -4,6 +4,19 @@ Inspired by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 Note: This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2025-11-25
+### Added
+- Added optional context_overrides argument for the following methods:
+    - `ParameterSubstitution.find_tokens`
+    - `ParameterSubstitution.find_formatters`
+    - `ParameterSubstitution.find_warnings`
+
+### Removed 
+- Removed optional `parameter_start` and `parameter_end` arguments for the following methods:
+    - `ParameterSubstitution.find_tokens`
+    - `ParameterSubstitution.find_formatters`
+    - `ParameterSubstitution.find_warnings`
+
 ## [2.1.0] - 2025-11-06
 ### Added
 - Added optional `parameter_start` and `parameter_end` arguments for the following methods:

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    parameter_substitution (2.1.0)
+    parameter_substitution (3.0.0)
       activesupport (>= 6.0)
       builder (~> 3.2)
       invoca-utils (~> 0.3)
@@ -22,7 +22,7 @@
       tzinfo (~> 2.0)
     appraisal (2.5.0)
       bundler
       rake
       thor (>= 0.14.0)
     appraisal-matrix (0.2.0)
       appraisal (~> 2.2)

lib/parameter_substitution.rb

@@ -3,6 +3,7 @@
 # See lib/parameter_substitution/readme.md
 
 require 'active_support/all'
+require 'set'
 require "parameter_substitution/context"
 require "parameter_substitution/parse_error"
 require "parameter_substitution/parser"
@@ -63,27 +64,65 @@ def configure
       ParameterSubstitution.config = config
     end
 
-    def find_tokens(string_with_tokens, mapping: {}, parameter_start: "<", parameter_end: ">")
-      parse_expression(context_from_string(string_with_tokens, mapping, parameter_start: parameter_start, parameter_end: parameter_end)).substitution_parameter_names
+    def find_tokens(string_with_tokens, mapping: {}, context_overrides: {})
+      context = build_context(string_with_tokens, mapping, context_overrides)
+      parse_expression(context).substitution_parameter_names
     end
 
-    def find_formatters(string_with_tokens, mapping: {}, parameter_start: "<", parameter_end: ">")
-      parse_expression(context_from_string(string_with_tokens, mapping, parameter_start: parameter_start, parameter_end: parameter_end)).method_names
+    def find_formatters(string_with_tokens, mapping: {}, context_overrides: {})
+      context = build_context(string_with_tokens, mapping, context_overrides)
+      parse_expression(context).method_names
     end
 
-    def find_warnings(string_with_tokens, mapping: {}, parameter_start: "<", parameter_end: ">")
-      parse_expression(context_from_string(string_with_tokens, mapping, parameter_start: parameter_start, parameter_end: parameter_end)).parameter_and_method_warnings || []
+    def find_warnings(string_with_tokens, mapping: {}, context_overrides: {})
+      context = build_context(string_with_tokens, mapping, context_overrides)
+      parse_expression(context).parameter_and_method_warnings || []
     end
 
     private
 
-    def context_from_string(string_with_tokens, mapping, parameter_start: "<", parameter_end: ">")
-      ParameterSubstitution::Context.new(
+    VALID_CONTEXT_OVERRIDE_KEYS = %i[
+        required_parameters
+        parameter_start
+        parameter_end
+        destination_encoding
+        allow_unknown_replacement_parameters
+        allow_nil
+        allow_unmatched_parameter_end
+      ].to_set
+    private_constant :VALID_CONTEXT_OVERRIDE_KEYS
+
+    # Build context with optional overrides
+    # @param [String] string_with_tokens The input string containing tokens
+    # @param [Hash] mapping The mapping of parameters to values
+    # @param [Hash] context_overrides Optional overrides for context attributes
+    # @return [ParameterSubstitution::Context] The constructed context
+    # @raise [ArgumentError] if context_overrides contains invalid keys
+    def build_context(string_with_tokens, mapping, context_overrides)
+      validate_context_overrides!(context_overrides)
+
+      base_options = {
         input: string_with_tokens,
-        mapping:,
-        parameter_start:,
-        parameter_end:
-      )
+        mapping: mapping
+      }
+
+      symbolized_overrides = context_overrides.transform_keys(&:to_sym)
+
+      ParameterSubstitution::Context.new(**symbolized_overrides.merge(base_options))
+    end
+
+    # @param [Hash] context_overrides The overrides to validate
+    # @raise [ArgumentError] if context_overrides contains invalid keys
+    def validate_context_overrides!(context_overrides)
+      return if context_overrides.empty?
+
+      invalid_keys = context_overrides.keys.reject { |key| VALID_CONTEXT_OVERRIDE_KEYS.include?(key.to_sym) }
+
+      if invalid_keys.any?
+        invalid_keys_list = invalid_keys.join(", ")
+        valid_keys_list = VALID_CONTEXT_OVERRIDE_KEYS.sort.join(", ")
+        raise ArgumentError, "Invalid context_overrides keys: #{invalid_keys_list}. Valid keys are: #{valid_keys_list}"
+      end
     end
 
     def parse_expression(context)

lib/parameter_substitution/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class ParameterSubstitution
-  VERSION = "2.1.0"
+  VERSION = "3.0.0"
 end

spec/lib/parameter_substitution_spec.rb

@@ -73,6 +73,44 @@ def self.find(_key); end
       let(:expression) { "<call.start_time.blank_if_nil><do_a_barrel_roll.downcase>" }
       let(:mapping) { { 'call.start_time' => 'hello' } }
 
+      shared_examples "passes context_overrides with symbolized keys to Context" do
+        it "calls Context.new with the expected overrides" do
+          allow(ParameterSubstitution::Context).to receive(:new).and_call_original
+          subject
+          expect(ParameterSubstitution::Context).to have_received(:new).once.with(
+            hash_including(test_context_overrides.transform_keys(&:to_sym).merge(
+              input: test_expression,
+              mapping: test_mapping
+            ))
+          )
+        end
+      end
+
+      shared_examples "validates context_overrides" do
+        context 'when context_overrides attempts to override base options' do
+          context "when input is provided in context_overrides" do
+            let(:test_context_overrides) { { input: "<different>" } }
+            it "raises error" do
+              expect { subject }.to raise_error(ArgumentError, /Invalid context_overrides keys: input/)
+            end
+          end
+
+          context "when mapping is provided in context_overrides" do
+            let(:test_context_overrides) { { mapping: { 'different' => 'value' } } }
+            it "raises error" do
+              expect { subject }.to raise_error(ArgumentError, /Invalid context_overrides keys: mapping/)
+            end
+          end
+        end
+
+        context 'when context_overrides contains invalid keys' do
+          let(:test_context_overrides) { { invalid_key: "value", another_invalid: "value2" } }
+          it "raises error with list of invalid keys" do
+            expect { subject }.to raise_error(ArgumentError, /Invalid context_overrides keys: invalid_key, another_invalid/)
+          end
+        end
+      end
+
       context "#find_tokens" do
         it "returns tokens up to first dot when no mapping is provided" do
           expect(ParameterSubstitution.find_tokens(expression)).to eq(['call', 'do_a_barrel_roll'])
@@ -83,16 +121,39 @@ def self.find(_key); end
         end
 
         context 'with non-default delimiters' do
-          let(:square_expression) { "[call.start_time.blank_if_nil][do_a_barrel_roll.downcase]" }
+          let(:test_expression) { "[call.start_time.blank_if_nil][do_a_barrel_roll.downcase]" }
+          let(:test_mapping) { {} }
+          let(:test_context_overrides) do
+            {
+              required_parameters: ["param1", "param2"],
+              parameter_start: "[",
+              parameter_end: "]",
+              destination_encoding: :json,
+              allow_unknown_replacement_parameters: true,
+              allow_nil: true,
+              allow_unmatched_parameter_end: true
+            }
+          end
 
-          it "returns tokens up to first dot when no mapping is provided" do
-            expect(ParameterSubstitution.find_tokens(square_expression, parameter_start: "[", parameter_end: "]")).to eq(['call', 'do_a_barrel_roll'])
+          context 'with symbol override keys' do
+            include_examples "passes context_overrides with symbolized keys to Context" do
+              subject { ParameterSubstitution.find_tokens(test_expression, mapping: test_mapping, context_overrides: test_context_overrides) }
+            end
           end
 
-          it "returns tokens that exist in mapping when one is provided" do
-            expect(ParameterSubstitution.find_tokens(square_expression, mapping: mapping, parameter_start: "[", parameter_end: "]")).to eq(['call.start_time', 'do_a_barrel_roll'])
+          context 'with string override keys' do
+            include_examples "passes context_overrides with symbolized keys to Context" do
+              subject { ParameterSubstitution.find_tokens(test_expression, mapping: test_mapping, context_overrides: test_context_overrides.transform_keys(&:to_s)) }
+            end
           end
         end
+
+        include_examples "validates context_overrides" do
+          let(:test_expression) { expression }
+          let(:test_mapping) { mapping }
+          let(:test_context_overrides) { {} }
+          subject { ParameterSubstitution.find_tokens(test_expression, mapping: test_mapping, context_overrides: test_context_overrides) }
+        end
       end
 
       context '#find_formatters' do
@@ -105,21 +166,44 @@ def self.find(_key); end
         end
 
         context 'with non-default delimiters' do
-          let(:square_expression) { "[call.start_time.blank_if_nil][do_a_barrel_roll.downcase]" }
+          let(:test_expression) { "[call.start_time.blank_if_nil][do_a_barrel_roll.downcase]" }
+          let(:test_mapping) { {} }
+          let(:test_context_overrides) do
+            {
+              required_parameters: ["param1", "param2"],
+              parameter_start: "[",
+              parameter_end: "]",
+              destination_encoding: :json,
+              allow_unknown_replacement_parameters: true,
+              allow_nil: true,
+              allow_unmatched_parameter_end: true
+            }
+          end
 
-          it "returns all formatters after first dot when no mapping is provided" do
-            expect(ParameterSubstitution.find_formatters(square_expression, parameter_start: "[", parameter_end: "]")).to eq(['start_time', 'blank_if_nil', 'downcase'])
+          context 'with symbol override keys' do
+            include_examples "passes context_overrides with symbolized keys to Context" do
+              subject { ParameterSubstitution.find_formatters(test_expression, mapping: test_mapping, context_overrides: test_context_overrides) }
+            end
           end
 
-          it "returns formatters after all tokens when mapping is provided" do
-            expect(ParameterSubstitution.find_formatters(square_expression, mapping: mapping, parameter_start: "[", parameter_end: "]")).to eq(['blank_if_nil', 'downcase'])
+          context 'with string override keys' do
+            include_examples "passes context_overrides with symbolized keys to Context" do
+              subject { ParameterSubstitution.find_formatters(test_expression, mapping: test_mapping, context_overrides: test_context_overrides.transform_keys(&:to_s)) }
+            end
           end
         end
+
+        include_examples "validates context_overrides" do
+          let(:test_expression) { expression }
+          let(:test_mapping) { mapping }
+          let(:test_context_overrides) { {} }
+          subject { ParameterSubstitution.find_formatters(test_expression, mapping: test_mapping, context_overrides: test_context_overrides) }
+        end
       end
 
       context '#find_warnings' do
         let(:expression_with_valid_params) { "<foo>" }
-        let(:expression_with_bad_paramss) { "<bobby><bobby2>" }
+        let(:expression_with_bad_params) { "<bobby><bobby2>" }
         let(:expression_with_bad_methods) { "<foo.test1.test2><foo.test3.test4><black.test1.test2>" }
         let(:expression_with_bad_params_and_methods) { "<bobby.test1.test2><bobby2.test3.test4>" }
         let(:expression_with_mixed_bad_params_and_methods) { "<bobby.test1.test2><foo.test3.test4>" }
@@ -133,7 +217,7 @@ def self.find(_key); end
 
         context "when there are invalid parameters" do
           it "returns 2 warnings" do
-            expect(ParameterSubstitution.find_warnings(expression_with_bad_paramss)).to eq(["Unknown param 'bobby'", "Unknown param 'bobby2'"])
+            expect(ParameterSubstitution.find_warnings(expression_with_bad_params)).to eq(["Unknown param 'bobby'", "Unknown param 'bobby2'"])
           end
         end
 
@@ -153,26 +237,39 @@ def self.find(_key); end
         end
 
         context "with non-default delimiters" do
-          let(:square_expression_with_valid_params) { "[foo]" }
-          let(:square_expression_with_bad_params) { "[bobby][bobby2]" }
-          let(:square_expression_with_bad_methods) { "[foo.test1.test2][foo.test3.test4][black.test1.test2]" }
-
-          it "returns empty array for valid parameters" do
-            expect(ParameterSubstitution.find_warnings(square_expression_with_valid_params, mapping: default_mapping, parameter_start: "[", parameter_end: "]"))
-              .to eq([])
+          let(:test_expression) { "[foo]" }
+          let(:test_mapping) { default_mapping }
+          let(:test_context_overrides) do
+            {
+              required_parameters: ["param1", "param2"],
+              parameter_start: "[",
+              parameter_end: "]",
+              destination_encoding: :json,
+              allow_unknown_replacement_parameters: true,
+              allow_nil: true,
+              allow_unmatched_parameter_end: true
+            }
           end
 
-          it "returns warnings for invalid parameters" do
-            expect(ParameterSubstitution.find_warnings(square_expression_with_bad_params, parameter_start: "[", parameter_end: "]"))
-              .to eq(["Unknown param 'bobby'", "Unknown param 'bobby2'"])
+          context "with symbol override keys" do
+            include_examples "passes context_overrides with symbolized keys to Context" do
+              subject { ParameterSubstitution.find_warnings(test_expression, mapping: test_mapping, context_overrides: test_context_overrides) }
+            end
           end
 
-          it "returns warnings for invalid methods" do
-            expect(ParameterSubstitution.find_warnings(square_expression_with_bad_methods, mapping: default_mapping, parameter_start: "[", parameter_end: "]"))
-              .to eq(["Unknown methods 'test1', 'test2', 'test3', 'test4' used on parameter 'foo'",
-                      "Unknown methods 'test1', 'test2' used on parameter 'black'"])
+          context "with string override keys" do
+            include_examples "passes context_overrides with symbolized keys to Context" do
+              subject { ParameterSubstitution.find_warnings(test_expression, mapping: test_mapping, context_overrides: test_context_overrides.transform_keys(&:to_s)) }
+            end
           end
         end
+
+        include_examples "validates context_overrides" do
+          let(:test_expression) { expression_with_valid_params }
+          let(:test_mapping) { default_mapping }
+          let(:test_context_overrides) { {} }
+          subject { ParameterSubstitution.find_warnings(test_expression, mapping: test_mapping, context_overrides: test_context_overrides) }
+        end
       end
     end