Tiny library inspired by Elixir protocol
pattern.
require 'dry/behaviour'
module Protocols
module Adder
include Dry::Protocol
defprotocol do
defmethod :add, :this, :other
defmethod :subtract, :this, :other
def add_default(value)
add(3, 2) + value
end
end
defimpl Protocols::Adder, target: String do
def add(this, other)
this * other
end
def subtract(this, other)
this
end
end
defimpl Protocols::Adder, target: NilClass do
def add(this, other)
other
end
def subtract(this, other)
this
end
end
# delegate `to_s` as is, map `add` and `subtract` to `:+` and `:-` respectively
defimpl target: Integer, delegate: :to_s, map: { add: :+, subtract: :- }
end
end
expect(Protocols::Adder.add(5, 3)).to eq(8)
expect(Protocols::Adder.add(5, 10)).to eq(15)
expect(Protocols::Adder.subtract(5, 10)).to eq(-5)
expect(Protocols::Adder.add(15, 10)).to eq(25)
expect(Protocols::Adder.add("!", 10)).to eq("!!!!!!!!!!")
expect(Protocols::Adder.add(nil, 10)).to eq(10)
expect(Protocols::Adder.add_default(1)).to eq(6)
Normally, one would use a simple notation to declare a method. It includes :this
receiver
in te very first position and some optional required arguments afterward.
defmethod :add, :this, :addend
...
defimpl ... do
def add(this, addend); this + addend; end
end
If the argument is not generic (optional, or splatted, or keyword,) its type must be explicitly specified in the protocol definition as shown below.
defprotocol implicit_inheritance: true do
defmethod :with_def_argument, :this, [:foo_opt, :opt]
defmethod :with_def_keyword_argument, :this, [:foo_key, :key]
defmethod :with_req_keyword_argument, :this, [:foo_key, :keyreq]
def with_def_argument(this, foo_opt = :super); foo_opt; end
def with_def_keyword_argument(this, foo_key: :super); foo_key; end
def with_req_keyword_argument(this, foo_key:); foo_key; end
...
That said, :addend
argument declaration is a syntactic sugar for [:addend, :req]
.
Possible values for the type are:
PARAM_TYPES = %i[req opt rest key keyrest keyreq block]
Please note, that the signature of the method and its implementation must exactly match.
One cannot declare a method to have a keyreq
argument and then make it defaulted in the
implementation. That is done by design.
Starting with v0.5.0
we support multiple function clauses and guards.
class GuardTest
include Dry::Guards
def a(p, p2 = nil, *_a, when: { p: Integer, p2: String }, **_b, &cb); 1; end
def a(p, _p2 = nil, *_a, when: { p: Integer }, **_b, &cb); 2; end
def a(p, _p2 = nil, *_a, when: { p: Float }, **_b, &cb); 3; end
def a(p, _p2 = nil, *_a, when: { p: ->(v) { v < 42 } }, **_b, &cb); 4; end
def a(_p, _p2 = nil, *_a, when: { cb: ->(v) { !v.nil? } }, **_b, &cb); 5; end
def a(p1, p2, p3); 6; end
def a(p, _p2 = nil, *_a, **_b, &cb); 'ALL'; end
def b(p, &cb)
'NOT GUARDED'
end
end
gt = GuardTest.new
it 'performs routing to function clauses as by guards' do
expect(gt.a(42, 'Hello')).to eq(1)
expect(gt.a(42)).to eq(2)
expect(gt.a(3.14)).to eq(3)
expect(gt.a(3)).to eq(4)
expect(gt.a('Hello', &-> { puts 0 })).to eq(5)
expect(gt.a(*%w|1 2 3|)).to eq(6)
expect(gt.a('Hello')).to eq('ALL')
end
@am-kantox, @saverio-kantox & @kantox
- many error reporting improvements,
- warning on wrong arity (declaration, arity 0 / implementation, wrong arity)
- deprecate implicit delegation to the target instance; error message saying “it’ll be removed in 1.0”
implicit_inheritance: true
flag in call todefprotocol
makes the implementation implicitly inherit the behaviour declared in the core protocol module itself, without the necessity to explicitly callsuper
:
module ParentOKImplicit
include Dry::Protocol
- defprotocol do
+ defprotocol implicit_inheritance: true do
defmethod :foo
def foo(this)
:ok
end
defimpl target: String do
- def foo(this)
- super(this)
- end
end
end
end
- better error messages (very descriptive, with whys and howtos)
- the whole stacktrace is carefully saved with
cause
- internal exceptions related to wrong implementation do now point to the proper lines in the client code (internal trace lines are removed)
- implementation for classes responding to
to_a
is handled properly
NB Works for all defimpl
s.
module Protocols::Adder
include Dry::Protocol
defprotocol do
defmethod :add, :this, :other
def default
42
end
end
end
Dry::Protocol.defimpl target: Integer do
def add(this)
this + default #⇒ 47 when called as Protocols::Adder.add(5)
end
end
NB At the moment works only for external defimpl
.
Protocols::Adder.add({}, 42)
#⇒ Protocols::NotImplemented: Protocol “Protocols::Adder” is not implemented for “Hash”
Protocols::Adder.hello({}, 42)
#⇒ Protocols::NotImplemented: Protocol “Protocols::Adder” does not declare method “hello”
defimpl MyProto, target: [MyClass1, MyClass2], delegate: [:add, :subtract]
when defimpl
does not fully cover the protocol declaration,
missing methods are implicitly delegated to the target,
the warning is being issued:
defimpl MyProto, target: MyClass, map: { add: :+, subtract: :- }
#⇒ W, [2016-10-24T14:52:49.230808 #26382] WARN -- : Implicit delegate MyProto#to_s to MyClass
defimpl
now accepts delegate
and map
:
defimpl MyProto, target: MyClass, delegate: :to_s, map: { add: :+, subtract: :- }
Add this line to your application's Gemfile:
gem 'dry-behaviour'
And then execute:
$ bundle
Or install it yourself as:
$ gem install dry-behaviour
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/dry-behaviour. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.