minimal option and argument parsing for ruby
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
spec
.gitignore
Gemfile
LICENSE.txt
README.md
Rakefile
arginine.gemspec

README.md

Arginine

Features/Philosophy

  • Specifies positional arguments, options, and flags
  • Is compatible with ARGF
  • Has no dependencies beyond optparse
  • Uses as simple an interface as I could devise

Installation

$ gem install arginine

Usage

Args, opts, flags, and argf

The syntax looks like optparse but breezier. You put in positional arguments with arg, options with opt, and flags with flag. There is a special command argf does not affect parsing but instead puts a note in the usage output. You can name your arguments/options/flags with symbols or strings and access the user's input via the output dictionary.

require 'arginine'
par = Arginine::parse do
  arg :my_first_arg
  arg "my second arg"
  opt :my_option
  flag :my_flag
  argf "input files"
end

Call this with script.rb foo bar --my_option baz --my_flag to get the hash par with value {my_first_arg: "foo", "my second arg" => "bar", my_option: "baz", my_flag: true}.

Casting

You can cast arguments and options using method names or your own procs.

par = Arginine::parse do
  arg :my_int, cast: :to_i
  opt :list_o_floats, cast: lambda { |s| s.split(",").map(&:to_f) }
end
p par

Call this with script.rb 42 --list_o_floats 1,2.0,3 to get {my_int: 42, list_o_floats: [1.0, 2.0, 3.0]}.

There is a special cast option Arginine::fh that, if passed a filename, will return the opened file object. If passed -, it will return standard input. For example,

par = Arginine::parse do
  arg :file1, cast: Arginine::fh
  arg :file2, cast: Arginine::fh
end

would allow you to call your script with script.rb a b, cat a | script.rb - b or cat b | script a - to get the same results.

Defaults

You can set default values for options.

params = Arginine::parse
  opt :foo, default: "bar"
end

By default, Arginine will create a description for an option with a default that tell the value of the default. You can turn that off with no_defaults inside the parse block.

Automatic short names

You can pick a short name, or let a default one be assigned.

params = Arginine::parse do
  opt :foo
  opt :bar, :short => "z"
  argf "tables"
end

gives the --help message

usage: script.rb [options] [fns/stdin: tables]
  -f, --foo [foo]
  -z, --bar [bar]

Descriptions

You can give the whole script a description. Each argument/option/flag can get one too.

params = Arginine::parse do
  desc "this script foos a bar"
  opt :foo, desc: "it's like goo but better"
end

Advanced topics

You can create an instance of the parser and modify it step by step. For example,

a = Arginine::Parser.new
a.opt :foo
p = a.parse(['--foo', 'bar'])

will create the dictionary p as {foo: 'bar'}. For testing purposes, you can call parse with include_help=true so that the output dictionary will have an entry :help that contains the help message.

Contributing

  1. Fork it ( https://github.com/swo/arginine/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

To do

[empty!]