Jekyll2026-05-13T07:53:40-04:00https://www.mslinn.com/feed/ruby.xmlMike Slinn | RubyMike SlinnHighline Gem and Workalike2025-09-25T00:00:00-04:002025-09-25T00:00:00-04:00https://www.mslinn.com/ruby/6650-highline
Highline
Highline
is a gem that is often found in CLIs that are built with OptionParser.
It provides a way to ask the user questions and get answers,
similar in syntax to methods that Thor provides for the same purpose.
The agree method
is particularly useful.
Both the agree and
ask methods
have a quirky feature:
putting a space at the end of the question string suppresses the newline between the question and the answer.
The optional character parameter causes the first character that the user types to be immediately
processed without requiring them to press Enter.
my_cli.rb
$ irb
irb(main):001> require 'highline'
=> true
irb(main):002* begin
irb(main):003* printf "Work work work"
irb(main):004> end while HighLine.agree "\nAll done! Do you want to do it again? ", character = true
Work work work
All done! Do you want to do it again?
Please enter "yes" or "no".
All done! Do you want to do it again? y
Work work work
All done! Do you want to do it again? y
Work work work
All done! Do you want to do it again? n
=> nil
irb(main):005>
Workalike
Below is some code that I wrote for
Nugem.
This could be hived into a separate gem, if someone was to ask.
The import statement
imports the methods of the Highline library directly into the current namespace.
highline_wrappers.rb
require 'highline/import'
# Augment Highline
module HighlineWrappers
def self.maybe_redirect_stdin
input_from_env = ENV.fetch('nugem_argv', nil)
return unless input_from_env
require 'stringio'
$stdin = StringIO.new(input_from_env)
puts 'Reading STDIN from the nugem_argv environment variable.'
end
def yes_no?(prompt = 'More?', default_value: true)
answer_letter = ''
suffix = default_value ? '[Y/n]' : '[y/N]'
default_letter = default_value ? 'y' : 'n'
acceptable_responses = %w[y n]
until acceptable_responses.include? answer_letter
if $stdin.tty? # Read from terminal
answer_letter = ask("#{prompt} #{suffix} ") do |q|
q.limit = 1
q.case = :downcase
end
else
$stdin.read # from pipe
end
answer_letter = default_letter if answer_letter.empty?
end
answer_letter == 'y'
end
# Invokes yes_no? with the default answer being 'no'
def no?(prompt = 'More?')
yes_no? prompt, default: false
end
# Invokes yes_no? with the default answer being 'yes'
def yes?(prompt = 'More?')
yes_no? prompt, default: true
end
end
# Monkey patch Highline
class HighLine
alias highline_ask ask
def ask(template_or_question, answer_type = nil, &)
if $stdin.tty? # highline handles terminal I/O
highline_ask(template_or_question, answer_type, &)
else
read_from_pipe(template_or_question, answer_type, &)
end
end
def read_from_pipe(prompt, answer_type, &)
if prompt.end_with? ' '
print prompt
else
puts prompt
end
q = HighLine::Question.new(prompt, answer_type, &)
q.answer = $stdin.read
unless q.answer
puts 'EOF encountered.'.red
exit! 1
end
puts q.answer
return q.answer if q.answer == '' # Caller must provide the default value or action
unless q.valid_answer?
error_message = q.responses[:not_valid] ||
q.responses[:not_in_range] ||
'Validation failed.'
puts "Input '#{q.answer}' is invalid: #{error_message}".red
exit! 33
end
q.answer
end
end
The above code can be mixed into any class or module.
They ask the user a question and return true or false based on the user’s response.
The methods in the code issue a prompt and then read just one character from the user.
The user can respond by typing the single character y to answer “yes”
or n to answer “no”.
If the user presses Space or Enter without typing anything else,
the default answer is used.
The following irb session shows how to use the yes? and no? methods.
irb session
irb(main):152> yes? 'asdf'
asdf [Y/n] Enter or Space=> true
irb(main):153> yes? 'asdf'
asdf [Y/n] n
=> false
irb(main):154> no? 'asdf'
asdf [y/N] Enter or Space=> false
irb(main):155> no? 'asdf'
asdf [y/N] n
=> false
irb(main):156> no? 'asdf'
asdf [y/N] y
=> true
Data Pipelines
highline_wrappers.rb, above, provides support for data pipelines.
The following is an example of a pipeline that feeds a multiline string with three lines into the STDIN of a one-line Ruby program.
The Ruby program merely reverses the order of the lines that it receives and sends the result to STDOUT.
Shell
$ printf "a\nb\nc\n" | ruby -e 'puts $stdin.readlines.reverse'
c
b
a
You could use data pipelines to drive a CLI you wrote that uses my version of \
ask, yes? and no?.
Debugging With Visual Studio Code
When Visual Studio Code debugs a Ruby program that it launched, the debugee
does not enjoy the niceties that a shell like Bash would have provided.
For example, there is no way to specify an input stream in a Visual Studio Code launch configuration,
and my experience with attaching to external terminals from rdbg and ruby_lsp has not been good.
Using Visual Studio Code to debug a program that performs user dialog is problematic.
This makes debugging a CLI that interacts with a user through dialog difficult.
I considered the following possible solutions:
Launch the the program under a monitor, pause execution, and then
attach Visual Studio Code to the monitor.
That works well, but that can involve a lot of fussing until things work just right.
BTW, when the program first launches, it examines the VO_DEBUGGING environment variable
to see if it should load the rest of the program from the project directory,
or if it should load the rest of itself from an installed gem.
All my gems work that way.
Redirect STDIN to read from a pipeline.
This approach works well for scripted environments, but does not help us with debugging via Visual Studio Code.
Redirect STDIN to read from an environment variable.
This approach works well for all scenarios.
Solution: nugem_argv
The third option is the best choice.
I decided to make the program look for an environment variable called nugem_argv.
If present, its value would be used as STDIN.
playground/nugem_argv.rb
def maybe_redirect_stdin
input_from_env = ENV.fetch('nugem_argv', nil)
return unless input_from_env
require 'stringio'
$stdin = StringIO.new(input_from_env)
puts 'Reading STDIN from the nugem_argv environment variable.'
end
# Define the environment variable
ENV['nugem_argv'] = "Hello from Mars\nHello from Venus\nGoodbye\n"
maybe_redirect_stdin
# Now any code that reads from standard input (like gets) will read from ENV['nugem_argv'].
# Echo STDIN to STDOUT line by line until EOF.
# Do not call $stdio.eof? to test EOF because it will block until the process exits
# if STDIN is a pipe or socket.
# Instead, detect when STDIN reaches EOF by gets returning nil
while line = gets # rubocop:disable Lint/AssignmentInCondition
puts line
end
We can test the above:
Shell
$ ruby playground/nugem_argv.rb
Reading STDIN from the nugem_argv environment variable.
Hello from Mars
Hello from Venus
Goodbye
After incorporating the maybe_redirect_stdin method shown above into nugem,
we can use the following launch configurations for testing CLI user dialog:
Visual Studio Code Launch Configurations with STDIO from nugem_argv
{
{
"debugPort": "0",
"env": {
"nugem_argv": "Hello from Mars\nHello from Venus\nGoodbye\n",
"VO_DEBUGGING": "true"
},
"name": "Nugem overwrite /tmp/nugem_test",
"script": "${workspaceFolder}/exe/nugem ruby test -o /tmp/nugem_test --force",
"request": "launch",
"type": "rdbg",
"useBundler": true,
},
{
"env": {
"nugem_argv": "Hello from Mars\nHello from Venus\nGoodbye\n",
"VO_DEBUGGING": "true"
},
"name": "ruby_lsp nugem jekyll test --force --private --tag=tag1",
"program": "ruby exe/nugem jekyll test --force --private --tag=tag1",
"request": "launch",
"type": "ruby_lsp",
},
}
Ruby ERB
expands Ruby expressions embedded in HTML or markup such that the encapsulated expression is replaced by its value.
ERB ultimately calls eval, with some wrapping for safety and binding control.
Export Execution Contexts Via Ruby Bindings
I have been developing the next-generation Nugem code
for a fair while yet.
This command-line program was being constructed so that it would generate
new working Ruby gems from command-line parameters.
When generating a new Ruby gem,
Nugem needs to inflate ERB templates embedded within file system templates.
The problem I encounted was that the values I wanted to inflate ERB templates with were defined in very different binding contexts.
To me, this sounded like there was a need for rudimentary management of Ruby binding context.
Easy, Simple, Flexible Ruby Binding Management
I was not happy with what I could see out there on the interwebs for assembling custom Ruby Bindings,
so I created the CustomBinding Ruby gem.
It provides a simple and flexible way of constructing a custom Ruby binding,
and simplifies the rendering of ERB templates from a custom Ruby binding.
CustomBinding provides an easy, simple and flexible way of specifying
variable and method references in ERB templates.
The CustomBinding#render method resolves the embedded references
against the CustomBinding internal state.
Nugem uses ERB templates to create every type of text file that a Ruby Gem needs.
This includes Ruby code, RSpec tests, markdown files, .gitignore, and more.
ERB templates support expressions that contain:
References to self
Local, instance, and global variable names
Local and instance public method names
Computation using the above
An ERB template consists of a String expression enclosed in single or double quotes, or provides as a here doc.
object_id
Every Ruby object has a unique identifier.
IRB Session
$ x = Object.new
=> #<Object:0x00007fcd79d5c9a8>
irb(main):002> x.object_id
=> 7160
If you find two variables with the same unique identifier,
then they are aliases, or mirrors, for each other.
This information could be helpful as you explore how Ruby Bindings work.
Bindings
For ERB to work, a mechanism must exist that can look up the value of a variable or obtain a method body from its name.
This mechanism is called a binding.
In Ruby, a Binding
instance is an object that encapsulates the execution context at a specific point in the code.
Each Binding instance maintains an execution environment,
sometimes referred to as the execution state.
Each Binding instance in Ruby encapsulates the execution state at the point where it was created.
This includes the current values of local variables, the value of self, method visibility,
and the context for constant and method lookup.
This execution environment can later be used to evaluate code with eval.
ERB is not the only thing that uses bindings; debuggers, the Ruby REPL, and code generators also use bindings.
The Top-Level Binding
Ruby provides a constant called TOPLEVEL_BINDING that returns the binding of the top-level scope.
Use it to access the top-level scope from anywhere in the program.
Because the top-level scope never contains local variables,
TOPLEVEL_BINDING does not contain local variables either.
self and main
When Ruby starts, it sets self to an instance of Object.
That instance is not bound to a constant or variable named main.
The string "main" is just what you see if you print self:
IRB Session
$ irb
irb(main):001> TOPLEVEL_BINDING.eval 'self'
=> main
irb(main):002> puts TOPLEVEL_BINDING.eval 'main'
(eval):1:in `': undefined local variable or method `main' for main:Object (NameError)
main
^^^^
from (irb):18:in `eval'
from (irb):18:in `'
from /home/mslinn/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0/gems/irb-1.15.2/exe/irb:9:in `'
from /home/mslinn/.rbenv/versions/3.2.2/lib/ruby/site_ruby/3.2.0/rubygems.rb:319:in `load'
from /home/mslinn/.rbenv/versions/3.2.2/lib/ruby/site_ruby/3.2.0/rubygems.rb:319:in `activate_and_load_bin_path'
from /home/mslinn/.rbenv/versions/3.2.2/bin/irb:25:in `'
If a binding is created at the top-level,
then binding’s self.to_s returns the string "main".
self is an instance of Object.
There is no separate main class or module in Ruby;
this output just indicates that the binding currently provides a particular execution context.
No standalone documentation page for main exists.
Note that IRB starts with TOPLEVEL_BINDING;
the binding tends to accumulate things as code is executed.
Shell
$ irb
irb(main):001> self
=> main irb(main):002> self.class
=> Object
There is no global variable or constant called main.
The String "main" is just the default output of to_s for that particular Object instance.
In Ruby, every Binding instance contains a self object.
A Binding object captures the execution context at a specific point in the code,
including the current value of self,
local variables, instance variables, class variables, global variables,
and all methods.
The following code accesses the self of a Binding
with Binding#receiver:
my_binding.local_variables is not equivalent to my_binding.receiver.local_variables or
my_binding.self.local_variables.
my_binding.local_variables returns an array of the names of local variables available in the context captured by the binding.
my_binding.receiver.local_variables
calls the local_variables method on the object that is self in the binding.
This usually returns the local variables in the current scope of that object, which is typically not the same as those
in the binding unless you are in the same context.
The top-level binding context is the outermost scope,
and is not encapsulated within any class or module.
The hello method shown below is defined at the top-level binding context / outermost scope.
Its method definition exists separately in the top-level binding context,
distinct from all other entries.
Ruby code
def hello
'hi'
end
p main.method(:hello) # => #<s;Method: Object#hello>
As you can see, hello is not shown as a method of main.
This is because it is an instance method of Object,
available everywhere because every object inherits from Object.
Promiscuous top-level definitions that leak from the main instance
into the Object definition are said to leak globally.
All top-level definitions leak, including methods, constants, local variables, and instance variables.
The precise mechanism varies for each type of definition, but the result is the same:
definitions propagating through Object to everything inheriting from Object.
To prevent accidental leakage, which would pollute the global namespace,
wrap your definitions within a module or class instead of defining them at the top level.
Variable and Method Resolution
Here’s how variable and method resolution works:
If a name matches a local variable in the binding, the value is returned.
Ruby next tries to resolve instance variables and method references on the current self object.
Instance variables are only accessible if the binding was created inside an object where they exist.
Methods are accessible if the object in the binding responds to them.
The binding and the object it is attached to are distinct.
This means they have separate methods and variables.
You can examine the public methods of a Binding instance like this:
Ruby code to list public methods of a binding
my_binding.public_methods
To see the methods of the object the binding is attached to,
first access binding.receiver
(this is self within the Binding instance):
Ruby code
my_binding
.receiver
.public_methods
.sort
Example ERB
The following simple example shows a template String being
interpreted according to the local binding.
Ruby code
1: require 'date'
2: require 'erb'
3: 4: name = 'Mike'
5: age = ((Date.today - Date.civil(1956, 10, 15)) / 365).to_i
6: template = '<%= name %> is <%= age %> years old.'
7: 8: erb = ERB.new template
9: puts erb.result binding
The above code contains two ERB expressions in the template on line 6.
Both ERB expressions implicitly use the binding to look up the
value of the given variable name or method name.
When I ran the above, the output was:
Output
Mike is 68 years old.
Purpose of custom_binding
It is a good practice to evaluate ERBs in a different portion of a code base than where the computation might be performed.
For example, Model-View-Controller
architectures are based on this style of programming.
However, this means that the variables and methods that the ERB needs to evaluate
are defined in different binding contexts than where they are used.
custom_binding to the rescue!
It allows you to define a custom binding either by creating new binding or mirroring an existing binding.
You can add mirrors of objects in your code to the custom binding.
The result is a completely normal binding that can be accessed from anywhere in your program.
Objects can contain variables and methods.
When mirrored in the custom binding,
variables and functions stored within objects are always in sync with the objects they mirror.
CustomBinding#render invokes ERB#render with the custom binding.
The custom_binding RSpec tests
show how to call CustomBinding#result,
which in turn invokes ERB#result with the appropriate binding object.
Here is the
GitHub’s online editor
for the custom_binding project.
Usage
Some of the RSpec tests are shown below as regular code to simplify the examples.
This code is provided in the
playground
directory of the custom_binding Git project.
playground/examples.rb defines a custom binding with specific objects mirrored from other binding contexts
that the ERB will reference.
Test data from playground/examples.rb
# Test data
class Foo
def initialize
@foo = 42
end
end
# Another class to demonstrate adding an instance to the mirrored binding
class Bar
attr_accessor :bar
def initialize(bar)
@bar = bar
end
def tell_me_a_story = 'A man was born. He lived, then died.'
end
The following method shows how Nugem uses CustomBinding with the above test data.
nugem_test method from playground/examples.rb
# Just exercise those CustomBinding methods required by Nugem:
# - CustomBinding.new
# - CustomBinding#add_object_to_binding_as
# - CustomBinding#eval
def nugem_test
puts 'nugem_test'
custom_binding = CustomBinding::CustomBinding.new binding # the current scope include the hello method
bar = Bar.new 'value of bar.bar'
custom_binding.add_object_to_binding_as('local_bar', bar)
custom_binding.add_object_to_binding_as('@test_bar', bar)
another_bar = Bar.new 'value of another_bar.bar'
custom_binding.add_object_to_binding_as('@another_test_bar', another_bar)
puts <<-END_MSG
local_bar.eval '1+2' = #{custom_binding.eval '1+2'}
local_bar.result '<%= 1+2 %>' = #{custom_binding.result '<%= 1+2 %>'}
hello = #{custom_binding.eval('hello')}
local_bar.tell_me_a_story = #{custom_binding.eval('local_bar.tell_me_a_story')}
@test_bar.tell_me_a_story = #{custom_binding.eval('@test_bar.tell_me_a_story')}
@another_test_bar.tell_me_a_story = #{custom_binding.eval('@another_test_bar.tell_me_a_story')}
local_bar.bar = #{custom_binding.eval('local_bar.bar')}
@test_bar.bar = #{custom_binding.eval('@test_bar.bar')}
@another_test_bar.bar = #{custom_binding.eval('@another_test_bar.bar')}
END_MSG
end
Output is:
Output of nugem_test method
nugem_test
hello = Hello from Mars
local_bar.tell_me_a_story = A man was born. He lived, then died.
@test_bar.tell_me_a_story = A man was born. He lived, then died.
@another_test_bar.tell_me_a_story = A man was born. He lived, then died.
local_bar.bar = value of bar.bar
@test_bar.bar = value of bar.bar
@another_test_bar.bar = value of another_bar.bar
The following method shows how to uses all CustomBinding methods,
again with the same test data.
full_test method from playground/examples.rb
# Exercise all CustomBinding methods
def full_test
puts 'full_test'
custom_binding = CustomBinding::CustomBinding.new Foo.new
# Create a new (internal) binding for the same object
mirrored_binding = custom_binding.mirror_binding
# Both original_binding and mirrored_binding are for the same object (obj).
# Any changes to @foo via either binding are reflected in the other,
# because they reference the same object’s instance variable.
# Set or update the instance variable via the original binding
custom_binding.eval '@foo = 100'
puts ' custom_binding: @foo = ' + custom_binding.eval('@foo').to_s # => 100
puts ' mirrored_binding: @foo = ' + mirrored_binding.eval('@foo').to_s # => 100
# Update the reference in the original binding via the new binding
mirrored_binding.eval '@foo = 200'
puts ' custom_binding: @foo = ' + custom_binding.eval('@foo').to_s # => 200
puts ' mirrored_binding: @foo = ' + mirrored_binding.eval('@foo').to_s # => 200
# Add a new instance of Bar to the mirrored binding
bar = Bar.new 'value of bar.bar'
custom_binding.add_object_to_binding_as('@another', bar)
puts ' custom_binding: @another.bar = ' + custom_binding.eval('@another.bar') # => 'value of bar.bar'
puts ' mirrored_binding: @another.bar = ' + mirrored_binding.eval('@another.bar') # => 'value of bar.bar'
# Change the value via the original binding
custom_binding.eval '@another.bar = "value of bar.bar changed"'
puts ' mirrored_binding: @another.bar = ' + mirrored_binding.eval('@another.bar') # => 'value of bar.bar changed'
# Ensure this still works:
puts ' custom_binding: @foo = ' + custom_binding.eval('@foo').to_s # => 200
puts ' mirrored_binding: @foo = ' + mirrored_binding.eval('@foo').to_s # => 200
end
Output is:
Output of full_test method
full_test
custom_binding: @foo = 100
mirrored_binding: @foo = 100
custom_binding: @foo = 200
mirrored_binding: @foo = 200
custom_binding: @another.bar = value of bar.bar
mirrored_binding: @another.bar = value of bar.bar
mirrored_binding: @another.bar = value of bar.bar changed
custom_binding: @foo = 200
mirrored_binding: @foo = 200
Ruby Quirks
Ruby methods defined at the top level, also known as global methods,
are associated with the Kernel module and are generally
accessible from anywhere.
However, they are conceptually tied to Object as a
private method due to encapsulation rules.
In other languages, like Java or C#,
top-level methods would be defined within a specific class or would be static,
not private methods of a general Object instance.
As an example, lets define a top-level method called hi
and see how Ruby classifies it.
The following code displays the result of every type of inquiry possible for Ruby methods.
Note that some functionality overlaps;
the methods method returns both public and protected
methods of the receiver,
while the public_methods only returns public methods.
IRB session
$ irb
irb(main):001> def hi = 'Hello from Mars'
=> :hi
irb(main):002> methods.select{ |x| x == :hi }
=> []
irb(main):003> private_methods.select{ |x| x == :hi }
=> [:hi]
irb(main):004> protected_methods.select{ |x| x == :hi }
=> []
irb(main):005> public_methods.select{ |x| x == :hi }
=> []
irb(main):006> singleton_methods.select{ |x| x == :hi }
=> []
Thus, if you define a top-level Ruby method and then do not see it defined the way you expected, you know why.
Nothing is broken, Ruby just has a few oddities.
]]>Mike SlinnRuby’s to_s and inspect Methods2025-09-04T00:00:00-04:002025-09-05T00:00:00-04:00https://www.mslinn.com/ruby/5000-to_s-inspect
The to_s and inspect methods are defined in Object and all classes inherit them.
To be precise, Object#to_s is inherited from Kernel#to_s.
Many core classes override inspect to show more detail.
Output from recursive processes can be so enormous that the system stops functioning effectively.
Normal Output Vs Debug Output
Each method has a different purpose:
inspect is for debugging.
to_s is for normal operation.
To compare with Python, to_s is like __str__ and returns a string.
In contrast, inspect is like __repr__;
for example, inspecting a class instance displays the class name, the instance’s object_id in hexadecimal,
and then the method recursively calls itself for each instance variable within the class instance.
The default output of both methods can be very different, as shown in this irb session:
Stack dumps can be problematic when working with large data structures.
For example, when debugging Jekyll plugins and a stack dump occurs,
even a powerful computer can be brought to its virtual knees for 10 minutes
or longer as the default implementation of inspect
painfully traverses the entire data structure and displays it on screen after
screen of mostly useless information.
The only way to terminate the dump is to terminate the Visual Studio Code
process or press the reset button on your computer.
When defining a custom class that has a large data structure to traverse,
be sure to define inspect in such a way that it displays a minimum of information.
Your code could respond to an environment variable that determines whether
recursive data structures should be traversed or not, for example.
This will eliminate the superfluous output when dumping stacks containing your custom classes.
Monkey Patching
If you are working with a Ruby gem that is dumping huge amounts of output as it raises exceptions,
fear not, you can monkey patch the gem quite easily.
For example, the Jekyll gem has large recursive data structures that really get in your face when the plugin you are working on raises StandardError.
The solution is to selectively override the problematic inspect method definitions in the gem with
significantly less verbose definitions.
Some of the classes that you will probably need to override are
Jekyll::Page, Jekyll::Post, and Jekyll::Document.
The following example code below demonstrates a minimal set of monkey patches for Jekyll.
With this in place, stack dumps will be a lot easier to understand at a high level.
You could tweak the code to display more information if desired.
monkey_patch_jekyll.rb
module Jekyll
class Page
def inspect
"#<Jekyll::Page path=#{path}>"
end
end
class Document
def inspect
"#<Jekyll::Document relative_path=#{relative_path}>"
end
end
class Site
def inspect
"#<Jekyll::Site source=#{source}>"
end
end
class Post
def inspect
"#<Jekyll::Post path=#{path}>"
end
end
end
😁
There are two ways of invoking the above.
Once invoked, stack dumps that reference Jekyll data structures will be dramatically shorter.
Life will be so much better!
To just affect dumps from the Jekyll project you are working on,
place monkey_patch_jekyll.rb in your project’s _plugins/ folder,
The full path from the Jekyll project root would be _plugins/monkey_patch_jekyll.rb.
To affect dumps from every Jekyll project that uses your plugin,
place monkey_patch_jekyll.rb in the lib/ directory of the plugin
and require it from any source file that is loaded.
Ruby code
require_relative 'monkey_patch_jekyll.rb'
The Joy of Aliases
The following code sets up to_s and a minimal version of inspect,
but also makes the original version of inspect available as inspect_original.
Ruby code
class MyClass
def initialize
@x = 1
@y = 'a'
end
def to_string = "x=#{@x} y=#{@y}"
# Order is important:
alias inspect_original inspect
alias inspect to_string
alias to_s to_string
end
We can exercise the above code to verify that to_s and
inspect are aliased
to the to_string method,
and the original inspect method is still available as inspect_original.
The splat operator, also known as the spread operator or spread syntax,
is a feature available in various programming languages.
A splat operator composes or decomposes various types of collections, including tuples, arrays and dictionaries.
Many programming languages have a splat operator, including CoffeScript, Julia, PHP, Python, Ruby, and Scala.
The C# params operator
and the CoffeScript ellipsis
are similar.
One of the many things that Ruby’s splat operator can do is to
destructure an array into individual arguments for a method call.
The following code example yields equivalent code to the previous system call example:
Ruby code
array = ['/bin/program', 1, 2, 3]
system *array
This can be very helpful if the arguments are strings that would require escaping if converted to a string.
Implementing an incantation that generates a correct escape sequence can be painful and is a common source of errors.
The splat operator dispenses with the need to craft a properly escaped argument string.
For example:
Ruby code
array = ['program_name', "abc'def 123"]
system *array
Let’s try this in irb:
irb
$ irb
irb(main):001> array = ["git", "status", "/path with/spaces"]
=> ["git", "status", "/path with/spaces"]
irb(main):002> system *array
On branch master
Your branch is up to date with 'origin/master'.
nothing to commit, working tree clean
=> true
You can see the Ruby splat operator in action with a Kernel.system call in my
commit Gem:
Ruby code
# @param command can be a String or an Array of String
def run(command, verbose: true, do_not_execute: false)
if command.instance_of?(Array)
puts command.join(' ') if verbose
system(*command) unless do_not_execute
else
puts command if verbose
`#{command}`.chomp unless do_not_execute
end
end
For the curious, you might be interested to know that you can directly preface an array literal with a splat operator:
Ruby code
system *['program_name', "abc'def 123"]
Related Stack Overflow Answer
This Stack Overflow answer
shows a similar approach that utilizes the splat operator in another way to invoke system.
]]>Mike SlinnVisualizing Dependencies with bundle graph2024-07-26T00:00:00-04:002024-07-26T00:00:00-04:00https://www.mslinn.com/ruby/7000-bundle-graph
You can visualize the dependencies between Ruby gems by using
the bundle graph subcommand.
This subcommand generates a PNG file of the dependencies of current Ruby project as a dependency graph.
The bundle graph subcommand is not installed by default.
Instead, it is implemented as a
Bundler plugin.
The Git project is here.
If you attempt to run bundle graph without installing the plugin,
you will get the following error:
Shell
$ bundle graph
Could not find command "graph".
Installation
Bundler plugins can either be installed globally or for specific projects.
I think the plugin is best installed globally, not per-project.
Follow these instructions for a global installation.
The documented installation instructions are incomplete.
This article provides more information.
Here is the help message:
Shell
$ bundler plugin help install
Usage:
bundler plugin install PLUGINS
Options:
[--source=URL of the RubyGems source to fetch the plugin from]
[--version=The version of the plugin to fetch]
[--git=URL of the git repo to fetch from]
[--local-git=Path of the local git repo to fetch from (deprecated)]
[--branch=The git branch to checkout]
[--ref=The git revision to check out]
[--path=Path of a local gem to directly use]
Description:
Install plugins either from the rubygems source provided (with --source option), from a git source provided with
--git, or a local path provided with --path. If no sources are provided, it uses Gem.sources
Installing the graph plugin for Bundler requires three steps.
Globally install the ruby-graphviz gem.
Shell
$ gem install ruby-graphviz
Fetching ruby-graphviz-1.2.5.gem
You need to install GraphViz (https://graphviz.org) to use this Gem.
For more information about Ruby-Graphviz :
* Doc: https://rdoc.info/github/glejeune/Ruby-Graphviz
* Sources: https://github.com/glejeune/Ruby-Graphviz
* Issues: https://github.com/glejeune/Ruby-Graphviz/issues
Successfully installed ruby-graphviz-1.2.5
Parsing documentation for ruby-graphviz-1.2.5
Installing ri documentation for ruby-graphviz-1.2.5
Done installing documentation for ruby-graphviz after 5 seconds
1 gem installed
Install the graphviz dependency.
On WSL/Ubuntu I installed it like this:
Shell
$ sudo apt install graphviz
To install the Bundler plugin globally, first move to your home directory, then type the following.
If you instead type this incantation from a Ruby project,
the plugin will only be installed for that project:
NuGem creates a scaffold project for a new gem in a new Git repository.
After you add your special code to the gem scaffold,
the project is ready to be released to a public or private gem server.
Features
This gem generates a new working Visual Studio Code project with the following features:
Compatible with rbenv.
Gemfile and .gemspec files set up.
Generates a README with badges.
Visual Studio Code project is set up with current Ruby extensions.
Rubocop configured.
Shellcheck configured.
Markdown lint configured.
Launch configurations set up for testing.
Can automatically create a public or private Git repository on GitHub for your new gem.
Creates a test infrastructure based on rspec.
Your gem can be publicly released to rubygems.org.
Optionally create the gem as:
A plain old gem.
A Jekyll plugin (tag or block tag).
The following features are still in development, so they probably do not work yet:
Automatically creates Git repositories on BitBucket or Geminabox.
Creates a test infrastructure based on minitest and minitest-reporters.
Your gem can be privately released to a Geminabox gem server.
If you are using rbenv to manage Ruby instances, type:
Shell
$ rbenv rehash
To update the program:
Shell
$ gem update nugem
Subcommands and Options
NuGem has 4 subcommands gem, jekyll, help and rails.
Currently, only gem, jekyll and help have been properly tested.
help Subcommand
The following lists the available subcommands:
Shell
$ nugem help
The following provides detailed help for the specified subcommand:
Shell
$ nugem help SUBCOMMAND
Common Options
The gem, jekyll and rails subcommands have common options.
The default option values assume that:
You do not want an executable for your gem scaffold
The gem project will be hosted on a public GitHub Git repository
The gem will be released to rubygems.org
Common options for the gem, jekyll and rails subcommands are:
--executable
add an executable based on Thor.
--host
specifies the Git host; possible values are bitbucket,
github and geminabox.
--out_dir
specifies the directory to write the generated gem to.
The default is generated/.
--private
the remote repository is made private,
and on release the gem will be pushed to a private Geminabox server.
--quiet
reduces verbosity.
--no-todos
do not generate TODO: strings in generated code.
Common Behavior
The gem, jekyll and rails subcommands have common behavior.
Gem scaffolds are created within the generated/ directory of the current directory by default.
If your user name is not already stored in your Git global config,
you will be asked for your GitHub or BitBucket user name.
You will also be asked to enter your GitHub or BitBucket password when the remote repository is created for you.
After you create the gem, edit the gemspec and change the summary and the description.
Then commit the changes to Git and invoke rake release,
and your gem will be published.
gem Subcommand
Shell
$ nugem gem NAME [COMMON_OPTIONS] [--test-framework=minitest|rspec]
NAME is the name of the gem to be generated.
The default test framework for the gem subcommand is rspec,
but you can specify minitest instead like this:
(Warning: this has not been properly tested)
Shell
$ nugem gem my_gem --test-framework=minitest
jekyll Subcommand
The jekyll subcommand extends the gem subcommand and creates a new Jekyll plugin with the given NAME:
Shell
$ nugem jekyll NAME [OPTIONS]
NAME is the name of the Jekyll plugin gem to be generated.
In addition to the common options, the jekyll-specific OPTIONS are:
--block, --blockn, --filter, --hooks, --tag, and --tagn.
(Warning: only ‑‑block and ‑‑tag been properly tested.)
Each of these options causes nugem to prompt the user for additional input.
The test framework for jekyll plugins is rspec.
All the above options can be specified more than once, except the ‑‑hooks option.
For example:
The above creates a Jekyll plugin called test_tags,
which defines Jekyll tags called my_tag1 and my_tag2.
You might use these tags in an HTML document like this:
If you have not installed the
Snippets extension,
Visual Studio Code will suggest that you do so the first time you open this project with Visual Studio Code.
You can also review the list of suggested extensions of with the CTRL-PExtensions: Show Recommended Extensions command.
Snippets
The predefined snippets for nugem are defined in
.vscode/nugem.json.code-snippets.
These snippets are focused on maintaining nugem itself.
File Associations
.vscode/settings.json defines file associations for various flavors of Thor templates in the
"files.associations" section.
You can disable them by commenting some or all of those definitions.
Generated Projects
Plugins
Similarly, for each gem project generated by nugem, Visual Studio Code will suggest
the user install missing extensions the first time those projects are opened.
Snippets
The predefined snippets for gem projects generated by nugem are defined in
their .vscode/gem.json.code-snippets file.
These snippets are focused on writing Jekyll plugins.
Development
After checking out the repository, run bin/setup to install dependencies.
Then, run rake test to run the tests.
You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run:
Shell
$ exec rake install
To release a new version, run:
Shell
$ exec rake release
The above will create a Git tag for the version, push Git commits and tags,
and push the .gem file to rubygems.org.
My Jekyll plugins packaged as Ruby gems are shown on their own page.
The above gems are unrelated to Jekyll.
]]>Mike SlinnParsing Command Line Arguments with OptionParser2023-10-03T00:00:00-04:002025-09-25T00:00:00-04:00https://www.mslinn.com/ruby/6600-option_parser
The Ruby language has many libraries for parsing command-line arguments.
This article discusses OptionParser, which
is one of the most popular Ruby libraries for parsing arguments.
OptionParser is popular because it is both powerful and easy to use,
and it is part of the Ruby runtime library.
The detailed Ruby documentation for OptionParser is
here.
I am not going to restate the documentation, since
many articles have been written about OptionParser.
Instead, this section will just discuss important details that are not usually discussed
or are assumed by many writers to be obvious,
even though the omitted details might not be obvious to many readers.
This Article Teaches Two Main Concepts
OptionParser returns parsed values in a hash.
OptionParser has an internal accumulator that
composes the subject of each OptionParser#on method call.
Some idiomatic Ruby code must be written to describe the desired parsing.
Although these idioms become familiar over time,
the first few times you are exposed to them, they will seem awkward.
This article discusses the idiomatic Ruby when it arises.
Denoting Keyword Options
Options can merely be keywords; for example, an option such as -f (--force)
might be used to specify that any previous output from a program should be overwritten.
Keywords are actually implemented as a key/value pair with value true.
If the program containing OptionParser code is launched with the -f option,
the above code fragment would store {force: true} in the options hash.
The name force is used because that is the long-form name of the option.
The parser.on statement causes the parser instance to retain the instruction for scanning for
the -f/--force option, should it be encountered.
The OptionParser#order! method accepts the command-line arguments from
the operating system via ARGV, uses the parsing instruction that was set up
via the on method call, and stores the results in the options hash.
Name/Value Options
Options with arbitrary values can also be defined, and they are also stored as key/value pairs.
For example, an option named verbose might require a string value such as low,
medium or high.
In the following minimal example, the default value for verbose is 'low'.
The presence of a placeholder,
in this example VERBOSE,
indicates that the parsed value should
be stored in the result hash with a key named after the long option name.
The placeholder value is not actually relevant, and its length is also unimportant;
the Ruby documentation calls placeholders dummy tokens.
As before, the name verbose is used for the name of the resulting entry in the resulting hash
because the long form of the option is --verbose.
The value placeholder is shown in yellow.
You could also write the above as follows, but there is no reason to do so because specifying the value placeholder twice just represents more typing:
The documentation does not mention a crucial limitation of how OptionParser
parses command lines:
Option parsing stops on the first positional parameter.
A positional parameter is a token that does not begin with a dash and is not an option value.
This means, for example, that the first two options in the following
command line are parsed, but the remaining options are not,
unless the command line is manipulated:
Subcommands that follow the above syntax are fully discussed in the OptionParser documentation.
Later in this article I discuss why the above syntax is unnecessarily awkward,
and in NuGem I discuss an alternative,
NestedOptionParser,
based on a novel usage of OptionParser
that is more user-friendly.
Sod
The F/OSS library called sod
enhances OptionParser.
Although sod can be used as an OptionParser wrapper that provides enhanced capability,
you can also just use selected features of sod while continuing to use OptionParser as usual.
That is the approach taken in this article.
One sod feature that I especially like is the
extra data types
that it supports for parsing arguments:
Custom
parsers are possible that return arbitrary data types.
Installation
OptionParser
is part of the standard Ruby runtime library,
so once Ruby itself is installed, there are no mandatory additional steps for installation.
Gemfile
If you are building an application,
add the following lines to your application’s Gemfile:
Gemfile
gem 'optparse'
gem 'sod' # If you want extra datatypes
And then execute:
Shell
$ bundle
Gem
If you are building a gem,
add the following line to your gem’s .gemspec:
your_gem.gemspec
spec.add_dependency 'optparse'
spec.add_dependency 'sod' # If you want extra datatypes
And then execute:
Shell
$ bundle
Usage
My stabilize_video
program is an example of how I like to use OptionParser.
Below are portions of three Ruby source files:
option.rb parses the options and generates the help text.
stabilize_video.rb parses the positional parameters.
stablize.rb receives the positional parameters and options.
The following import is required before invoking creating an OptionParser instance:
Ruby code fragment
require 'optparse'
require 'sod' # If you want to use sod
require 'sod/types/pathname' # If you want to parse Pathnames
Parsing Options
Let’s look at an initial version of the parse_options method,
which uses OptionParser to parse the optional arguments.
Later in this article
I show a more flexible implementation that allows the parsing code to be testable.
Portion of options.rb
def parse_options
options = { shake: 5, loglevel: 'warning' }
OptionParser.new do |parser|
parser.program_name = File.basename __FILE__
@parser = parser
parser.on('-f', '--overwrite', 'Overwrite output file if present')
parser.on('-l', '--loglevel LOGLEVEL', Integer, "Logging level (#{VERBOSITY.join ', '})")
parser.on('-s', '--shake SHAKE', Integer, 'Shakiness (1..10)')
parser.on('-v', '--verbose VERBOSE', 'Verbosity')
parser.on('-z', '--zoom ZOOM', Integer, 'Zoom percentage')
parser.on_tail('-h', '--help', 'Show this message') do
help
end
end.order!(into: options)
help "Invalid verbosity value (#{options[:verbose]}), must be one of one of: #{VERBOSITY.join ', '}." if options[:verbose] && !options[:verbose] in VERBOSITY
help "Invalid shake value (#{options[:shake]})." if options[:shake].negative? || options[:shake] > 10
options
end
The default options are set in the highlighted hash.
Default values are set for the :shake and :loglevel keys.
When parser.on is passed the name of an option value in UPPER CASE,
it creates an entry in the options hash with that name, in lower case.
The above code shows the following examples:
LOGLEVEL provides a means for the user to specify a value to replace the default value of the
loglevel entry in the options hash, which was initialized with the string value 'warning'.
SHAKE provides a means for the user to specify a to replacement for the default value of the
shake entry in the options hash, which was initialized with the integer value 5.
VERBOSE provides a means for the user to specify a string value for a new entry in the
options hash with the key verbose.
ZOOM provides a means for the user to specify a string value for a new entry in the
options hash with the key zoom.
OptionParser.order!
has the side effect that option keywords and key/value pairs
that match parser.on statements are removed from ARGV.
Ending the end.order! statement with (into: options)
causes the parsed option key/value pairs to be added or updated in the hash called options.
The parsed options are returned.
Parsing Positional Parameters
Let’s see how stabilize_video.rb parses positional parameters:
stabilize_video.rb
require 'colorator'
require_relative 'stabilize_video/version'
require_relative 'options'
# Require all Ruby files in 'lib/', except this file
Dir[File.join(__dir__, '*.rb')].each do |file|
require file unless file.end_with?('/stabilize_video.rb')
end
def main
options = parse_options
help 'Video file name must be provided.' if ARGV.empty?
help "Too many parameters specified.\n#{ARGV}" if ARGV.length > 1
video_in = ARGV[0]
video_out = "#{File.dirname video_in}/stabilized_#{File.basename video_in}"
StablizeVideo.new(video_in, video_out, **options).stabilize
end
main
Here are some notes to help you understand the above code:
Usage of colorator or
rainbow
to output colored strings helps readability but is not required.
Because OptionParser removes each argument from ARGV that it recognizes,
when it finishes, all that should be left on the command line are the positional parameters.
The main method calls parse_options,
which, as we know calls OptionParser,
and then ensure that a mandatory filename parameter is provided.
parse_options returns a hash of name/value pairs,
which can optionally be passed when doubly dereferenced with two asterisks (**options),
often referred to as the double splat operator.
This is done in the highlighted code above when creating a new StablizeVideo instance.
Warning: AI Misinformation
Warning: AI-generated help from Google provides incorrect information about the double asterisk syntax.
It says:
The double asterisks cause each key/value pair in the options hash to be passed
as a named argument to the StablizeVideo.initialize method.
The above is incorrect.
Here is some code that shows exactly what happens:
deref_fun.rb
def fun(**options)
puts "fun options: #{options}"
puts "fun options[:dry_run]: #{options[:dry_run]}"
@dry_run = options.key?(:dry_run) ? options[:dry_run] : false
puts "fun dry_run: #{dry_run}" # This line will raise an error because dry_run is not defined
rescue StandardError => e
puts "Error in fun: #{e.message}"
end
my_options = { dry_run: true }
fun(**my_options)
puts "@dry_run: #{@dry_run}"
Here is the output of the above code:
Shell
$ ruby playground/deref_fun.rb
fun options: {:dry_run=>true}
fun options[:dry_run]: true
Error in fun: undefined local variable or method `dry_run' for main:Object
@dry_run: true
Passing Options
In the following code, the optional values returned by parse_options are provided to the StablizeVideo.initialize method.
Once again, double asterisks are used.
The value of the -l / --loglevel option is obtained from options[:loglevel].
The value of the -s / --shake option is obtained from options[:shake].
If the user specified the -f (--overwrite) option, that is detected by options.key?(:overwrite).
Hand-written Help Text
I find that using the automatically generated help text results in a more complex program for little gain,
because there are so many moving parts to keep track of.
Explicitly writing the help method is a more maintainable way of showing the user what they need to know.
The help method below generates the help text, which might be preceded by an error message.
Portion of options.rb
def help(msg = nil)
printf "Error: #{msg}\n\n".yellow unless msg.nil?
msg = <<~END_HELP
stabilize: Stabilizes a video using the FFmpeg vidstabdetect and vidstabtransform filters.
Syntax: stabilize [Options] PATH_TO_VIDEO
Options:
-f Overwrite output file if present
-h Show this help message
-s Shakiness compensation 1..10 (default 5)
-v Verbosity; one of: #{VERBOSITY.join ', '}
-z Zoom percentage (computed if not specified)
See:
https://www.ffmpeg.org/ffmpeg-filters.html#vidstabdetect-1
https://www.ffmpeg.org/ffmpeg-filters.html#toc-vidstabtransform-1
END_HELP
printf msg.cyan
exit 1
end
A Ruby squiggly heredoc
is used to store a multiline string as the help text.
Running the Program
Now let's run the above program and view the generated help text:
Shell
$ stabilize -h
stabilize -h
stabilize: Stabilizes a video using the FFmpeg vidstabdetect and vidstabtransform filters.
Syntax: stabilize [Options] PATH_TO_VIDEO
Options:
-f Overwrite output file if present
-h Show this help message
-s Shakiness compensation 1..10 (default 5)
-v Verbosity; one of: trace, debug, verbose, info, warning, error, fatal, panic, quiet
-z Zoom percentage (computed if not specified)
See:
https://www.ffmpeg.org/ffmpeg-filters.html#vidstabdetect-1
https://www.ffmpeg.org/ffmpeg-filters.html#toc-vidstabtransform-1
Testing Argument Parsing
As we have seen, Ruby passes an argument to the
OptionParser
block body.
As a reminder, the following code shows the block body and the argument, called parser:
Ruby code
OptionParser.new do |parser|
# OptionParser block body
end
Designing Parsing Code for Testability
The argument provided to the OptionParser block body, called parser,
is an OptionParser instance.
There are two ways to supply a value for ARGV other than the default value that Ruby provides.
The OptionParser provides methods called parse,
parse!, option and option!.
All of these methods accept an optional argv parameter.
The first optional argument of each of these methods is the array of arguments to be parsed.
The value of this argument defaults to ARGV, which
the operating system passes to your Ruby program when it starts.
The following Ruby code defines a method called parse_options that demonstrates a technique for
command-line option parsing.
Key features of this technique are:
Default values can be established in a modular fashion
Option parsing code is more modular, which makes it easier to understand
OptionParser functionality is not affected
System-provided values can be overridden for testing
Nothing extra required for full RSpec support
I intend to use this latest iteration of the technique in all my scripts and CLI tools.
Ruby code
require 'optparse'
def parse_options(default_options, argv: ARGV)
options = default_options
OptionParser.new do |parser|
# Remaining parameter parsing code goes here
# For example:
parser.on '-v', '--verbose', FalseClass
end.order! argv, into: options
options
end
The parse_options method accepts one or two arguments:
default_options, which is a hash containing default values for options,
and the optional argv argument,
which allows you to specify a custom array of arguments to parse instead
of the default system ARGV provided by Ruby.
The parse_options method body initializes a new automatic variable called options
from the default_options parameter.
A new OptionParser instance is then created called parser.
Its scope is only within the OptionParser body.
The odd syntax of this method body actually defines the parsing of the arguments,
which stores the results in the options hash.
If the parameter list does not specify an option, the default value remains intact;
otherwise, the default value is overwritten.
The highlighted line within the OptionParser body is important:
this code tells the parser to use the optional argv array, if provided,
as the source of command-line arguments.
This technique is useful for testing and for programmatically specifying arguments.
Define the options that your script accepts within the remainder of the parser block.
The example recognizes a -v or --verbose flag.
After instantiating the OptionParser instance called parser,
the end closes the OptionParser constructor block, which finalizes the parsing process.
The order! method is then called with an option called into:,
followed by the name of the variable that will receive the hash resulting from the parsing operation that just completed.
Finally, the parse_options method returns the populated options hash.
It is up to the caller to handle any remaining arguments in ARGV.
Testing the Parsing Code With irb
The following example invocation demonstrates how to call parse_options with a set of default options
and a custom argument String array, simulating command-line input.
The demonstrated approach shows how to make option parsing flexible and testable.
You can easily override the arguments without going through the
pain of providing actual command lines to running instances of your code,
or getting frustrated with Visual Studio Code’s inability to accept ARGV tokens with embedded spaces.
The following example shows how to use the parse_options method above.
You might write code like this for unit tests of CLI user invocation.
This example simulates a CLI being called with two positional parameters (param1 and param2),
and without an optional parameter (-v / --verbose) being provided.
You can write RSpec unit tests that incorporate similar code.
This allows you to test CLI argument parsing easily.
Testing with RSpec
The following code shows an RSpec test that parses an argument as a Ruby Time instance.
Ruby code
require 'optparse'
require 'optparse/time'
require_relative 'spec_helper'
class NestedOptionParserTest
RSpec.describe OptionParser do
option_parser = described_class.new do |parser|
parser.on('-t TIME', '--time=TIME', Time)
parser.on('-x', '--xray')
end
it 'initializes an OptionParser' do
options = { time: '2020-02-12T00:00:00Z' } # Default value of all options
option_parser.order! %w[-x -t 2025-07-01T12:00:00Z], into: options
expect(options).to eq({ xray: true, time: Time.parse('2025-07-01T12:00:00Z') })
end
end
end
Advanced Usage
In Ruby, procs are closures that capture variables from their surrounding context.
If you are familiar with partial functions, they can be defined as procs
so they can be passed around and invoked later.
This capability can be useful when defining OptionParser command-line option parsing.
Ruby procs can be provided to OptionParser,
and command-line parsing would occur within them.
However, it may not be obvious how to obtain the value of parsed options from a proc,
especially if the proc is defined in a different binding context than one containing the
accumulator (the options hash).
To provide argument value outside the block, you can:
Close over a variable (simple, but mixes parsing code with business logic)
Pass in a container
Encapsulate the logic in an object
Let’s look at each of these techniques in turn.
Close Over A Variable
Using a proc to define the parsing for an option is comparatively simple to set up.
Because only one lexical scope is involved, the accumulator (the options hash) must be defined
in the same lexical scope as the parser procs.
Constructing the proc in a method allows the proc to be reused because the lexical scope in force when the proc is
constructed includes the method arguments.
With this technique, the proc fills in the provided options hash
without any lexical binding trickery.
Because the options hash is passed by value,
the caller can see the changes to the value that the proc might make.
Ruby code
require 'optparse'
def outdir_proc(options)
proc do |parser|
parser.on('-o', '--out_dir=OUT_DIR') do |value|
options[:out_dir] = value
end
end
end
options = {}
parser = OptionParser.new
outdir_proc(options).call(parser)
parser.parse!(['-o', '/tmp/blah']) # Simulate ARGV
puts options # displays {:out_dir=>"/tmp/blah"}
Multiple Procs
This approach allows for modular and reusable option definitions
that can be easily combined in different ways.
A separate proc is defined for each option or group of related options.
Each proc adds parsing for one or more options to the parser;
parsed values are stored in the options hash.
Default values for options can be set in the options hash
before calling the procs.
Procs define how options are parsed and stored in the options hash.
Procs are independent and cannot assume that any other proc has been called,
so they must not depend on any other option values
being present in the options hash.
Procs can be called in any order when accumulating
option values from the command line arguments
into the options hash.
Idempotency is important: calling a proc multiple times should not cause errors
or unexpected behavior.
After all procs have been called, parser.parse! should be called
to actually parse the command line arguments and populate the options hash
Here’s a multi-option example using the Rails/Thor-style central options
hash where multiple procs contribute their options independently but all populate the same hash.
Note that each proc only references values passed to it,
and default values are defined separately from the parsing code.
optionparser_many_procs.rb
require 'optparse'
# Define default values and accumulate option values into this Hash.
# The procs that follow are invoked such that option values
# accumulate into this variable.
options = {
dry_run: false,
out_dir: Dir.home,
verbose: false,
}
# Proc for handling output directory
out_dir_proc = proc do |parser, opts|
parser.on('-o', '--out_dir=OUT_DIR', 'Output directory') do |value|
opts[:out_dir] = value
end
end
# Proc for handling verbosity
verbose_proc = proc do |parser, opts|
parser.on('-v', '--[no-]verbose', 'Run verbosely') do |value|
opts[:verbose] = value
end
end
# Proc for handling dry-run mode
dry_run_proc = proc do |parser, opts|
parser.on('-n', '--dry-run', 'Do everything except execute') do |value|
opts[:dry_run] = value
end
end
# Build parser and apply all option procs
parser = OptionParser.new
[out_dir_proc, verbose_proc, dry_run_proc].each do |p|
p.call(parser, options)
end
parser.parse!(['-o', '/tmp/test', '-v', 'very']) # Simulated command line arguments
puts "RubyOptions hash: #{options.sort.to_h}"
# RubyOptions hash: {:dry_run=> false, :out_dir=>"/tmp/test", :verbose=>true}
Encapsulate in a Class
This version encapsulates the previous version in a class.
$nugem/playground/optionparser_class.rb
require 'optparse'
class MyOptionParser
attr_reader :parser, :options
def initialize
@options = {}
@parser = OptionParser.new
[dry_run_proc, out_dir_proc, verbose_proc].each do |p| # Build parser from option procs
p.call(@parser, @options)
end
end
# Proc for handling dry-run mode
def dry_run_proc
proc do |parser, opts|
parser.on('-n', '--dry-run', 'Do everything except execute') do |value|
opts[:dry_run] = value
end
end
end
# Build parser and apply all option procs
def out_dir_proc
proc do |parser, opts|
parser.on('-o', '--out_dir=OUT_DIR') do |value|
opts[:out_dir] = value
end
end
end
# Proc for handling verbosity
def verbose_proc
proc do |parser, opts|
parser.on('-v', '--[no-]verbose', 'Run verbosely') do |value|
opts[:verbose] = value
end
end
end
def parse(argv = ARGV)
@parser.parse! argv
end
end
my_option_parser = MyOptionParser.new
argv = ['-o', '/tmp/blah'] # Simulate ARGV
puts "Parsing #{argv}"
unparsed_options = my_option_parser.parse argv
puts "Parsed options: #{my_option_parser.options}"
puts "Unparsed options: #{unparsed_options}"
argv = ['-o', '/tmp/blah', 'x'] # Simulate ARGV
puts "\nParsing #{argv}"
unparsed_options = my_option_parser.parse argv
puts "Parsed options: #{my_option_parser.options}"
puts "Unparsed options: #{unparsed_options}"
Inside the parser.on block,
the value of OUT_DIR is given as the block argument (e.g., |out_dir|).
Note:
options is a hash that is passed around.
Each option-defining proc knows nothing about where the hash lives;
it just fills in the value for the provided key.
After parsing, user-supplied options are stored in one place.
Composing Subcommand Parsers With a Common Option Parser
This approach can be used to compose subcommand option parsers as well.
For example, instead of defining a proc per option,
you might define a proc for all options of each subcommand.
Each subcommand proc would be invoked conditionally based on the first positional argument.
The procs would accumulate the option values they parse to the central hash.
Here is an example of how that might look:
optionparser_proc_fun.rb
1: require 'optparse'
2: 3: argv = ['init', '-v', '-t', 'blah']
4: subcommand = argv.shift
5: if subcommand.nil?
6: puts 'Error: No subcommand provided. Subcommands are: init and deploy'
7: exit 1
8: end
9: options = { verbose: false } # Default value of options
10: 11: common_proc = proc do |parser, opts|
12: parser.on('-v', '--[no-]verbose', 'Run verbosely') do |value|
13: opts[:verbose] = value
14: end
15: end
16: 17: subcommand_procs = {
18: 'init' => proc do |parser, opts|
19: parser.on('-t', '--template=TEMPLATE', 'Template to use') do |value|
20: opts[:template] = value
21: end
22: end,
23: 'deploy' => proc do |parser, opts|
24: parser.on('-e', '--env=ENV', 'Environment to deploy to') do |value|
25: opts[:env] = value
26: end
27: end,
28: }
29: 30: parser = OptionParser.new
31: common_proc.call(parser, options)
32: 33: # Subcommand-specific options
34: if subcommand_procs.key?(subcommand)
35: subcommand_procs[subcommand].call(parser, options)
36: else
37: puts "Unknown subcommand: #{subcommand}"
38: exit 1
39: end
40: 41: parser.parse(argv) # Example args; replace with ARGV in real use
42: puts "Subcommand '#{subcommand}' has options #{options.inspect}"
The above is simple and clear.
The following is more verbose and less clear,
but it accomplishes the same purpose:
Ruby code
_option_parser = OptionParser.new do |parser|
common_proc.call(parser, options)
end
There are a lot of ways to compose OptionParser parsing.
Highline
Highline is a gem that is often found in CLIs that are built with
OptionParser.
It now enjoys its very own article:
Highline Gem and Workalike.
Subcommand Options
The documentation shows how to set up your code so subcommands can share common options,
and also have options specific to certain subcommands.
This is how most information on the interwebs says subcommand options should be organized:
Most commonly recommended form of subcommand options
For example, the nugem
CLI has two subcommands: ruby and jekyll.
The --loglevel, --executable and --help options are available for all subcommands.
The ruby subcommand has no special options.
The --tags and --hooks options are only for the jekyll subcommand.
The version of nugem described here is still under development.
I am working on a
major new release
for nugem at present.
👏👏
This new release has taken 18 months;
I decided to create (and test) lots of support gems for the new release.
Now (2025-09-25) I about to start working on the last one.
The new version is looking pretty nice.
I am tempted to release the next generation Nugem soon.
Using the documentated way of implementing subcommand option parsing, the following syntaxes would be allowed:
Allowed syntaxes
nugem --help
nugem ruby
nugem --loglevel info ruby
nugem --executable ruby
nugem --loglevel info --executable ruby
nugem jekyll
nugem jekyll --tags
nugem jekyll --tags --hooks
nugem --loglevel info jekyll --tags --hooks
nugem --loglevel info --executable jekyll --tags --hooks
... and others ...
I do not like this syntax.
The most commonly recommended approach requires that common options must precede the subcommand,
and subcommand options must follow the subcommand.
The following desirable syntaxes would therefore not be allowed:
Here is a rough outline of how to implement this type of syntax:
Ruby code
global = OptionParser.new do |opts|
# on statements for flags common to all commands go here
end
subcommands = {
'foo' => OptionParser.new do |opts|
# on statements for the foo command go here
end
'baz' => OptionParser.new do |opts|
# on statements for the baz command go here
end
}
global.order!
subcommands[ARGV.shift].order!
The last two lines of the above code show how global.order!
parses all options in the first element of ARGV until the first token
that does not start with a dash and removes them from ARGV.
The next line, subcommands[ARGV.shift].order!,
parses and removes all options after the subcommand.
I prefer to order options before positional parameters
and to be able to specify options in any order,
anywhere on the command line.
However, this makes parsing multiple subcommands difficult.
A More Practical Approach
A more practical approach would be to mandate that the first parameter must be the subcommand name,
followed by options and any other positional parameters.
OptionParseron statements typically match specific flags or options.
However, to match all options, regardless of their name or format,
write the on statement as a custom order block:
]]>Mike SlinnRubocop Settings for Visual Studio Code2023-08-28T00:00:00-04:002023-08-28T00:00:00-04:00https://www.mslinn.com/ruby/5100-rubocop-vscode
Rubocop Visual Studio Plugin
RuboCop
is a Ruby code style checker (linter) and formatter based on the community-driven Ruby Style Guide.
There is a Rubocop Visual Studio Code plugin that works well.
Rubocop Project Configuration
Copying the following lines into .vscode/settings.json makes Rubocop work in Visual Studio Code.
The following is the Rubocop configuration file (.rubocop.yml) that I use for this Jekyll website.
It should be located within the top-level directory of a Ruby or Jekyll project.
I, Mike Slinn, have been working with Ruby for a long time now.
Back in 2005, I was the product marketing manager at CodeGear
(the company was formerly known as Borland) for their
3rd Rail IDE.
3rd Rail supported Ruby and Ruby on Rails at launch.
In 2006, I co-chaired the Silicon Valley Ruby Conference on behalf of the SD Forum in Silicon Valley.
As you can see, I have the t-shirt.
I was the sole chairman of the 2007 Silicon Valley Ruby Conference.
Several court cases have come my way over the years
in my capacity as a software expert witness.
The court cases featured questions about IP misappropriation for Ruby on Rails programs.
You can read about my experience as a software expert
if that interests you.
I currently enjoy writing Jekyll plugins in Ruby for this website and others,
as well as Ruby utilities.
]]>Mike SlinnGraceful Crash Exit From Ruby2023-08-11T00:00:00-04:002023-08-11T00:00:00-04:00https://www.mslinn.com/ruby/2200-crash-exit
Ever want to stop your Ruby program without generating a stack trace?
It is simple enough to do if you control the execution environment,
but if your program is loaded by another program, then the loading program can trap your attempts to exit.
Jekyll traps exceptions thrown by its plugins.
If you attempt to call abort or
exit,
those calls will work,
but there is nothing you can do to prevent a long stack trace from being issued.
This is not a pleasant experience for users.
Process.kill('KILL', Process.pid) # Like kill -9 in bash
# or:
Process.kill('SEGV', Process.pid) # Like kill -11 in bash
Unfortunately, not only does this generate a stack trace, but it also dumps lots of other information.
This is worse than just calling abort.
Kernel.exec
The only way I found that worked was to terminate the process by loading another process
using Kernel:exec.
The following method prints an error message in red
using colorator,
then replaces the Jekyll process with the bash command, echo ''.
Shell
require 'colorator'
# If a Jekyll plugin needs to crash exit, and stop Jekyll, call this method.
# It does not generate a stack trace.
# This method does not return because the process is abruptly terminated.
#
# @param error StandardError or a subclass of StandardError is required
#
# Do not raise the error before calling this method, just create it via 'new', like this:
# exit_without_stack_trace StandardError.new('This is my error message')
#
# If you want to call this method from a handler method, the default index for the backtrace array must be specified.
# The default backtrace index is 1, which means the calling method.
# To specify the calling method's caller, pass in 2, like this:
# exit_without_stack_trace StandardError.new('This is my error message'), 2
def exit_without_stack_trace(error, caller_index = 1)
raise error
rescue StandardError => e
file, line_number, caller = e.backtrace[caller_index].split(':')
caller = caller.tr('`', "'")
warn "#{self.class} died with a '#{error.message}' #{caller} on line #{line_number} of #{file}".red
exec "echo ''"
end
