https://github.com/am-kantox/dry-behaviour

Tiny library inspired by Elixir protocol pattern.
https://github.com/am-kantox/dry-behaviour

behaviour delegate kantox protocol ruby

Last synced: about 2 months ago
JSON representation

Tiny library inspired by Elixir protocol pattern.

Host: GitHub
URL: https://github.com/am-kantox/dry-behaviour
Owner: am-kantox
License: mit
Created: 2016-10-18T17:48:30.000Z (over 8 years ago)
Default Branch: master
Last Pushed: 2023-02-01T09:20:01.000Z (over 2 years ago)
Last Synced: 2025-03-21T12:22:04.560Z (2 months ago)
Topics: behaviour, delegate, kantox, protocol, ruby
Language: Ruby
Size: 94.7 KB
Stars: 13
Watchers: 4
Forks: 2
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        # Dry::Behaviour

[![Build Status](https://travis-ci.org/am-kantox/dry-behaviour.svg?branch=master)](https://travis-ci.org/am-kantox/dry-behaviour)

**Tiny library inspired by Elixir [`protocol`](http://elixir-lang.org/getting-started/protocols.html) pattern.**

## Protocols

### Declaration

```ruby

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

```

### Usage

```ruby

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.

```ruby

  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.

```ruby

  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:

```ruby

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.

## Guards

Starting with `v0.5.0` we support multiple function clauses and guards.

```ruby

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

```

## Authors

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

## Changelog

### `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`:

```diff

 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

```

### `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 `defimpl`s.

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

```ruby

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`.

### `0.3.1` :: `implemented_for?` and `implementation_for`

### `0.3.0` :: version bump

### `0.2.2` :: meaningful errors

#### Throws an exception on wrong usage:

```ruby

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:

```ruby

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:

```ruby

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`:

```ruby

defimpl MyProto, target: MyClass, delegate: :to_s, map: { add: :+, subtract: :- }

```

## Installation

Add this line to your application's Gemfile:

```ruby

gem 'dry-behaviour'

```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install dry-behaviour

## Development

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](https://rubygems.org).

## Contributing

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](contributor-covenant.org) code of conduct.

## License

The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/am-kantox/dry-behaviour

Awesome Lists containing this project

README