trollop 1.7 → 1.7.1

data/History.txt

@@ -1,3 +1,6 @@
+== 1.7.1 / 2008-01-07
+* Documentation improvements
+
 == 1.7 / 2007-06-17
 * Fix incorrect error message for multiple missing required arguments
   (thanks to Neill Zero)

data/README.txt

@@ -4,20 +4,21 @@ by William Morgan <wmorgan-trollop@masanjin.net>
 
 http://trollop.rubyforge.org
 
-== DESCRIPTION:
+Documentation quickstart: See Trollop::Parser.
 
-Trollop is YAFCLAP --- yet another fine commandline argument
-processing library 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).
+== DESCRIPTION
 
-Trollop provides a nice automatically-generated help page, robust
-option parsing, and sensible defaults for everything you don't
-specify.
+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:
+== FEATURES/PROBLEMS
 
 - Simple usage.
 - Sensible defaults. No tweaking necessary, much tweaking possible.
@@ -26,20 +27,22 @@ Trollop: getting you 90% of the way there with only 10% of the effort.
 - Automatic help message generation, wrapped to current screen width.
 - Lots of unit tests.
 
-== SYNOPSIS:
+== SYNOPSIS
 
   ###### simple ######
 
+  require 'trollop'
   opts = Trollop::options do
-    opt :monkey, "Use monkey mode."
-    opt :goat, "Use goat model", :default => true
+    opt :monkey, "Use monkey mode"
+    opt :goat, "Use goat mode", :default => true
     opt :num_limbs, "Set number of limbs", :default => 4
   end
 
   p opts
 
-  ###### complex ######
+  ###### medium ######
 
+  require 'trollop'
   opts = Trollop::options do
     version "test 1.2.3 (c) 2007 William Morgan"
     banner <<-EOS
@@ -56,18 +59,75 @@ Trollop: getting you 90% of the way there with only 10% of the effort.
     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.exists?(opts[:file]) if opts[:file]
+  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:
+== REQUIREMENTS
 
-* none
+* none!
 
-== INSTALL:
+== INSTALL
 
 * gem install trollop
 
-== LICENSE:
+== LICENSE
 
-Copyright (c) 2007 William Morgan.
+Copyright (c) 2008 William Morgan.
 
 Trollop is distributed under the same terms as Ruby.

data/Rakefile

@@ -2,6 +2,8 @@
 
 require 'rubygems'
 require 'hoe'
+
+$:.unshift "lib"
 require 'trollop'
 
 class Hoe
@@ -11,7 +13,7 @@ end # thanks to "Mike H"
 Hoe.new('trollop', Trollop::VERSION) do |p|
   p.rubyforge_name = 'trollop'
   p.author = "William Morgan"
-  p.summary = "YAFCLAP --- yet another fine commandline argument processing library 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)."
+  p.summary = "Trollop is YAFCLAP --- yet another fine commandline argument processing library 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)."
 
   p.description = p.paragraphs_of('README.txt', 4..5, 9..18).join("\n\n").gsub(/== SYNOPSIS/, "Synopsis")
   p.url = "http://trollop.rubyforge.org"
@@ -19,11 +21,13 @@ Hoe.new('trollop', Trollop::VERSION) do |p|
   p.email = "wmorgan-trollop@masanjin.net"
 end
 
-## is there really no way to make a rule for this?
-WWW_FILES = %w(index.html README.txt FAQ.txt)
-
+WWW_FILES = FileList["www/*"] + %w(README.txt FAQ.txt)
 task :upload_webpage => WWW_FILES do |t|
   sh "scp -C #{t.prerequisites * ' '} wmorgan@rubyforge.org:/var/www/gforge-projects/trollop/"
 end
 
-# vim: syntax=Ruby
+task :upload_docs => [:docs] do |t|
+  sh "scp -Cr doc wmorgan@rubyforge.org:/var/www/gforge-projects/trollop/trollop"
+end
+
+# vim: syntax=ruby

data/lib/trollop.rb

@@ -5,7 +5,7 @@
 
 module Trollop
 
-VERSION = "1.7"
+VERSION = "1.7.1"
 
 ## Thrown by Parser in the event of a commandline error. Not needed if
 ## you're using the Trollop::options entry.
@@ -26,8 +26,9 @@ FLOAT_RE = /^-?((\d+(\.\d+)?)|(\.\d+))$/
 PARAM_RE = /^-(-|\.$|[^\d\.])/
 
 ## The commandline parser. In typical usage, the methods in this class
-## will be handled internally by Trollop#options, in which case only
-## the methods #opt, #banner and #version will be called.
+## will be handled internally by Trollop#options, in which case only the
+## methods #opt, #banner and #version, #depends, and #conflicts will
+## typically be called.
 class Parser
   ## The set of values specifiable as the :type parameter to #opt.
   TYPES = [:flag, :boolean, :bool, :int, :integer, :string, :double, :float]
@@ -171,9 +172,9 @@ class Parser
   def banner s; @order << [:text, s] end
   alias :text :banner
 
-  ## Marks two (or more!) options as requiring each other. Only
-  ## handles undirected dependcies. Directed dependencies are better
-  ## modeled with #die.
+  ## Marks two (or more!) options as requiring each other. Only handles
+  ## undirected (i.e., mutual) dependencies. Directed dependencies are
+  ## better modeled with Trollop::die.
   def depends *syms
     syms.each { |sym| raise ArgumentError, "unknown option '#{sym}'" unless @specs[sym] }
     @constraints << [:depends, syms]

metadata

@@ -3,15 +3,15 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: trollop
 version: !ruby/object:Gem::Version 
-  version: "1.7"
-date: 2007-06-17 00:00:00 -07:00
-summary: YAFCLAP --- yet another fine commandline argument processing library 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).
+  version: 1.7.1
+date: 2008-01-07 00:00:00 -08:00
+summary: Trollop is YAFCLAP --- yet another fine commandline argument processing library 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).
 require_paths: 
 - lib
 email: wmorgan-trollop@masanjin.net
 homepage: http://trollop.rubyforge.org
 rubyforge_project: trollop
-description: "Trollop is YAFCLAP --- yet another fine commandline argument processing library 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.  Synopsis:  ###### simple ######  opts = Trollop::options do opt :monkey, \"Use monkey mode.\" opt :goat, \"Use goat model\", :default => true opt :num_limbs, \"Set number of limbs\", :default => 4 end  p opts  ###### complex ######  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.exists?(opts[:file]) if opts[:file]  == REQUIREMENTS:  * none"
+description: "== 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).  - 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 ######"
 autorequire: 
 default_executable: 
 bindir: bin
@@ -38,10 +38,14 @@ files:
 - test/test_trollop.rb
 test_files: 
 - test/test_trollop.rb
-rdoc_options: []
-
-extra_rdoc_files: []
-
+rdoc_options: 
+- --main
+- README.txt
+extra_rdoc_files: 
+- FAQ.txt
+- History.txt
+- Manifest.txt
+- README.txt
 executables: []
 
 extensions: []