A configuration system for ruby CLIs

If you have developed Rails applications you might be familiar with its configuration system but if your are working on a CLI utility you might miss part of that convenience.

Let me share with you a simple system that gets you set with just a couple of files:

The hook

somewhere close to the first lines of code you run you have something like this:

 options = Parser.parse_options Config.setup(**options) 

I do this just after setting zeitwerk up.
the you need 2 files:

The Parser

This is based on rubys stdlib's OptionParser class.

require "optparse" module Parser extend self def parse_options options = {} OptionParser.new do |parser| load(parser, options) progress(parser, options) memory(parser, options) #... end.parse! options end def load(parser, options) parser.on("-l", "--load", "Load data files") do |l| options[:load_files] = l end end def progress(parser, options) parser.on("-p", "--progress", "Show progress bar for long processes") do |p| options[:progress] = p end end def memory(parser, options) parser.on("-M", "--memory", "Use in-memory db") do |m| options[:memory] = m end end #... end 

This is very reusable because it is initializing options as an empty hash, a returning a hash with only the options that have been set up.

If you want to show the default value on some option you can use #{Config::DEFAULTS[:option_name]}.

But if you are not using the next part, you can just use this and have a hash of options to store where you like.

The Config Singleton

require "singleton" # Global configuration object with automatic defaults # # Usage: # Configure with: Config.setup(load_files: true, ...) # Access with: Config.value(:load_files) # class Config include Singleton DEFAULTS = { load_files: false, progress: false, memory: false, option_name: "default_value", }.freeze Options = Data.define(*DEFAULTS.keys) def self.setup(**) = instance.setup(**) def self.value(key) raise ArgumentError, "Unknown configuration key: #{key}" unless DEFAULTS.key?(key) instance.config.public_send(key) end def config = @config ||= Options.new(*DEFAULTS.values) def setup(**kwargs) updated_values = DEFAULTS.merge(kwargs) @config = Options.new(*updated_values.values_at(*DEFAULTS.keys)) end end 

First we declare DEFAULTS as a hash with the keys being our option names and the values being the default values if the option is not explicitly configures by the user.

Then we define the Value Object with

 Options = Data.define(*DEFAULTS.keys) 

This takes advantage of Ruby's Data.define functionality. You can see the documentation here, but the TL;DR it is a Struct like immutable object.

The we have this slightly cryptic:

 def self.setup(**) = instance.setup(**) 

This means, if you call Config.setup on the class, we are going to call it on the (singular) instance that is keeping the state.

Then you have a class method for reading a config value:

 def self.value(key) raise ArgumentError, "Unknown configuration key: #{key}" unless DEFAULTS.key?(key) instance.config.send(key) end 

It uses DEFAULTS as an allow list to prevent the dynamic send we do on the Data instance from posing any security risk on malicious config keys.

We would use instance.config.to_h[key] instead.

The we have

 def config = @config ||= Options.new(*DEFAULTS.values) 

which is memoizing the value object on the Singleton instance.

And then the trickiest part:

 def setup(**kwargs) updated_values = DEFAULTS.merge(kwargs) @config = Options.new(*updated_values.values_at(*DEFAULTS.keys)) end 

This is the method that allows you to update a config value (or several). Because Data.define object are immutable, when you have a new config, you create a new one based on the existing one plus your changes.

If you choose to use a hash instead of a Data.define, you could use merge! here.

This is the method that we were calling from "the hook" with the options hash returned from the Parser class.

With just this now you have a global Config object you can access anywhere in your app.

If you want extra ergonomics, you can have a concern like this:

module Configurable def self.included(base) base.extend Methods # for class methods base.include Methods # for instance methods end # Methods module to allow including and extending module Methods # Convenience method for configuration values def config(key, setup_config: ::Setup::Config) setup_config.value(key) end end end 

And then in any of you classes do something like:

class MyClass include Configurable def my_method if config :option_name puts "optional behavior" end end 

I hope you find it useful.

Let me know if you use it on any projects.

--
cover image: yinka adeoti