Build Status

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

    defimpl Protocols::Adder, target: String do
      def add(this, other)
        this * other
      def subtract(this, other)
    defimpl Protocols::Adder, target: NilClass do
      def add(this, other)
      def subtract(this, other)

    # delegate `to_s` as is, map `add` and `subtract` to `:+` and `:-` respectively
    defimpl target: Integer, delegate: :to_s, map: { add: :+, subtract: :- }


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)

Arguments types

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

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)

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')


@am-kantox, @saverio-kantox & @kantox


0.9.0 :: Warning On Wrong Arity

  • many error reporting improvements,
  • warning on wrong arity (declaration, arity 0 / implementation, wrong arity)

0.8.0 :: Implicit Inheritance

  • deprecate implicit delegation to the target instance; error message saying “it’ll be removed in 1.0”
  • implicit_inheritance: true flag in call to defprotocol makes the implementation implicitly inherit the behaviour declared in the core protocol module itself, without the necessity to explicitly call super:
 module ParentOKImplicit
   include Dry::Protocol

-  defprotocol do
+  defprotocol implicit_inheritance: true do
     defmethod :foo

     def foo(this)

     defimpl target: String do
-      def foo(this)
-        super(this)
-      end

0.7.0 :: Handling Errors

  • 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)

0.6.0 :: Bugfix

  • implementation for classes responding to to_a is handled properly

0.5.0 :: Guards

0.4.2 :: Removed the forgotten debug output :(

0.4.1 :: Protocol-wide methods are allowed to call from implementation

NB Works for all defimpls.

0.4.0 :: Protocol-wide methods are allowed to call from inside implementation

module Protocols::Adder
  include Dry::Protocol

  defprotocol do
    defmethod :add, :this, :other
    def default

Dry::Protocol.defimpl target: Integer do
  def add(this)
    this + default #⇒ 47 when called as Protocols::Adder.add(5)

NB At the moment works only for external defimpl.

0.3.1 :: implemented_for? and implementation_for

0.3.0 :: version bump

0.2.2 :: meaningful errors

Throws an exception on wrong usage:

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”

0.2.1 :: multiple targets

Multiple targets:

defimpl MyProto, target: [MyClass1, MyClass2], delegate: [:add, :subtract]

0.2.0 :: implicit delegate on incomplete implementation

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

0.1.1 :: delegate and map methods to receiver

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.