Awesome

Chainable Methods

The Elixir language is great and within its many incredible features is the famous "Pipe Operator". Other popular functional languages like Haskell and F# sport a similar feature to chain method calls in a non-OO language.

It allows you to do constructs such as this:

require Integer
1..100_000
  |> Stream.map(&(&1 * 3))
  |> Stream.filter(&(Integer.is_odd(&1)))
  |> Enum.sum

In a nutshell, this is taking the previous returning value and automatically passing it as the first argument of the following function call, so it's sort of equivalent to do this:

require Integer
Enum.sum(Enum.filter(Enum.map(1..100_000, &(&1 * 3)), &(Integer.is_odd(&1))))

This is how we would usually do it, but with the Pipe Operator it becomes incredibly more enjoyable and readable to work with and shifts our way of thinking into making small functions in linked chains. (By the way, this example comes straight from Elixir's Documentation)

(In F# it's even more important to make proper left-to-right type inference.)

Now, in the Ruby world, we would prefer to do it in a more Object Oriented fashion, with chained methods like this:

object.method_1.method_2(argument).method_3 { |x| do_something(x) }.method_4

This is how we do things with collections (Enumerables in general), and in Rails. For example, Arel coming into mind:

User.first.comments.where(created_at: 2.days.ago..Time.current).limit(5)

This pattern involves the methods returning a chainable Relation object and further methods changing the internal state of that object.

On the other hand, sometimes we would just want to be able to take adhoc returning objects and passing them ahead and isolating on the methods level instead of the objects level. There is a lot of existing discussions so the idea is not to vouch for one option or another.

In case you want to do the "semi-functional" way, we can do it like this:

Installation

Add this line to your application's Gemfile:

gem 'chainable_methods'

And then execute:

$ bundle

Or install it yourself as:

$ gem install chainable_methods

Usage

The easiest way and one of the most important purposes of this implementation in Ruby is to allow quick prototyping and better interface discovery. The gist of it is to think of "given an input data, what transformation steps should I follow to get to a certain output data?"

For example, given a text with links in it, how do I extract the links, parse them, fetch thee content of a link, parse the HTML, and finally get the title?

This is one such example:

include Nokogiri
CM("foo bar http://github.com/akitaonrails/chainable_methods foo bar")
  .URI.extract
  .first
  .URI.parse
  .HTTParty.get
  .HTML.parse
  .css("H1")
  .text
  .unwrap

And that's it!

Now, an important point is that I am NOT saying that this is a good state to leave your code, but it makes it easy to quickly prototype, test and reason about which parts should be encapsulated in a different method or even a different class.

The only other way to quickly prototype the same thing without Chainable Methods would be to use temporary variables which litter your code with dangerous variables that can be misused and make refactorings more difficult, for example:

sample_text = "foo bar http://github.com/akitaonrails/chainable_methods foo bar"
sample_link = URI.extract(sample_text).first
uri = URI.parse(sample_link)
response = HTTParty.get(uri)
doc = Nokogiri::HTML.parse(response)
title = doc.css("H1").text

Chaining feels way more natural. And in a pseudo-Elixir version it would be something like this:

"foo bar http://github.com/akitaonrails/chainable_methods foo bar"
  |> URI.extract
  |> List.first
  |> URI.parse
  |> HTTParty.get
  |> HTML.parse
  |> css("H1")

So we got similar levels of functionality without compromising the dot-notation and the Ruby style.

And we can advance further in other ways to use this chaining methods scheme to better organize functional-style coding:

# create your Module with composable 'functions'
module MyModule
  include ChainableMethods

  def method_a(current_state)
    # transform the state
    do_something(current_state)
  end

  def method_b(current_state, other_argument)
    do_something2(current_state, other_argument)
  end

  def method_c(current_state)
    yield(current_state)
  end
end

And now we can build something like this:

MyModule.
  chain_from(some_text).
  upcase. # this calls a method from the string in 'some_text'
  method_a.
  method_b("something").
  method_c { |current_state| do_something3(current_state) }.
  unwrap

And that's it. Again, this would be the equivalent of doing something more verbose like this:

a = some_text.upcase
b = MyModule.method_a(a)
c = MyModule.method_b(b, "something")
d = MyModule.method_c(c) { |c| do_something3(c) }

So we have this approach to create modules to serve as "namespaces" for collections of isolated and stateless functions, each being a step of some transformation workflow. A module will not hold any internal state and the methods will rely only on what the previous methods return.

Sometimes we have adhoc transformations. We usually have to store intermediate states as temporary variables like this:

text  = "hello http:///www.google.com world"
url   = URI.extract(text).first }
uri   = URI.parse(url)
body  = open(uri).read
title = Nokogiri::HTML(body).css("h1").first.text.strip

Or now, we can just chain them together like this:

include Nokogiri
CM("hello http:///www.google.com world")
  .URI.extract.first
  .URI.parse
  .chain { |uri| open(uri).read }
  .HTML.parse
  .css("h1")
  .first.text.strip
  .unwrap

I think this is way neater :-) And as a bonus it's also easier to refactor and change the order of the steps or add new steps in-between.

If you don't have a neat "Module.method" format to chain, you can use the #chain call to add transformations from anywhere and keep chaining methods from the returning objects as well, in the same mix, and without those ugly dangling variables.

The shortcut CM(state, context) will wrap the initial state and optionally provide a module as a context upon which to call the chained methods. Without you declaring this context, the chained methods will run the initial state object's methods.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test 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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/akitaonrails/chainable_methods. 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.

CHANGELOG

v0.1.0

initial version

v0.1.1

introduces the ability to wrap any plain ruby object, without the need for a special module to extend the ChainableMethods module first.
fixes the priority of methods to call if both state and context has the same method, context always has precedence

v0.1.2

introduces a shortcut global method 'CM' to be used like this:

CM(2, ['a', 'b', 'c'])
  .[]
  .upcase
  .unwrap
# => "C"

v0.1.3

introduces the #chain method do link blocks of code together, the results are wrapped in the Link object and chained again

v0.1.4

makes the ChainableMethods module "includable" and it automatically makes all instance methods of the parent Module as class methods that can be easily chainable without having to declare all of them as def self.method first. So you can do it like this:

v0.2.1

use a const_get trick to allow to chain Module or Class names directly in the dot notation. Inspired by this gist. Kudos to @bkerley for the idea and letting me know.

License

The gem is available as open source under the terms of the MIT License.