0.0
No commit activity in last 3 years
No release in over 3 years
A small framework that enables encapsulating pieces of code within eachother.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.14
~> 10.0
~> 3.0

Runtime

 Project Readme

Encapsulate

A small Ruby framework that enables encapsulating pieces of code within eachother.

Branch Status
Release Build Status Coverage Status Gem Version Total Downloads
Development Build Status Coverage Status

What is this?

Ever get tired of writing exception handling blocks? Ever think it's not really DRY (Don't Repeat Yourself)?

With Ruby instead of...

begin
  read_file
rescue IOError => e
  handle_io_error
ensure
  close_io
end

... you can do

def handle_io_error
  begin
    yield
  rescue IOError => e
    handle_io_error
  ensure
    close_io
  end
end

handle_io_error do
  read_file
end

... and with Encapsulate you can do

run callback: read_file, with: io_error_handling

Not to mention code duplications that are otherwise difficult to get rid of...

signal_processing_start
start_time_measurement

process

stop_time_measurement
signal_processing_end

How about...

lifecycle_signals do
  time_measurement do
    read_file
  end
end

... or with Encapsulate

run callback: process, with: [time_measurement, lifecycle_signals]

Encapsulate provides an alternaive solution utilizing a function-like syntax instead of nesting.

How does it work?

We essentially want to create the following structure:

encapsulator1
  # ...
  encapsulator2
    # ...
      base_function
        # ...
      end
    # ...
  end
  # ...
end

In order to achieve this each encapsulator function must know the next one in the chain (the last one being the base function). Also the parameters of the base function must be carried by the encapsulators. Our pseudocode should look something like this:

def encapsulator1(callback:, params: nil)
  # some logic...
  def encapsulator2(callback:, params: nil)
    # some logic...
      base_function(params)
    # some logic...
  end
  # some logic...
end

How to use it?

The encapsulators gem contains a collection of practical functions to be used with Encapsulate. You may check if your use case is already implemented. If not then please consider contributing it.

Below you will find some insight on how to create and structure your call chains but you can also head right to the unit tests for hands-on examples.

Building the chain

require 'encapsulate'
# Single encapsulator
Encapsulate.run callback: base_function, with: [encapsulator]

# Multiple encapsulators
# They will apply in the given order: encapsulator2(encapsulator1(callback))
Encapsulate.run callback: base_function, with: [encapsulator1, encapsulator2]

# Parameters
Encapsulate.run callback: base_function, with: [encapsulator1, encapsulator2], params: {arg: 'something'}

Base function

To sidestep the issue of varying number of parameters we must use keyword arguments or a single Hash parameter in the base function.

def self.base_function(my_param:, my_other_param:)
  # ...
end

base_function = self.method(:base_function)

Encapsulators

Encapsulators should be implemented (for reasons detailed in the previous chapter) along the lines of:

def self.my_encapsulator(callback:, params: nil)
  # ...
  params.nil? ? callback.call : callback.call(params)
  # ...
end

my_encapsulator = self.method(:my_encapsulator)

The base function may take no parameters which is why params in our interface must default to nil and we also need to take care of calling the callback accordingly. This small piece of logic is implemented in the gem reflection_utils (as seen below) alongside with other useful reflection related functions.

You may use any objects that respond to call. The only difference will be in how you reference these objects. These are also valid skeletons:

my_encapsulator = lambda do |callback:, params: nil|
  # ...
  ReflectionUtils.call(callback, params)
  # ...
end
my_encapsulator = Proc.new do |callback:, params: nil|
  # ...
  ReflectionUtils.call(callback, params)
  # ...
end

Encapsulators will ideally not use any parameters. They do take the base function's parameter hash as second parameter and you could technically hide additional parameters there but it's not a good practice. Instead:

  • try to keep encapsulators simple
  • use their own classes to configure them

This brings us to how to structure encapsulators. You have several options.

1 class per encapsulator

class ExceptionEncapsulator
  def self.callback(callback:, params: nil)
    # ...
  end
end

Collcetor class

class Encapsulators
  def self.exception_handling(callback:, params: nil)
    # ...
  end
  
  def self.time_measurement(callback:, params: nil)
    # ...
  end
  
  # ...
end

In place

my_encapsulator = lambda do |callback:, params: nil|
  # ...
end

Installation

Add this line to your application's Gemfile:

gem 'encapsulate'

And then execute:

$ bundle

Or install it yourself as:

$ gem install encapsulate

Feedback

Any feedback is much appreciated.

I can only tailor this project to fit use-cases I know about - which are usually my own ones. If you find that this might be the right direction to solve your problem too but you find that it's suboptimal or lacks features don't hesitate to contact me.

Please let me know if you make use of this project so that I can prioritize further efforts.

Development

This gem is developed using Bundler conventions. A good overview can be found here.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/thisismydesign/encapsulate.

License

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