From fb4b95a0b999adcf9705f0acb08520ecb4b583f9 Mon Sep 17 00:00:00 2001 From: Thomas Sawyer Date: Tue, 17 Nov 2026 20:24:59 -0500 Subject: [PATCH] Make Paramix the module to include A parametric module now says include Paramix, not include Paramix::Parametric. Paramix::Parametric, the name in the Paramix gem, is kept as another name for the same module. Co-Authored-By: Claude Fable 5.2 --- HISTORY.md | 13 +- lib/standard/facets/paramix.rb | 225 ++++++++++++++++----------------- test/standard/test_paramix.rb | 25 ++-- 3 files changed, 135 insertions(+), 128 deletions(-) diff --git a/HISTORY.md b/HISTORY.md index 74c142f3..f8effc7c 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -31,12 +31,13 @@ Changes: `instance_variables`, or a `BasicObject` that has neither. The class is `Kernel::Mirror`, so an application's own `Mirror` class takes precedence instead of clashing. Based on the Instance gem. - * `Paramix::Parametric`, loaded with `require 'facets/paramix'`, makes a - module take parameters where it is included or extended: - `include Greeter[:name => 'x']`. The module's `parameterized` block is - given the parameters and defines the methods that depend on them. - Paramix was part of Facets until 2.7.0; this is the Paramix gem's - version. + * `Paramix`, loaded with `require 'facets/paramix'`, makes a module + take parameters where it is included or extended: + `include Greeter[:name => 'x']`. A module that includes `Paramix` + has a `parameterized` block, which is given the parameters and + defines the methods that depend on them. Paramix was part of Facets + until 2.7.0, then the Paramix gem, where the module to include was + `Paramix::Parametric`; that name still works. * `String::Mask` and `String#mask`, loaded with `require 'facets/string/mask'`, treat a string as a mask with empty slots and combine masks character by character: diff --git a/lib/standard/facets/paramix.rb b/lib/standard/facets/paramix.rb index c930c4ee..26722e38 100644 --- a/lib/standard/facets/paramix.rb +++ b/lib/standard/facets/paramix.rb @@ -1,4 +1,50 @@ -# Paramix namespace. +# Paramix makes a module parametric: one that takes parameters where it +# is included or extended, with `Module[parameters]`. Its `parameterized` +# block is given the parameters, and defines the methods that depend on +# them. +# +# module Greeter +# include Paramix +# +# parameterized do |params| +# define_method :hello do +# "Hello from #{params[:name]}!" +# end +# end +# end +# +# class English +# include Greeter[:name => 'England'] +# end +# +# class Scots +# include Greeter[:name => 'Scotland'] +# end +# +# English.new.hello #=> "Hello from England!" +# Scots.new.hello #=> "Hello from Scotland!" +# +# Each use of `Module[parameters]` makes a new module that includes the +# parametric one, so each class gets its own methods. The block runs in +# that module, where `public`, `private` and `protected` also define a +# method when given a block: +# +# module Named +# include Paramix +# +# parameterized do |params| +# public(params[:as]) { params[:value] } +# end +# end +# +# class Config +# extend Named[:as => :env, :value => 'test'] +# end +# +# Config.env #=> "test" +# +# A module that includes a parametric module without giving it +# parameters becomes parametric too, and passes its own parameters on. # # NOTE: This is not loaded by `require 'facets'`. Use: # @@ -11,143 +57,94 @@ module Paramix - # A parametric mixin is a module that takes parameters where it is - # included or extended, with `Module[parameters]`. Its `parameterized` - # block is given the parameters, and defines the methods that depend - # on them. - # - # module Greeter - # include Paramix::Parametric # - # parameterized do |params| - # define_method :hello do - # "Hello from #{params[:name]}!" - # end - # end - # end - # - # class English - # include Greeter[:name => 'England'] - # end - # - # class Scots - # include Greeter[:name => 'Scotland'] - # end - # - # English.new.hello #=> "Hello from England!" - # Scots.new.hello #=> "Hello from Scotland!" - # - # Each use of `Module[parameters]` makes a new module that includes the - # parametric one, so each class gets its own methods. The block runs in - # that module, where `public`, `private` and `protected` also define a - # method when given a block: - # - # module Named - # include Paramix::Parametric - # - # parameterized do |params| - # public(params[:as]) { params[:value] } - # end - # end - # - # class Config - # extend Named[:as => :env, :value => 'test'] - # end - # - # Config.env #=> "test" - # - # A module that includes a parametric module without giving it - # parameters becomes parametric too, and passes its own parameters on. + def self.included(base) + base.extend(Extensions) + end - module Parametric + # Class-level methods of a parametric module. + module Extensions + # Apply parameters, giving a module to include or extend. # - def self.included(base) - base.extend(Extensions) + # Returns a new Mixin. [Mixin] + def [](parameters={}) + Mixin.new(self, parameters) end - # Class-level methods of a parametric module. - module Extensions - - # Apply parameters, giving a module to include or extend. - # - # Returns a new Mixin. [Mixin] - def [](parameters={}) - Mixin.new(self, parameters) - end - - # Add a block to run when parameters are applied. Without a block, - # gives the blocks added so far. - # - # Returns the list of blocks. [Array] - def parameterized(&code) - @code ||= [] - if block_given? - @code << code - else - @code - end + # Add a block to run when parameters are applied. Without a block, + # gives the blocks added so far. + # + # Returns the list of blocks. [Array] + def parameterized(&code) + @code ||= [] + if block_given? + @code << code + else + @code end + end - # - def append_features(base) - return super(base) if Mixin === base || Mixin === self - - base.extend(Extensions) + # + def append_features(base) + return super(base) if Mixin === base || Mixin === self - anc = ancestors.find{ |a| a.respond_to?(:parameterized) } - base.parameterized.concat(anc.parameterized) + base.extend(Extensions) - super(base) - end + anc = ancestors.find{ |a| a.respond_to?(:parameterized) } + base.parameterized.concat(anc.parameterized) - # - def extend_object(base) - return super(base) if Mixin === base || Mixin === self + super(base) + end - base.extend(Extensions) + # + def extend_object(base) + return super(base) if Mixin === base || Mixin === self - anc = ancestors.find{ |a| a.respond_to?(:parameterized) } - base.parameterized.concat(anc.parameterized) + base.extend(Extensions) - super(base) - end + anc = ancestors.find{ |a| a.respond_to?(:parameterized) } + base.parameterized.concat(anc.parameterized) + super(base) end - # An instance of the Mixin module class is what is produced - # when parameters are applied to a parametric module. - # - class Mixin < Module - - def initialize(base, parameters) - super() - include(base) - base.parameterized.each do |code| - instance_exec(parameters, &code) - end - end + end - # As Module#public, and given a block, define the method first. - def public(*names, &code) - define_method(names.first, &code) if code - super(*names) - end + # An instance of the Mixin module class is what is produced + # when parameters are applied to a parametric module. + # + class Mixin < Module - # As Module#private, and given a block, define the method first. - def private(*names, &code) - define_method(names.first, &code) if code - super(*names) + def initialize(base, parameters) + super() + include(base) + base.parameterized.each do |code| + instance_exec(parameters, &code) end + end - # As Module#protected, and given a block, define the method first. - def protected(*names, &code) - define_method(names.first, &code) if code - super(*names) - end + # As Module#public, and given a block, define the method first. + def public(*names, &code) + define_method(names.first, &code) if code + super(*names) + end + # As Module#private, and given a block, define the method first. + def private(*names, &code) + define_method(names.first, &code) if code + super(*names) + end + + # As Module#protected, and given a block, define the method first. + def protected(*names, &code) + define_method(names.first, &code) if code + super(*names) end end + # The name this module had in the Paramix gem. + Parametric = self + end diff --git a/test/standard/test_paramix.rb b/test/standard/test_paramix.rb index 7f01fb7e..693851b9 100644 --- a/test/standard/test_paramix.rb +++ b/test/standard/test_paramix.rb @@ -1,12 +1,12 @@ covers 'facets/paramix' -test_case Paramix::Parametric::Extensions do +test_case Paramix::Extensions do # A parametric module that defines the method named by :name, returning # :value. maker = lambda do Module.new do - include Paramix::Parametric + include Paramix parameterized do |params| public(params[:name]) { params[:value] } end @@ -15,12 +15,21 @@ method :parameterized do - test "is added to a module that includes Parametric" do + test "is added to a module that includes Paramix" do m = maker.call m.assert.respond_to?(:parameterized) m.assert.respond_to?(:[]) end + test "Paramix::Parametric, its name in the gem, is the same module" do + Paramix::Parametric.assert.equal?(Paramix) + m = Module.new do + include Paramix::Parametric + parameterized { |params| public(:f) { params[:p] } } + end + Class.new { include m[:p => 1] }.new.f.assert == 1 + end + end method :[] do @@ -49,7 +58,7 @@ test "the module's own methods come along" do m = Module.new do - include Paramix::Parametric + include Paramix parameterized do |params| define_method(:params) { params } end @@ -63,7 +72,7 @@ def hello test "the block can define any methods from its parameters" do m = Module.new do - include Paramix::Parametric + include Paramix parameterized do |params| attr_accessor params[:p] end @@ -76,7 +85,7 @@ def hello test "private and protected define methods with that visibility" do m = Module.new do - include Paramix::Parametric + include Paramix parameterized do |params| private(:secret) { params[:value] } protected(:guarded) { params[:value] } @@ -91,7 +100,7 @@ def hello test "public, private and protected still take names alone" do m = Module.new do - include Paramix::Parametric + include Paramix parameterized do |params| define_method(:a) { 1 } define_method(:b) { 2 } @@ -106,7 +115,7 @@ def hello test "a parametric module can include another with parameters" do inner = maker.call outer = Module.new do - include Paramix::Parametric + include Paramix include inner[:name => :f, :value => 1] parameterized do |params| public(params[:name]) { params[:value] }