docopt 0.0.4 → 0.5.0

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gem 'rake'

data/{LICENSE-MIT → LICENSE}

@@ -1,4 +1,7 @@
-Copyright (c) 2012 Vladimir Keleshev <vladimir@keleshev.com>, Alex Speller <alex@alexspeller.com>
+Copyright (c) 2012 Vladimir Keleshev <vladimir@keleshev.com>
+                   Blake Williams <code@shabbyrobe.org>
+                   Alex Speller <alex@alexspeller.com>
+                   Nima Johari
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in 

data/README.md

@@ -1,72 +1,79 @@
-`docopt` – command line option parser, that will make you smile
+`docopt.rb` – command line option parser, that will make you smile
 ===============================================================================
 
-[![Build Status](https://secure.travis-ci.org/alexspeller/docopt.png?branch=master)](http://travis-ci.org/alexspeller/docopt)
+This is the ruby port of [`docopt`](https://github.com/docopt/docopt),
+the awesome option parser written originally in python.
 
-Isn't it awesome how `optparse` and other option parsers generate help and
-usage-messages based on your code?!
+> New in version 0.5.0:
+>
+> Repeatable flags and commands are counted if repeated (a-la ssh `-vvv`).
+> Repeatable options with arguments are accumulated into list.
 
-Hell no!  You know what's awesome?  It's when the option parser *is* generated
-based on the help and usage-message that you write in a docstring!  This way
+Isn't it awesome how `optparse` and `argparse` generate help messages
+based on your code?!
+
+*Hell no!*  You know what's awesome?  It's when the option parser *is* generated
+based on the beautiful help message that you write yourself!  This way
 you don't need to write this stupid repeatable parser-code, and instead can
-write a beautiful usage-message (the way you want it!), which adds readability
-to your code.
+write only the help message--*the way you want it*.
 
-Now you can write an awesome, readable, clean, DRY code like *that*:
+`docopt` helps you create most beautiful command-line interfaces *easily*:
 
 ```ruby
-doc = "Usage: example.rb [options] <arguments>...
+require "docopt"
+doc = <<DOCOPT
+Naval Fate.
+
+Usage:
+  #{__FILE__} ship new <name>...
+  #{__FILE__} ship <name> move <x> <y> [--speed=<kn>]
+  #{__FILE__} ship shoot <x> <y>
+  #{__FILE__} mine (set|remove) <x> <y> [--moored|--drifting]
+  #{__FILE__} -h | --help
+  #{__FILE__} --version
 
 Options:
-  -h --help            show this help message and exit
-  --version            show version and exit
-  -v --verbose         print status messages
-  -q --quiet           report only file names
-  -r --repeat          show all occurrences of the same error
-  --exclude=patterns   exclude files or directories which match these comma
-                       separated patterns [default: .svn,CVS,.bzr,.hg,.git]
-  --filename=patterns  when parsing directories, only check filenames matching
-                       these comma separated patterns [default: *.rb]
-  --select=errors      select errors and warnings (e.g. E,W6)
-  --ignore=errors      skip errors and warnings (e.g. E4,W)
-  --show-source        show source code for each error
-  --statistics         count errors and warnings
-  --count              print total number of errors and warnings to standard
-                       error and set exit code to 1 if total is not null
-  --benchmark          measure processing speed
-  --testsuite=dir      run regression tests from dir
-  --doctest            run doctest on myself"
-
-require 'docopt'
-
-
-if __FILE__ == $0
-    options = Docopt(doc, '1.0.0')  # parse options based on doc above
-    puts options.inspect
-    puts ARGV.inspect
+  -h --help     Show this screen.
+  --version     Show version.
+  --speed=<kn>  Speed in knots [default: 10].
+  --moored      Moored (anchored) mine.
+  --drifting    Drifting mine.
+
+DOCOPT
+
+begin
+  require "pp"
+  pp Docopt::docopt(doc)
+rescue Docopt::Exit => e
+  puts e.message
 end
 ```
 
-Hell yeah! The option parser is generated based on `doc` string above, that you
-pass to the `Docopt` function.
+Beat that! The option parser is generated based on the docstring above that is
+passed to `docopt` function.  `docopt` parses the usage pattern
+(`Usage: ...`) and option descriptions (lines starting with dash "`-`") and
+ensures that the program invocation matches the usage pattern; it parses
+options, arguments and commands based on that. The basic idea is that
+*a good help message has all necessary information in it to make a parser*.
 
-```ruby
-require 'docopt'
-doc = "Usage: your_program.rb [options]
+Installation
+===============================================================================
 
-  -h --help     Show this.
-  -v --verbose  Print more text.
-  --quiet       Print less text.
-  -o FILE       Specify output file [default: ./test.txt]"
+Docopt is available via rubygems:
 
-options = Docopt(doc, version=nil, help=true)`
+    gem install docopt
 
-options['--help'] # returns true or false depending on option given
+Alternatively, you can just drop `lib/docopt.rb` file into your project--it is
+self-contained. [Get source on github](http://github.com/docopt/docopt.rb).
 
-```
+`docopt` has been confirmed to work with 1.8.7p370 and 1.9.3p194. If you have
+noticed it working (or not working) with an earlier version, please raise an
+issue and we will investigate support.
 
+API
+===============================================================================
 
-`Docopt` takes 1 required and 2 optional arguments:
+`Docopt` takes 1 required and 1 optional argument:
 
 - `doc` should be a string that
 describes **options** in a human-readable format, that will be parsed to create
@@ -81,6 +88,10 @@ section. Here is a quick example of such a string:
         --quiet       Print less text.
         -o FILE       Specify output file [default: ./test.txt].
 
+
+The optional second argument contains a hash of additional data to influence
+docopt. The following keys are supported: 
+
 - `help`, by default `true`, specifies whether the parser should automatically
 print the usage-message (supplied as `doc`) in case `-h` or `--help` options
 are encountered. After showing the usage-message, the program will terminate.
@@ -97,101 +108,79 @@ Note, when `docopt` is set to automatically handle `-h`, `--help` and
 `--version` options, you still need to mention them in the options description
 (`doc`) for your users to know about them.
 
-The **return** value is an instance of the ```Docopt``` class:
-
-```ruby
-doc = "Options:
-  --verbose
-  -o FILE  Output file [default: out.txt]"
-  
-options = Docopt(doc)
-
-puts options.inspect
-# --verbose=nil
-# -o="out.txt"
-```
-
-You can access the values of options like a hash:
-
-```
-doc = "Options:
-  -v, --verbose  Verbose output [default: true]
-  -o FILE  Output file [default: out.txt]"
-  
-options = Docopt(doc)
+The **return** value is just a dictionary with options, arguments and commands,
+with keys spelled exactly like in a help message
+(long versions of options are given priority). For example, if you invoke
+the top example as::
 
-# The following are equivilant:
-
-puts options['-v']
-puts options['--verbose']
-puts options[:v]
-puts options[:verbose]
+    naval_fate.rb ship Guardian move 100 150 --speed=15
 
+the return dictionary will be::
 
+```ruby
+{"ship"=>true,
+ "new"=>false,
+ "<name>"=>["Guardian"],
+ "move"=>true,
+ "<x>"=>"100",
+ "<y>"=>"150",
+ "--speed"=>"15",
+ "shoot"=>false,
+ "mine"=>false,
+ "set"=>false,
+ "remove"=>false,
+ "--moored"=>false,
+ "--drifting"=>false,
+ "--help"=>false,
+ "--version"=>false}
 ```
 
-You can access positional arguments in `ARGV`.
-
-`doc` string format for your usage-message
+Help message format
 ===============================================================================
 
-The main idea behind `docopt` is that a good usage-message (that describes
-options and defaults unambiguously) is enough to generate an option parser.
-
-Here are the simple rules (that you probably already follow) for your
-usage-message to be parsable:
-
-- Every line that starts with `-` or `--` (not counting spaces) is treated
-as an option description, e.g.:
-
-        Options:
-          --verbose   # GOOD
-          -o FILE     # GOOD
-        Other: --bad  # BAD, line does not start with dash "-"
+docopt.rb follows the docopt help message format.
+You can find more details at
+[official docopt git repo](https://github.com/docopt/docopt#help-message-format)
 
-- To specify that an option has an argument, put a word describing that
-argument after space (or equals `=` sign) as shown below.
-You can use comma if you want to separate options. In the example below both
-lines are valid, however you are recommended to stick to a single style.
 
-        -o FILE --output=FILE       # without comma, with "=" sign
-        -i <file>, --input <file>   # with comma, wihtout "=" sing
+Examples
+-------------------------------------------------------------------------------
 
-- Use two spaces to separate options with their informal description.
+We have an extensive list of
+[examples](https://github.com/docopt/docopt.rb/tree/master/examples)
+which cover every aspect of functionality of `docopt`.  Try them out,
+read the source if in doubt.
 
-        --verbose More text.   # BAD, will be treated as if verbose option had
-                               # an argument "More", so use 2 spaces instead
-        -q        Quit.        # GOOD
-        -o FILE   Output file. # GOOD
-        --stdout  Use stdout.  # GOOD, 2 spaces
+Data validation
+-------------------------------------------------------------------------------
 
-- If you want to set a default value for an option with an argument, put it
-into the option description, in form `[default: <my-default-value>]`.
+`docopt` does one thing and does it well: it implements your command-line
+interface.  However it does not validate the input data.  We are looking
+for ruby validation libraries to make your option parsing experiene
+even more awesome!
+If you've got any suggestions or think your awesome schema validation gem
+fits well with `docopt.rb`, open an issue on github and enjoy the eternal glory!
 
-        -i INSTANCE      Instance of something [default: 1]
-        --coefficient=K  The K coefficient [default: 2.95]
-        --output=FILE    Output file [default: test.txt]
-        --directory=DIR  Some directory [default: ./]
-
-Something missing? Help porting [docopt](http://docopt.org/) to Ruby!
-===============================================================================
-
-Compatibility notice:
+Contribution
 ===============================================================================
 
-In order to maintain your program's compatibility with future versions
-of `docopt.rb` (as porting more features continues) you are recommended to
-keep the following in the begining of `doc` argument:
+We would *love* to hear what you think about `docopt.rb`.
+Contribute, make pull requrests, report bugs, suggest ideas and discuss
+`docopt.rb` on
+[issues page](http://github.com/docopt/docopt.rb/issues).
 
-    Usage: my_program.rb [options] <arguments>...
+If you want to discuss the original `docopt` reference,
+point to [it's home](http://github.com/docopt/docopt) or
+drop a line directly to vladimir@keleshev.com!
 
-or
-
-    Usage: my_program.rb [options] <argument>
-
-or
+Porting `docopt` to other languages
+===============================================================================
 
-    Usage: my_program.rb [options]
+Docopt is an interlinguistic (?) effort,
+and this is the ruby port of `docopt`.
+We coordinate our efforts with docopt community and try our best to
+keep in sync with the python reference.
 
-(followed by an empty line), where you are free to change `my_program.rb`
-and `argument(s)` name inside of `<...>`.
+Docopt community *loves* to hear what you think about `docopt`, `docopt.rb`
+and other sister projects on docopt's
+[issues page](http://github.com/docopt/docopt/issues).

data/Rakefile

@@ -0,0 +1,150 @@
+require 'rubygems'
+require 'rake'
+require 'date'
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def date
+  Date.today.to_s
+end
+
+def rubyforge_project
+  name
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
+end
+
+#############################################################################
+#
+# Standard tasks
+#
+#############################################################################
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+desc "Generate RCov test coverage and open in your browser"
+task :coverage do
+  require 'rcov'
+  sh "rm -fr coverage"
+  sh "rcov test/test_*.rb"
+  sh "open coverage/index.html"
+end
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "#{name} #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/#{name}.rb"
+end
+
+#############################################################################
+#
+# Custom tasks (add your own tasks here)
+#
+#############################################################################
+
+
+
+#############################################################################
+#
+# Packaging tasks
+#
+#############################################################################
+
+desc "Create tag v#{version} and build and push #{gem_file} to Rubygems"
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh "git push origin master"
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{name}-#{version}.gem"
+end
+
+desc "Build #{gem_file} into the pkg directory"
+task :build => :gemspec do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+desc "Generate #{gemspec_file}"
+task :gemspec => :validate do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # replace name version and date
+  replace_header(head, :name)
+  replace_header(head, :version)
+  replace_header(head, :date)
+  #comment this out if your rubyforge_project has a different name
+  replace_header(head, :rubyforge_project)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg)/ }.
+    map { |file| "    #{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end
+
+desc "Validate #{gemspec_file}"
+task :validate do
+  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
+  unless libfiles.empty?
+    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
+    exit!
+  end
+  unless Dir['VERSION*'].empty?
+    puts "A `VERSION` file at root level violates Gem best practices."
+    exit!
+  end
+end