== trollop

by William Morgan <[email protected]>

http://trollop.rubyforge.org

Documentation quickstart: See Trollop::Parser.

== DESCRIPTION

Trollop is YAFCLAP --- yet another fine commandline argument processor
for Ruby. Trollop is designed to provide the maximal amount of GNU-style
argument processing in the minimum number of lines of code (for you, the
programmer).

Trollop provides a nice automatically-generated help page, robust option
parsing, and sensible defaults for everything you don't specify.

Trollop: getting you 90% of the way there with only 10% of the effort.

== FEATURES/PROBLEMS

- Simple usage.
- Sensible defaults. No tweaking necessary, much tweaking possible.
- Support for long options, short options, short option bundling,
and automatic type validation and conversion.
- Automatic help message generation, wrapped to current screen width.
- Lots of unit tests.

== SYNOPSIS

###### simple ######

require 'trollop'
opts = Trollop::options do
opt :monkey, "Use monkey mode"
opt :goat, "Use goat mode", :default => true
opt :num_limbs, "Set number of limbs", :default => 4
end

p opts

###### medium ######

require 'trollop'
opts = Trollop::options do
version "test 1.2.3 (c) 2007 William Morgan"
banner <<-EOS
Test is an awesome program that does something very, very important.

Usage:
test [options] <filenames>+
where [options] are:
EOS

opt :ignore, "Ignore incorrect values"
opt :file, "Extra data filename to read in, with a very long option description like this one", :type => String
opt :volume, "Volume level", :default => 3.0
opt :iters, "Number of iterations", :default => 5
end
Trollop::die :volume, "must be non-negative" if opts[:volume] < 0
Trollop::die :file, "must exist" unless File.exist?(opts[:file]) if opts[:file]

###### real-life ######

require 'trollop'
opts = Trollop::options do
version "sup-sync (sup #Redwood::VERSION)"
banner <<EOS
Synchronizes the Sup index with one or more message sources by adding
messages, deleting messages, or changing message state in the index as
appropriate.

[...]

Usage:
sup-sync [options] <source>*

where <source>* is zero or more source URIs. If no sources are given,
sync from all usual sources. Supported source URI schemes can be seen
by running "sup-add --help".

Options controlling WHICH messages sup-sync operates on:
EOS
opt :new, "Operate on new messages only. Don't scan over the entire source. (Default.)", :short => :none
opt :changed, "Scan over the entire source for messages that have been deleted, altered, or moved from another source. (In the case of mbox sources, this includes all messages AFTER an altered message.)"
opt :restored, "Operate only on those messages included in a dump file as specified by --restore which have changed state."
opt :all, "Operate on all messages in the source, regardless of newness or changedness."
opt :start_at, "For --changed and --all, start at a particular offset.", :type => :int

text <<EOS

Options controlling HOW message state is altered:
EOS
opt :asis, "If the message is already in the index, preserve its state. Otherwise, use default source state. (Default.)", :short => :none
opt :restore, "Restore message state from a dump file created with sup-dump. If a message is not in this dumpfile, act as --asis.", :type => String, :short => :none
opt :discard, "Discard any message state in the index and use the default source state. Dangerous!", :short => :none
opt :archive, "When using the default source state, mark messages as archived.", :short => "-x"
opt :read, "When using the default source state, mark messages as read."
opt :extra_labels, "When using the default source state, also apply these user-defined labels. Should be a comma-separated list.", :type => String, :short => :none

text <<EOS

Other options:
EOS
opt :verbose, "Print message ids as they're processed."
opt :optimize, "As the final operation, optimize the index."
opt :all_sources, "Scan over all sources.", :short => :none
opt :dry_run, "Don't actually modify the index. Probably only useful with --verbose.", :short => "-n"
opt :version, "Show version information", :short => :none

conflicts :changed, :all, :new, :restored
conflicts :asis, :restore, :discard
end
Trollop::die :restored, "requires --restore" if opts[:restored] unless opts[:restore]
if opts[:start_at]
Trollop::die :start_at, "must be non-negative" if opts[:start_at] < 0
Trollop::die :start_at, "requires either --changed or --all" unless opts[:changed] || opts[:all]
end

== REQUIREMENTS

* none!

== INSTALL

* gem install trollop

== LICENSE

Copyright (c) 2008 William Morgan.

Trollop is distributed under the same terms as Ruby.