Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions HISTORY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
225 changes: 111 additions & 114 deletions lib/standard/facets/paramix.rb
Original file line number Diff line number Diff line change
@@ -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:
#
Expand All @@ -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<Proc>]
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<Proc>]
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
25 changes: 17 additions & 8 deletions test/standard/test_paramix.rb
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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] }
Expand All @@ -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 }
Expand All @@ -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] }
Expand Down
Loading