Improve Your Ruby with the Adapter Design Pattern

Key Takeaways

• The Adapter Design Pattern in Ruby allows for greater flexibility and easier addition of new methods by separating implementations into modules, rather than using conditional branching.
• The Adapter Design Pattern can be seen in action in gems such as multi_json, ActiveRecord, and moneta, which parse JSON, interact with databases, and provide a unified interface to key-value stores, respectively.
• The Adapter Design Pattern can also be used to create a gem that allows the user to choose an adapter for a rudimentary CSV parser, as demonstrated in the tutorial section of the text.
• The Adapter Design Pattern promotes code reusability and flexibility, allows for interaction with a uniform interface regardless of the underlying class or interface, and enables classes to work together that couldn’t otherwise due to incompatible interfaces.

👁 Image

Imagine we have some code where we want to accomplish things in a variety of ways. One way to do this is with conditional branching:

class Animal
 def speak(kind)
 puts case kind
 when :dog then "woof!"
 when :cat then "meow!"
 when :owl then "hoo!"
 end
 end
end
Animal.new.speak(:dog)

This works, but what if a developer wants to add a new way? With conditional branching, the entire method would need to be overwritten. Instead, we can separate the implementations into modules:

class Animal
 module Adapter
 module Dog
 def self.speak
 puts "woof!"
 end
 end
 module Cat
 def self.speak
 puts "meow!"
 end
 end
 end
 def speak
 self.adapter.speak
 end
 def adapter
 return @adapter if @adapter
 self.adapter = :dog
 @adapter
 end
 def adapter=(adapter)
 @adapter = Animal::Adapter.const_get(adapter.to_s.capitalize)
 end
end
animal = Animal.new
animal.speak
animal.adapter = :cat
aanimal.speak

This is a lot more code! However, if we want to add another module, it’s not too bad and a lot more flexible:

class Animal
 module Adapter
 module Owl
 def self.speak
 puts "hoo!"
 end
 end
 end
end
animal.adapter = :owl
animal.speak

This new module could even go in a separate gem – and with its own dependencies! Organizing things this way is called the adapter design pattern. Let’s look at a few examples of this pattern in the wild.

multi_json

A good example is the multi_json gem which parses JSON with the fastest available backend. In multi_json, each backend is contained in an class that descends from Adapter. Here’s multi_json/lib/multi_json/adapters/gson.rb.

require 'gson'
require 'stringio'
require 'multi_json/adapter'
module MultiJson
 module Adapters
 # Use the gson.rb library to dump/load.
 class Gson < Adapter
 ParseError = ::Gson::DecodeError
 def load(string, options = {})
 ::Gson::Decoder.new(options).decode(string)
 end
 def dump(object, options = {})
 ::Gson::Encoder.new(options).encode(object)
 end
 end
 end
end

Here, load executes each library’s method for turning a JSON string into an object, and dump executes the method for turning an object into a string.

ActiveRecord

ActiveRecord is Rails’ ORM library for interacting with relational databases. It relies on the adapter pattern to allow the developer to interact with any supported database using the same methods. We can find this pattern in ActiveRecord‘s connection_adapters.

module ActiveRecord
 module ConnectionAdapters # :nodoc:
 extend ActiveSupport::Autoload
 autoload :Column
 autoload :ConnectionSpecification
 autoload_at 'active_record/connection_adapters/abstract/schema_definitions' do
 autoload :IndexDefinition
 autoload :ColumnDefinition
 autoload :ChangeColumnDefinition
 autoload :ForeignKeyDefinition
 autoload :TableDefinition
 autoload :Table
 autoload :AlterTable
 autoload :ReferenceDefinition
 end
 autoload_at 'active_record/connection_adapters/abstract/connection_pool' do
 autoload :ConnectionHandler
 autoload :ConnectionManagement
 end
 autoload_under 'abstract' do
 autoload :SchemaStatements
 autoload :DatabaseStatements
 autoload :DatabaseLimits
 autoload :Quoting
 autoload :ConnectionPool
 autoload :QueryCache
 autoload :Savepoints
 end
 ...
 class AbstractAdapter
 ADAPTER_NAME = 'Abstract'.freeze
 include Quoting, DatabaseStatements, SchemaStatements
 include DatabaseLimits
 include QueryCache
 include ActiveSupport::Callbacks
 include ColumnDumper
 SIMPLE_INT = /\A\d+\z/
 define_callbacks :checkout, :checkin
 attr_accessor :visitor, :pool
 attr_reader :schema_cache, :owner, :logger
 alias :in_use? :owner
 ...
 attr_reader :prepared_statements
 def initialize(connection, logger = nil, config = {}) # :nodoc:
 super()
 @connection = connection
 @owner = nil
 @instrumenter = ActiveSupport::Notifications.instrumenter
 @logger = logger
 @config = config
 @pool = nil
 @schema_cache = SchemaCache.new self
 @visitor = nil
 @prepared_statements = false
 end
 ...

ActiveRecord includes many adapters, including MySQL and PostgreSQL here. Look through a couple of those to see great examples of this pattern.

Moneta

One of my favorite gems is moneta which is a unified interface to key-value stores, such as Redis. Here is an example of using a file as a key-value store:

require 'moneta'
# Create a simple file store
store = Moneta.new(:File, dir: 'moneta')
# Store some entries
store['key'] = 'value'
# Read entry
store.key?('key') # returns true
store['key'] # returns 'value'
store.close

From the user’s perspective, accessing both redis and daybreak is as simple as reading or modifying a hash. Here’s what the daybreak adapter looks like (comments removed to save space):

require 'daybreak'
module Moneta
 module Adapters
 class Daybreak < Memory
 def initialize(options = {})
 @backend = options[:backend] ||
 begin
 raise ArgumentError, 'Option :file is required' unless
options[:file]
 ::Daybreak::DB.new(options[:file], serializer:
::Daybreak::Serializer::None)
 end
 end
 def load(key, options = {})
 @backend.load if options[:sync]
 @backend[key]
 end
 def store(key, value, options = {})
 @backend[key] = value
 @backend.flush if options[:sync]
 value
 end
 def increment(key, amount = 1, options = {})
 @backend.lock { super }
 end
 def create(key, value, options = {})
 @backend.lock { super }
 end
 def close
 @backend.close
 end
 end
 end
end

Creating an Adapter Gem

Let’s make a gem that allows the user to choose an adapter for a rudimentary CSV parser. Here’s what our folder structure will look like:

├── Gemfile
├── Rakefile
├── lib
│   ├── table_parser
│   │   └── adapters
│   │   ├── scan.rb
│   │   └── split.rb
│   └── table_parser.rb
└── test
 ├── helper.rb
 ├── scan_adapter_test.rb
 ├── split_adapter_test.rb
 └── table_parser_test.rb

Dependencies

Add minitest and ruby "2.3.0" to the Gemfile:

# Gemfile
source "https://rubygems.org"
ruby "2.3.0"
gem "minitest", "5.8.3"

Ruby 2.3 adds the new squiggly heredoc syntax which will be useful in this case as it prevents unnecessary leading whitespace. Adding it to the Gemfile will not install it. It will need to be installed separately with a command like (if you use RVM):

$ rvm install 2.3.0

Test Support

Add a Rakefile that lets use rake to run all of our tests:

# Rakefile
require "rake/testtask"
Rake::TestTask.new do |t|
 t.pattern = "test/*_test.rb"
 t.warning = true
 t.libs << 'test'
end
task default: :test

t.libs << 'test' adds the test folder to our $LOAD_PATH when running the task. The lib folder is included by default.

The Main Module

lib/table_parser.rb will implement what the user accesses when they use the gem:

# lib/table_parser.rb
module TableParser
 extend self
 def parse(text)
 self.adapter.parse(text)
 end
 def adapter
 return @adapter if @adapter
 self.adapter = :split
 @adapter
 end
 def adapter=(adapter)
 require "table_parser/adapters/#{adapter}"
 @adapter = TableParser::Adapter.const_get(adapter.to_s.capitalize)
 end
end

::adapter sets a default adapter the first time it is called. Notice that adapters are not loaded until they are set. This avoids exposing developers to bugs in unused adapters and allows adapters in the same project to use their own dependencies without requiring all dependencies for all adapters up front.

The Adapters

The first adapter parses using the scan method with an appropriate regular expression. The regex delimiter searches for either anything that is not a comma or two consecutive commas:

# lib/table_parser/adapters/scan.rb
module TableParser
 module Adapter
 module Scan
 extend self
 def parse(text)
 delimiter = /[^,]+|,,/
 lines = text.split(/\n/)
 keys = lines.shift.scan(delimiter).map { |key| key.strip }
 rows = lines.map do |line|
 row = {}
 fields = line.scan(delimiter)
 keys.each do |key|
 row[key] = fields.shift.strip
 row[key] = "" if row[key] == ",,"
 end
 row
 end
 return rows
 end
 end
 end
end

The second adapter parses using the split method with another regular expression:

# lib/table_parser/adapters/split.rb
module TableParser
 module Adapter
 module Split
 extend self
 def parse(text)
 delimiter = / *, */
 lines = text.split(/\n/)
 keys = lines.shift.split(delimiter, -1)
 rows = lines.map do |line|
 row = {}
 fields = line.split(delimiter, -1)
 keys.each { |key| row[key] = fields.shift }
 row
 end
 return rows
 end
 end
 end
end

Test Helper

The main thing that needs to be done here is setting up the minitest dependencies, and we can go ahead and load the project code as well. This is not really a necessary file here, but it’s common in larger projects.

# test/test_helper.rb
require "minitest/autorun"
require "table_parser"

Shared Test Examples

We should avoid duplicating all tests for each adapter. Instead, we will write shared examples that will be pulled in from simpler adapter test files:

# test/table_parser_test.rb
require "test_helper"
module TableParserTest
 def test_parse_columns_and_rows
 text = <<~TEXT
 Name,LastName
 John,Doe
 Jane,Doe
 TEXT
 john, jane = TableParser.parse(text)
 assert_equal "John", john["Name"]
 assert_equal "Jane", jane["Name"]
 assert_equal "Doe", john["LastName"]
 assert_equal "Doe", jane["LastName"]
 end
 def test_empty
 text = <<~TEXT
 Name,LastName
 TEXT
 result = TableParser.parse(text)
 assert_equal [], result
 end
 def test_removes_leading_and_trailing_whitespace
 text = <<~TEXT
 , Name,LastName
 ,John , Doe
 , Jane, Doe
 TEXT
 john, jane = TableParser.parse(text)
 assert_equal "John", john["Name"]
 assert_equal "Jane", jane["Name"]
 assert_equal "Doe", john["LastName"]
 assert_equal "Doe", jane["LastName"]
 end
end

Adapter Test Files

Next, for each adapter we need a test that will run the shared examples on it. Since the test examples are in a separate file and shared, these are pretty compact.

First, one for the scanning adapter:

# test/scan_adapter_test.rb
require "table_parser_test"
class TableParser::ScanAdapterTest < Minitest::Test
 include TableParserTest
 def setup
 TableParser.adapter = :scan
 end
end

Next, for the splitting adapter:

# test/split_adapter_test.rb
require "table_parser_test"
class TableParser::SplitAdapterTest < Minitest::Test
 include TableParserTest
 def setup
 TableParser.adapter = :split
 end
end

Running the Test Suite

Thanks to the Rakefile, verifying that both of the adapters work is easy;

$ rake
Run options: --seed 26993
# Running:
......
Fabulous run in 0.001997s, 3004.7896 runs/s, 9014.3689 assertions/s.
6 runs, 18 assertions, 0 failures, 0 errors, 0 skips

Conclusion

Adapters are great ways to incorporate multiple ways of accomplishing something without resorting to mountains of conditional branching. They also let you split approaches into separate libraries that can have their own dependencies. If adapters are loaded in a lazy manner, broken adapters will not affect a project unless they are used.

Stay tuned for more great design pattern articles!

Frequently Asked Questions (FAQs) about the Adapter Design Pattern in Ruby