DEV Community: OKURA Masafumi

How to read Gemfile

OKURA Masafumi — Sat, 12 Jun 2021 13:41:11 +0000

Motivation

When we join new projects, what we do first is to understand dependencies. Understanding dependencies helps us to grasp the scope of the project and to read source code smoothly.

For example, if it's a Rails project (and yes, we know it's a Rails project via gem rails line!), we can tell it treats parts of its data as trees with acts_as_tree gem installed. With omniauth-github the project should provide "login with GitHub" feature.

In Ruby, those dependencies are described in Gemfile, a file Bundler provides to define dependencies. Seasoned devs take a look at it and soon find some characteristics or problems.

On the other hand, novices in software development sometimes struggle to read Gemfile. Everything seems new and unfamiliar. There are too much information.

This article aims to help these people who find it difficult to understand dependencies when reading Gemfile.

The basic of Gemfile

The official man page describes the syntax of Gemfile, so I'd like to summarizes it here.

First of all, Gemfile is actually a Ruby file so you can do everything you can with Ruby. For example, you can define classes in Gemfile, though we usually don't have to do so.

The most important part of Gemfile is gem declaration and version constraints. Others are less important.

`gem`

gem declaration tells Bundler that we require that gem as a dependency. Typically it looks like:

gem 'nokogiri'

In the example above, we tell Bundler that we need nokogiri gem as a dependency of the project.

You don't know what nokogiri does? No worry! We'll talk about how to look up each gem does later in this article.

Version constraints

Each gem declaration may be followed by version constraints. It looks like this:

gem 'nokogiri', '>= 1.0'

In this example, we tell Bundler we need nokogiri but it must be version 1.0 or newer. If there's no other dependencies that depend on older nokogiri, the latest one will be installed.

https://guides.rubygems.org/patterns/#pessimistic-version-constraint explains what we can do with version specifiers, so here we don't cover everything.

Version constraints are important because it indicates this dependency is treated somewhat different than others. We default to latest version so that we can benefit from new features and bugfixes. If we cannot use the latest version of that gem, there might be something we should take care of.

How to know what the gem does

When we read Gemfile, we see a bunch of gem names. Some are famous, some are not. Each project has unique list of gems it depends. How should we look up their functionalities and why they're in the list?

There are two aspect in dependencies - what it does in general and why the project needs it. Let's talk one by one.

What it does in general

Let's say we want to know what nokogiri does. The most reliable source is not something we find with google, but https://rubygems.org/, the official rubygems website.

The top page of the official rubygems site has a search box so just enter the name you want to know the feature of. That guides you to the search result page and you'll soon find a link to that gem. In this example you'll reach https://rubygems.org/gems/nokogiri.

On the right column, you'll see "homepage" link. Clicking that navigates us to the (yes) homepage of the gem. It might be a dedicated page of the project or a GitHub README, but it should explains what the gem is for. In this example the homepage of nokogiri is https://nokogiri.org/.

nokogiri's homepage provides lots of information and you'll be probably satisfied. If there's no information you want, you should then search the web with the gem name ("nokogiri" in this example).

When you cannot find you're looking for with the homepage and web search, you might want to take a look at its source code. That's possible by clicking the "Source Code" link also on the right column of the gem page on https://rubygems.org

Why the project needs it

Some gems are well known and every developer with some experience knows what they're for. Some gems are not that famous but provide good documentations. In these cases it's easy to understand what it provides to the project.

In some cases, however, you might want to know more about that gem. If the version constraint of the gem points to old version, you might want to know why you have to use that old version instead of newer or the latest one.

In those situations, bug trackers will help. You can go to bug tracker page by clicking "Bug Tracker" link on the right column. You can find some information about bugs the gem has in bug trackers and sometimes there's a bug that prevents you from using newer versions. For example, https://github.com/sparklemotion/nokogiri/issues is a issue tracker for nokogiri and we can find discussions around bugs.

Things get complicated when the gem is not well known or well documented. In this case, grep is your friend. Searching through the code using grep and other similar tools with the gem name will find the place where the gem is used. That also tells us why we need it.

Conclusion

We illustrated how to read Gemfile and find the information we need on https://rubygems.org, issue trackers and the web.

Reading Gemfile enables us to know more about Ruby's ecosystem. It helps to reduce the possibility of reinventing the wheel and focus on more important things.

What you should know about JSON serialization solution in Ruby

OKURA Masafumi — Thu, 03 Jun 2021 15:56:38 +0000

tl;dr

Alba is a fast and declarative JSON serializer for Ruby that supports typing, rich error handling and ActiveModelSerializers-like APIs.

What is Alba

Alba is a new Ruby library (rubygems) for JSON serialization I've been recently developing.

Why yet another JSON serializer?

Does it spark joy?

As a Ruby developer, I occasionally compare JSON serialization solution in Ruby ecosystem and I'm not fully satisfied with existing ones. They don't spark joy.

Pros and cons of existing JSON serializers for Ruby

Note that this table is totally subjective and not comprehensive, especially in that it doesn't have JSON:API compatible libraries. It's not planned to support JSON:API with Alba and it's not easy to make sense to compare JSON:API compatible ones with "flat" ones.

If you'd like to point out that I'm wrong, or add something to this list, please comment below or contact me on Twitter!

Name	Pros	Cons
ActiveModelSerializers	Stable, lots of articles and documentations	Slower than others, not maintained actively, complex
jbuilder	Part of Rails official gems, well maintained	Lots of DSLs to remember, slow when partials are overused
blueprinter	Simple and fast, supports many features	The terminology is special such as "views" and not easy to understand
representable	Supports JSON, XML and YAML format and many features	Not fast nor simple
jb	Very simple, fast	When building complex JSON the code gets complex and hard to read

Overall, I like the speed and simplicity of blueprinter and feature set representable provides, but didn't find them the best possible.

I can build it myself!

As a programmer I wondered - why can't I create something thats' better than all of them and satisfy myself? And the answer was "yes!"

I wanted my library to be as simple as possible so I named it Alba. See this section of README.

The primary goal of Alba is to be as simple and fast as blueprinter and to be as fully featured as representable.

Hidden goals

I wish my code is something that I can achieve with my best effort. There are some hidden goals of Alba that satisfies me as a programmer:

Smallest - I don't like reading long code, even when it's written by myself. I wish the code is smaller than 500 loc.
Best test coverage - Yes I know that code coverage is not a perfect index for test quality, but I'm not confident enough to think my code works as expected without tests. I keep code coverage higher than 99%.
Best code quality - Thanks to SaaS such as CodeClimate I can tell when my code quality is too low. I try to keep "code smells" absolute zero.

Also I don't want Alba to depend on other gems so that it works well with not only Rails but also in other environments such as Hanami, Sinatra and even standalone. Although some features in Alba depend on ActiveSupport, it's carefully designed not to be required to use Alba itself.

The result

So I've built Alba and the result is impressive.

According to the benchmark Alba is one of the fastest JSON serializer. It also consumes the least amount of memory.

Alba has some unique features such as error handling. It also supports types (only representable supports this) and circular association control (only ActiveModelSerializers supports this).

Alba achieves these features and performance by less than 500 lines of code. It's well tested with 99% test coverage.

I'm proud of my work for now, but there's a still long way to go.

The future of Alba

Alba aims to be the defacto library to serialize objects into JSON in Ruby. It'll provide these advantages over the alternatives:

Speed - Alba will be the fastest among all other JSON serializers
Features - Alba will support most of the features we require daily for serialization, plus some unique features such as typing and custom hooks
Simplicity - Alba will not depend on external gems except for one I built for hooks, that makes it easy to use Alba outside of Rails

ensure doesn't return value implicitly

OKURA Masafumi — Sat, 27 Feb 2021 15:46:12 +0000

In Ruby, ensure clause ensures that the code block is executed when an exception is raised or not.

def foo
  'foo'
ensure
  puts 'ensure'
end

foo # => 'ensure' is output

However, the value in ensure clause is not returned implicitly.

def foo
  'foo'
ensure
  'ensure'
end

foo # => 'foo', not 'ensure'

You need to return value explicitly with return.

def foo
  'foo'
ensure
  return 'ensure'
end

foo # => 'ensure'

`Eval`ing twice to define toplevel module from String

OKURA Masafumi — Sat, 06 Feb 2021 15:54:37 +0000

Sometimes we want to define modules using String and instance_eval.

class A
end

code = <<-CODE
  module B
    module_function
    def b
      puts 'b'
    end
  end
CODE
a = A.new
a.instance_eval code

B.b # => Should print 'b'

However, this code causes NameError saying uninitialized constant B.

Where has it gone? To know where module B is defined, we use ObjectSpace class.

# Replace `B.b` in the snippet above with this
ObjectSpace.each_object(Module) {|m| p m if m.name =~ /::B/ }
# => You see something like "#<Class:0x00007f861b8c8e50>::B"

OK, with instance_eval and String combination, the defined module is put in Anonymous class namespace, the way which we don't like. How to define a toplevel module with instance_eval?

So here's the answer.

class A
end

code = <<-CODE
  module B
    module_function
    def b
      puts 'b'
    end
  end
CODE
a = A.new
a.instance_eval do
  eval code
end
B.b # => "b" is printed

What happened? We eval code string in instance_eval block. I don't know why but this code just does what we want to do.

Ruby: proc and lambda

OKURA Masafumi — Sat, 23 Jan 2021 12:37:03 +0000

Example

hash = {foo: :bar}
nested_array = [[1, 2]]
proc_printer = Proc.new {|a, b| puts "a: #{a}, b: #{b}" }
lambda_printer = lambda {|a, b| puts "a: #{a}, b: #{b}" }

hash.each(&proc_printer) # => a: foo, b: bar
nested_array.each(&proc_printer) # => a: 1, b: 2
hash.each(&lambda_printer) # => a: foo, b: bar
nested_array.each(&lambda_printer) # => wrong number of arguments (given 1, expected 2) (ArgumentError)

What happened?

A lambda takes argument differently than a proc does. In this case, an array in nested array case "gets extracted" into two arguments with a proc, while it is passes as one array with a lambda.

Procs behave like blocks, and lambdas behave like methods. When used with methods such as each, which are usually used with blocks, it might be a good idea to use procs instead of lambdas.

You can `bundle e` instead of `bundle exec`

OKURA Masafumi — Fri, 05 Jun 2020 05:43:39 +0000

OK, you're tired of typing bundle exec all the time when you develop Ruby/Rails application. I'd suggest defining an alias for it, just like:

# Save this in your shell profile such as .bashrc or .zshrc
alias be="bundle exec"

be rspec # bundle exec rspec

But if you're lazy enough, you don't have to anything. Just type

bundle e rspec

and it works! Enjoy saving time!

Installing libxml-ruby on macOS

OKURA Masafumi — Mon, 27 Apr 2020 08:32:23 +0000

I always cannot find the way to install libxml-ruby gem which is used by Rails, so here's a command:

gem i libxml-ruby -- --with-xml2-dir=`brew --prefix libxml2` --with-xml2-config=`brew --prefix libxml2`/bin/xml2-config