Mike Slinn
Mike Slinn

Ruby Gem Scaffold Generation With Thor

Published 2023-06-06. Last modified 2023-06-12.
Time to read: 5 minutes.

This page is part of the ruby collection, categorized under Ruby.

Recently I wrote a command-line program (CLI) in Ruby. It was straightforward to write and worked well.

However, if I had used a special-purpose library for building CLIs, over the lifetime of my CLI program, the accumulated time for maintanance might have been much less. This could only be realized if the mythical library:

  • Was well designed.
  • Had the necessary features.
  • Continues to be well maintained.
  • Had good documentation.

Unfortunately, open-source software rarely fits this description.

Writing Yet Another CLI

Next, I wanted to write another command-line program, this time a generator of various types of Ruby gems. Unlike my previous CLI project, this one had the following criteria:

  • The source code needed to be easy to understand.
  • The overall program needed to be flexible in how it could be used.
  • The resulting software must be easy to maintain.
  • Development and deployment must rely on stable techology.

I found an old Ruby gem generator, creategem, written by Igor Jancev. Although the project had not been updated in 7 years, it was well written. I decided to update the project and extend it for my use. The project used the Thor gem. You can see my progress at creategem.

I could have used dry-cli instead of thor. But I did not. Maybe next time.

The Mighty Thor

Written by the Ruby on Rails programmers, Thor is an open-source toolkit for building powerful command-line interfaces.

This software is a classic example of programmers scratching their own itch. They were not motivated at all to help others learn how to use the program. If you want to understand how to best use Thor, you should expect to spend time reading the source code.

Thor is used by 2.1M GitHub projects

Despite the huge number of GitHub projects that are based on Thor, very few of them were written by humans. Instead, Ruby on Rails has used thor since Rails v3 for code generation. For example, commands like rails new, rails console, rails server, and rails routes are implemented with thor.

Please note: Thor, by design, is a system tool created to allow seamless file and url access, which should not receive application user input.
 – Thor README on GitHub

The above is not the full story.

Actions - Thor::Actions are helpers for your Thor tasks that make typical actions, like file system interaction or command line user dialogue, easier.
 – Thor Wiki

The Actions whose sole purpose is to interact with a user are: ask, indent, mute, mute?, no, print_in_columns, print_table, print_wrapped, say, say_error, set_color, terminal_width, and yes?.

My Evaluation

Thor is:

  1. Well designed
  2. Well maintained
  3. Useful and powerful
  4. Has no change log, and some features have changed a lot over the years. For example, the old option statement was renamed some years ago to method_option, however, the old options variable was not renamed. I have not found any mention of that ... and it makes looking at old code confusing.
  5. Put to shame with out-of-date and dramatically incomplete user-oriented documentation
  6. Has decent comments in the source code for Actions, and other portions of the code base. This means the RubyDoc for Thor is useful, if you have time and the ability to put it all together in your mind.
  7. Lacking in accessible examples that exercise the current API. If you have access to a working program the task of learning the API becomes much easier.

Maybe all that is needed is for someone to write a decent book about Thor.

I Wrote Some Docs

Thor CLI

A command called thor was installed when the thor gem installed.

Shell
$ which thor
/home/mslinn/.rbenv/shims/thor 

$ thor help
Commands:
  thor help [COMMAND]  # Describe available commands or one specific command
  thor install NAME    # Install an optionally named Thor file into your system commands
  thor installed       # List the installed Thor modules and commands
  thor list [SEARCH]   # List the available thor commands (--substring means .*SEARCH)
  thor uninstall NAME  # Uninstall a named Thor module
  thor update NAME     # Update a Thor file from its original location
  thor version         # Show Thor version

Unfortunately, the help message does not state what the thor command is for. Google brought me to the thor man page, which was weird, because no such man page got installed on my Ubuntu system when I installed the thor gem, and apt does not have such a package available from the default Ubuntu 23.04 PPAs.

The man page says:

thor - Scripting framework for command line utilities

Thor is a scripting framework designed for command line utilities. It is supposed to be a replacement for rake, sake and rubigen.
 – Debian man page for thor

Really? Never would have known that from any other source. If this were true, I would expect at least some documentation. I call bullshit.

No-one needs the thor command-line utility for any purpose... unless you want an example of how to use thor. If that is something you want, the command’s source is provided in lib/thor/runner.rb. Just keep in mind that this program contains a lot of use-case-specific code that probably does not match your needs, and their use case is not expressed anywhere. I humbly suggest that creategem is a much better example to learn from.

BTW, rubigen is a defunct GitHub project that vanished without a trace. Sake never was anything to speak of.

Nevermind, thor is a useful and valuable program, even if its creators are woefully misguided in the documentation department.

ERB Syntax

Other than the comments in the source code, accessible via RubyDoc, I have not found any user-accessible documentation on Thor templates.

However, I realized that templates use ERB syntax, after I saw error messages from erb. Since Thor has no defined dependencies that pertain to scriptlet support, and ERB is builtin to Ruby, ERB syntax was apparently implemented.

In Visual Studio Code

The comment “This implementation is based in Templater actions”, found in the Actions module source code, suggests that this portion of the Thor source code was modified from the templater source code, since Thor does not have the templater gem as a dependency. The templater RubyDoc seems to fit what I have noticed so far about Thor’s template capability. This does not qualify as proper documentation for thor, but it should help guide future detective work.

Actions

Thor Actions can:

  • Define Thor runtime options
  • Define paths for template sources
  • Transform template directory contents recursively.

The code I inherited from Igor Jancev used the directory and template actions.

Undocumented Run Options

The run command is documented as having options :verbose, :capture and :with. Examining the source for run we see the following undocumented, yet very useful, additional options: :abort_on_failure, :capture, and :pretend.

Some commands, like git-commit, do not return zero return codes on a successful invocation. To make them work without prematurely ending the Thor program, write:

my_thor_program.rb
run "git commit -aqm 'Initial commit'", abort_on_failure: false

References