Ordú

Another command-line interface library for Ruby. This one is based entirely on the venerable and built-in OptionParser class.

Installation

Add this line to your application's Gemfile:

gem 'ordu'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ordu

Usage

Write a subclass of Ordu. Then use the option, command and action to define behaviour. In the background, a set of command-line parsers will be built up. Now, calling the parse! method on the class itself, and passing in an array of arguments will give you your CLI.

Here's a simple example:

#!/usr/bin/env ruby
require 'ordu'
class Sneezer < Ordu
  # Define options much as you would with Ruby's built-in OptionParser. The
  # difference is that blocks are evaluated within the Ordu instance's
  # context.
  option('-h', '--help', 'print this message') { puts(self); exit }
  option('-V', '--version', 'print the version') { puts('0.0.1'); exit }
  option('-v', '--[no-]verbose', 'be noisy') { |v| $verbose = v }

  # Define an action to be run after commands are processed. This is optional.
  action do |*args|
    puts "Leftover args: #{args}" if $verbose
  end

  # Define one or more subcommands (with a brief description). They will be
  # turned into Ordu parsers, and given the remaining arguments to parse. The
  # DSL within a command is exactly like that of the top-level class.
  command 'sneeze', 'sneeze on the console' do
    option('-h', '--help', 'you are reading it') { puts(self); exit }
    option('-l', '--loud', 'sneeze louder') { @loud = true }
    option('-t', '--times N', Integer, 'sneeze repeatedly') { |n| @times = n }

    action do |*args|
      (@times || 1).times { puts 'Achoo!'.tap { |s| s.upcase! if @loud } }
      puts "After sneezing: #{args}" if $verbose
    end
  end
end

Sneezer.parse!(ARGV) # Processes the commands

This gives you a useless little tool which sneezed multiple times on demand. You can see it in action if you're in this project's directory, and you run

examples/sneezer.rb -h
examples/sneezer.rb sneeze -h

These commands print out the Ordús, and thence the options and available commands.

Development

After checking out the repo, 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 bundle exec rake install. To release a new version, update the version number in ordu.gemspec, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/bjjb/ordu. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.