• Stars
    star
    176
  • Rank 216,987 (Top 5 %)
  • Language
    Ruby
  • License
    MIT License
  • Created over 16 years ago
  • Updated almost 8 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Choice is a gem for defining and parsing command line options with a friendly DSL.

<img src=“https://travis-ci.org/defunkt/choice.svg?branch=master” />

Welcome to Choice

Choice is a small library for defining and parsing command line options. It works awesomely with Highline or other command line interface libraries.

Choice was written by Chris Wanstrath as an exercise in test driving development of a DSL. This project is still an infant: bugs are expected and tattling on them is appreciated.

Installing is easy, with RubyGems. Give it a shot:

$ gem install choice

E-mail inquiries can be directed to chris[at]ozmm[dot]org.

Of course, Choice is licensed under the MIT License, which you can find included in the LICENSE file or by surfing your World Wide Web browser of choice towards www.opensource.org/licenses/mit-license.php.

Using Choice

An examples directory is included with Choice, in which some contrived Ruby programs utilizing the library have been placed. Here’s a snippet:

ftpd.rb

require 'choice'

PROGRAM_VERSION = 4

Choice.options do
  header ''
  header 'Specific options:'

  option :host do
    short '-h'
    long '--host=HOST'
    desc 'The hostname or ip of the host to bind to (default 127.0.0.1)'
    default '127.0.0.1'
  end

  option :port do
    short '-p'
    long '--port=PORT'
    desc 'The port to listen on (default 21)'
    cast Integer
    default 21
  end

  separator ''
  separator 'Common options: '

  option :help do
    long '--help'
    desc 'Show this message'
  end

  option :version do
    short '-v'
    long '--version'
    desc 'Show version'
    action do
      puts "ftpd.rb FTP server v#{PROGRAM_VERSION}"
      exit
    end
  end
end

puts 'port: ' + Choice[:port]

Notice the last line. For free, you will be given a Choice.choices hash which contain, at runtime, the options found and their values.

Choice[:key] is a shortcut for Choice.choices[:key].

Because we gave option :port a default of 21, Choice[:port] should be 21 if we run ftpd.rb with no options. Let’s see.

$ ruby ftpd.rb
port: 21

Cool. On our system, port 21 is reserved. Let’s use another port.

$ ruby ftpd.rb -p 2100
port: 2100

Alright. And, of course, there is the hard way of doing things.

$ ruby ftpd.rb --port=2100
port: 2100

That :version option looks pretty interesting, huh? I wonder what it does…

$ ruby ftpd.rb -v
ftpd.rb FTP server v4

That’s not all, though. We also get a --help option for free.

$ ruby ftpd.rb --help
Usage: ftpd.rb [-hpv]

Specific options:
    -h, --host=HOST                  The hostname or ip of the host to bind to (default 127.0.0.1)
    -p, --port=PORT                  The port to listen on (default 21)

Common options:
        --help                       Show this message
    -v, --version                    Show version

The Choice.choices hash

Keep in mind that your option’s key in the Choice.choices hash is defined by the first parameter passed to option statement. This is perfectly legit, albeit somewhat confusing:

option :name do
  short '-h'
  long '--handle=NAME'
  desc "Your handle."
end

You can access this option by using Choice.choices[:name], not :handle.

Option options

Obviously, Choice revolves around the option statement, which receives a block. Here are all the, er, options option accepts. None of them are required but short or long must be present for Choice to know what to do.

Options must be defined in the context of a Choice.options block, as seen above. This context is assumed for the following explanations.

For the quick learners, here’s the list:

  • short

  • long

  • default

  • desc

  • cast

  • valid (takes array)

  • validate (takes regex)

  • filter (takes a block)

  • action (ditto)

You can define these within your option in any order which pleases you.

short

Defines the short switch for an option. Expected to be a dash and a single character.

short '-s'

long

Defines the long switch for an option. Expected to be a double dash followed by a string, an equal sign (or a space), and another string.

There are two variants: longs where a parameter is required and longs where a parameter is optional, in which case the value will be true if the option is present.

Optional:

long '--debug=[LEVEL]'

Assuming our program defines Choices and ends with this line:

puts 'debug: ' + Choice.choices[:debug]

we can do this:

$ ruby ftpd.rb --debug
debug: true

$ ruby ftpd.rb --debug=1
debug: 1

$ ruby ftpd.rb --debug 1
debug: 1

Required:

long '--debug=LEVEL'

Assuming the same as above:

$ ruby ftpd.rb --debug 1
debug: 1

$ ruby ftpd.rb --debug
<help screen printed>

long as array

Often you may wish to allow users the ability to pass in multiple arguments and have them all combined into an array. You can accomplish this by defining a long and setting the caps-argument to *ARG. Like this:

long '--suit *SUITS'

Choice.choices.suits will now return an array. Here’s an example of usage:

$ ruby --suit hearts clubs
suit: ['hearts', 'clubs']

Check out examples/gamble.rb for more information on this cool feature.

default

You can define a default value for your option, if you’d like. If the option is not present in the argument list, the default will be returned when trying to access that element of the Choice.choices hash.

As with the above, assume our program prints Choice.choices[:debug]:

default 'info'

If we don’t pass in --debug, the :debug element of our hash will be ‘info.’

$ ftpd.rb
debug: info

$ ftpd.rb --debug warn
debug: warn

desc

The description of this option. Fairly straightforward, with one little trick: multiple desc statements in a single option will be considered new desc lines. The desc lines will be printed in the order they are defined. Like this:

desc "Your hostname."
desc "(default 'localhost')"

A snippet from your --help might then look like this:

-h, --host=HOST                  Your hostname.
                                 (default 127.0.0.1)

cast

By default, all members of the Choice.choices hash are strings. If you want something different, like an Integer for a port number, you can use the cast statement.

cast Integer

Currently support cast options:

  • Integer

  • String

  • Float

  • Symbol

We’ll probably add Date, Time, and DateTime in the future, if people want them.

valid

Giving valid an array creates a whitelist of acceptable arguments.

valid %w[clubs hearts spades diamonds]

If our option is passed anything other than one of the four card suits, the help screen will be printed. It might be a good idea to include acceptable arguments in your option’s “desc” value.

$ ruby gamble.rb -s clubs
suit: clubs

$ ruby gamble.rb -s joker
<help screen printed>

validate

The validate statement accepts a regular expression which it will test against the value passed. If the test fails, the --help screen will be printed. I love ports, so let’s stick with that example:

validate /^\d+$/

Of course, 2100 matches this:

$ ruby ftpd.rb -p 2100
port: 2100

I like dogs. I wish dogs could be ports. Alas, Choice knows better (once I’ve told it so):

$ ruby ftpd.rb -p labradoodle
<help screen printed>

filter

The filter statement lets you play with a value before it goes into the Choice.choices hash. If you use cast, this will occur post-casting.

In this program we’re defining a :name option and saying we don’t want any crazy characters in it, then printing that element of the Choice.choices+ hash:

filter do |value|
  value = value.gsub(/[^\w]/, '')
end

Now:

$ ruby ftpd.rb --name=c.hr.is
name: chris

You can probably think of better uses.

action

A block passed to the action statement will be run if that particular option is passed. See the --version example earlier.

required options

You can specify an option as being required by passing :required => true to the option definition. Choice will then print the help screen if this option is not present. Please let your dear users know which options are required.

For example:

option :card, :required => true do
  short '-c'
  long '--card CARD'
  desc "The card you wish to gamble on.  Required.  Only one, please."
end

Then:

$ ruby gamble.rb
<help screen, -c or --card wasn't passed>

Other options

These statements are purely aesthetic, used to help make your --help screen a little more digestible.

Passing an empty string to any of these options will print a newline.

banner

The banner is the first line printed when your program is called with --help. By default, it will be something like this, based on the options defined:

Usage: ftpd.rb [-hpv]

You can pass any string to the banner statement to override what prints. This might be useful if you’re into ascii art.

banner "Usage: ftpd.rb"

header

The header is what shows up after the banner but before your option definitions are printed. Each header call is a newline. Check out the example above.

header "ftp is a harsh and unforgiving protocol."

separator

As in the example above, you can put separators between options to help display the logical groupings of your options. Or whatever.

separator "----"

To get a blank line, rock an empty string:

separator ''

The footer is displayed after all your options are displayed. Nothing new here, works like the other options above.

footer "That's all there is to it!"

Shorthand

Now that you’ve gone through all the hard stuff, here’s the easy stuff: Choice options can be defined with a simple hash if you’d like. Here’s an example, from the tests:

Choice.options do
  header "Tell me about yourself?"
  header ""
  options :band => { :short => "-b", :long => "--band=BAND", :cast => String, :desc => "Your favorite band.",
                    :validate => /\w+/ },
          :animal => { :short => "-a", :long => "--animal=ANIMAL", :cast => String, :desc => "Your favorite animal." }

  footer ""
  footer "--help This message"
end

How’s that tickle you? Real nice.

It looks like poetry

That’s it. Not much, I know. Maybe this will make handling your command line options a bit easier. You can always use the option parser in the standard Ruby library, but DSLs are just so cool. As one of my non-programmer friends said of a Ruby DSL: “It looks like poetry.”

It’s totally broken

Okay, I knew this would happen. Do me a favor, if you have time: run rake from the Choice directory and send me the output (chris[at]ozmm[dot]org). This’ll run the unit tests. Also, if you would, send me a bit of information on your platform. Choice was tested on OS X and RHEL with a 2.4 kernel but who knows. Thanks a lot.

Thanks to

For bug reports, patches, and ideas I’d be honored to thank the following:

  • Justin Bailey

  • Alexis Li

More Repositories

1

jquery-pjax

pushState + ajax = pjax
JavaScript
16,740
star
2

gist

Potentially the best command line gister.
Ruby
3,805
star
3

dotjs

~/.js
Ruby
3,161
star
4

facebox

Facebook-style lightbox, built in jQuery
JavaScript
1,928
star
5

unicorn

Unofficial Unicorn Mirror.
Ruby
1,410
star
6

pystache

Mustache in Python
Python
1,308
star
7

github-gem

`github` command line helper for simplifying your GitHub experience.
Ruby
1,123
star
8

cijoe

CI Joe is a fun Continuous Integration server. Unmaintained.
Ruby
1,046
star
9

coffee-mode

Emacs Major Mode for CoffeeScript
Emacs Lisp
574
star
10

gist.el

Yet another Emacs paste mode, this one for Gist.
Emacs Lisp
548
star
11

hurl

Hurl makes HTTP requests.
JavaScript
529
star
12

rip

Take back your $LOAD_PATH. Deprecated and unmaintained.
Ruby
363
star
13

repl

Sometimes you need a REPL. Unmaintained, sorry.
Ruby
360
star
14

textmate.el

Basic emulation of awesome TextMate features for Emacs.
Emacs Lisp
356
star
15

colored

Colors in your terminal. Unmaintained.
Ruby
270
star
16

cache_fu

Ghost from Christmas past. Unmaintained.
Ruby
257
star
17

exception_logger

Unmaintained. Sorry.
Ruby
242
star
18

cheat

Cheating is fun!
Ruby
239
star
19

Zen

Distraction free writing for Atom.
CoffeeScript
193
star
20

emacs

My Emacs config
Emacs Lisp
187
star
21

ambition

include Enumerable — Unmaintained
Ruby
165
star
22

markdown-mode

Emacs Markdown mode
Emacs Lisp
155
star
23

lyndon

Lyndon wraps JavaScript in a loving MacRuby embrace. A fun hack that is no longer maintained.
Ruby
145
star
24

nginx_config_generator

Generates nginx config files from YAML.
Ruby
125
star
25

acts_as_textiled

Makes your models act as textiled.
Ruby
115
star
26

resque-lock

A Resque plugin for ensuring only one instance of your job is running at a time.
Ruby
113
star
27

mofo

Mofo was a fast and simple microformat parser, based on a concise DSL and Hpricot. No longer maintained.
JavaScript
91
star
28

gem-man

RubyGems plugin to view a gem's manpage.
Ruby
85
star
29

quake

The source code to Quake, one of the best games ever.
79
star
30

mustache-sinatra-example

An example of using Mustache in a Sinatra app.
Ruby
79
star
31

defunkt.github.com

My GitHub Page
HTML
78
star
32

sake

System wide Rake.
Ruby
76
star
33

starling

Ruby
74
star
34

resque

Moved to resque/resque
57
star
35

ircamp

IRC <-> Campfire Bridge
Python
54
star
36

evilbot

an evil bot that's definitely not for convore
CoffeeScript
50
star
37

jasper

Lispy JavaScript
JavaScript
40
star
38

gibberish

Dead simple Rails localization.
Ruby
37
star
39

Mustache.tmbundle

A little textmate bundle for defunkt/mustache
36
star
40

resque-web

Sinatra-based web UI for Resque
Ruby
30
star
41

ike

Rake in Io.
Io
28
star
42

mapreducerb

Simple map/reduce in Ruby
Ruby
26
star
43

sake-tasks

Your own personal sake tasks, ripe for sharing.
25
star
44

matzbot

matzbot is nice so we are nice
Ruby
22
star
45

mustache-syntax-highlighter

Syntax highlighting plugin for mustache.rb
Ruby
22
star
46

repl-completion

Completion files for repl(1)
22
star
47

sfruby-meetup-resque

My Resque presentation at the SF Ruby Meetup, January 2010
Ruby
21
star
48

ftpd.rb

A simple ftp daemon, written in Ruby. Do not use — here for historical purposes.
Ruby
19
star
49

zippy

Zippy lil’ zipcode lib.
Ruby
18
star
50

subtlety

Subtlety: SVN => RSS, hAtom => Atom
Ruby
16
star
51

ambitious_activerecord

Unmaintained Ambitious ActiveRecord adapter, for Ambition.
Ruby
15
star
52

cheat.el

Cheat Emacs mode
Emacs Lisp
15
star
53

fixture_scenarios_builder

Build your fixtures in Ruby.
Ruby
15
star
54

resque-cli

A command line program for talking to Resque.
15
star
55

iui

Import of the iui library
JavaScript
14
star
56

ambitious_activeldap

Ambition adapter for ActiveLdap
Ruby
13
star
57

dodgeball.github.com

yes
Ruby
12
star
58

ooc-markdown

A Discount binding for ooc
C
12
star
59

pinder

My fork of Pinder, the Campfire API for Python developers.
Python
10
star
60

sdoc-helpers

Simple helpers to make using sdoc easier.
Ruby
10
star
61

metaid

10
star
62

Markdown-problems

Public repository to submit markdown problems to github support
9
star
63

currency_converter

Objective-C
9
star
64

magit

Mirror of the Magit Emacs mode.
Emacs Lisp
8
star
65

burn

Sinatra => Campfire
7
star
66

my-awesome-framework

A simple demonstration of how to effectively use Git submodules.
7
star
67

repo-in-a-repo

7
star
68

sakerb

Sake repository served fresh by the guys at Barefoot.
Ruby
7
star
69

barefootexamples

Ruby
7
star
70

ozimodo

An ancient Ruby on Rails powered tumblelog.
7
star
71

electron-wordwrap

7
star
72

redis-namespace

Moved to resque/redis-namespace
6
star
73

rtimeout

Ruby
6
star
74

lacampfire

Logical Awesome Campfire userscript.
JavaScript
6
star
75

my-fun-repo

5
star
76

my-fantastic-plugin

A simple demonstration of how to effectively use Git submodules.
5
star
77

github-markup

Moved!
5
star