simple-cli-options

A small Ruby library for parsing command-line flags (short and long options with values). The way you define flags (short/long, description, validation, conversion) is inspired by Cobra. Define options, then parse ARGV and read values by name.

Note: This project is in beta. APIs may change in future releases.

After building the gem (gem build simple-cli-options.gemspec in the repo), install and require:

gem install simple-cli-options-0.1.3.gem

require 'simple-cli-options'
# Option and Options are now available

Use the library as plain Ruby files. No gem packaging or Gemfile required.

1. Clone or download the repo, or copy the lib/ folder (containing option.rb and options.rb) into your project.
2. Install the runtime dependency (needed for type hints):

   gem install sorbet-runtime

3. Require the files from your script (adjust paths if needed):

   require_relative 'lib/option'
   require_relative 'lib/options'

   If you keep the library in a subdirectory (e.g. vendor/simple-options/):

   require_relative 'vendor/simple-options/lib/option'
   require_relative 'vendor/simple-options/lib/options'

A stable gem may be published to RubyGems.org later.

If you use a Gemfile, add the dependency and require as above:

# Gemfile
gem 'sorbet-runtime'

require_relative 'lib/options'
require_relative 'lib/option'

opts = Options.new(description: 'My CLI')
opts.add Option.new(:name, short: '-n', long: '--name', desc: 'Your name', required: true)
opts.add Option.new(:count, short: '-c', long: '--count', desc: 'Repeat count', required: false)
       .convert(&:to_i)

opts.parse!
puts "Hello, #{opts.get(:name)}!" * (opts.get(:count) || 1)

Running with ruby app.rb -n Alice -c 3 prints Hello, Alice! three times. -h or --help prints usage and exits.

Represents a single flag: short form (e.g. -l), long form (e.g. --length), description, and optional validation/conversion.

Example

opt = Option.new(:port, short: '-p', long: '--port', desc: 'Port number')
             .validate { |v| (1..65535).cover?(v.to_i) ? nil : 'Port must be between 1 and 65535' }
             .convert(&:to_i)

opt.process('8080')  # => 8080
opt.process('99999') # => raises ArgumentError, "Port must be between 1 and 65535 for -p or --port option"

Collects options, parses an argument array, and provides access to parsed values.

Behavior

• Each option expects the next argument as its value (e.g. --length 10).
• Help is built from the options you add; -h / --help are handled automatically.
• Validators return nil on success or an error message string on failure; failed validation raises ArgumentError with a message like "Please input positive number for -l or --length option". parse! catches it, prints Error: <message> to stderr, and exits 1.

opts = Options.new(description: 'Greeter')
opts.add Option.new(:name, short: '-n', long: '--name', desc: 'Your name', required: true)
opts.add Option.new(:times, short: '-t', long: '--times', desc: 'Repeat N times').convert(&:to_i)
opts.parse!
name = opts.get(:name)       # required; parse! would have exited if missing
times = opts.get(:times) || 1

Option.new(:size, short: '-s', long: '--size', desc: 'Size (s/m/l)',
           validate: ->(v) { %w[s m l].include?(v) ? nil : 'Size must be one of s/m/l' })
      .convert(&:upcase)

Option.new(:verbose, short: '', long: '--verbose', desc: 'Verbose output')
Option.new(:x, short: '-x', long: '', desc: 'Enable X')

Run an example (from project root):

ruby examples/paint_calculator.rb --length 10 --width 5
ruby examples/greet.rb --name World --count 2

Install dependencies, then run RSpec from the project root:

bundle install
bundle exec rspec spec/

test_helper.rb loads RSpec and the library (option.rb, options.rb), so your specs can use Option and Options without requiring them yourself.

• Specs under spec/: use spec_helper, which already requires test_helper:

  # spec/my_feature_spec.rb
  require_relative 'spec_helper'
  
  RSpec.describe Option do
    it 'does something' do
      opt = Option.new(:x, short: '-x', long: '--x', desc: 'X')
      expect(opt.process('value')).to eq 'value'
    end
  end

• Specs elsewhere (e.g. in your app): require test_helper by path so the library and RSpec are loaded:

  require_relative '/path/to/simple-options/test_helper'
  # Now Option, Options are available and RSpec is configured

Then run your spec with bundle exec rspec path/to/your_spec.rb.

RuboCop (and rubocop-performance, rubocop-rspec) are in the Gemfile. Run with bundle exec rubocop.

MIT (see LICENSE).