docopt 0.0.1

data/README.md

@@ -0,0 +1,172 @@
+`docopt` – command line option parser, that will make you smile
+===============================================================================
+
+Help porting [docopt](http://docopt.org/) to Ruby!
+
+Isn't it awesome how `optparse` and other option parsers generate help and
+usage-messages based on your code?!
+
+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
+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.
+
+Now you can write an awesome, readable, clean, DRY code like *that*:
+
+```ruby
+doc = "Usage: example.rb [options] <arguments>...
+
+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
+end
+```
+
+Hell yeah! The option parser is generated based on `doc` string above, that you
+pass to the `docopt` function.
+
+API `require 'docopt'`
+===============================================================================
+
+###`options = docopt(doc, version=nil, help=true)`
+
+`docopt` takes 1 required and 2 optional arguments:
+
+- `doc` should be a string that
+describes **options** in a human-readable format, that will be parsed to create
+the option parser.  The simple rules of how to write such a docstring
+(in order to generate option parser from it successfully) are given in the next
+section. Here is a quick example of such a string:
+
+        Usage: your_program.rb [options]
+
+        -h --help     Show this.
+        -v --verbose  Print more text.
+        --quiet       Print less text.
+        -o FILE       Specify output file [default: ./test.txt].
+
+- `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.
+If you want to handle `-h` or `--help` options manually (as all other options),
+set `help=false`.
+
+- `version`, by default `nil`, is an optional argument that specifies the
+version of your program. If supplied, then, if the parser encounters
+`--version` option, it will print the supplied version and terminate.
+`version` could be any printable object, but most likely a string,
+e.g. `'2.1.0rc1'`.
+
+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 a hash with option values
+(giving long options precedence), e.g:
+
+    {"--benchmark"=>true,
+     "--count"=>true,
+     "--doctest"=>false,
+     "--exclude"=>".svn,CVS,.bzr,.hg,.git",
+     "--filename"=>"*.rb",
+     "--help"=>false,
+     "--ignore"=>false,
+     "--quiet"=>false,
+     "--repeat"=>false,
+     "--select"=>"*.rb",
+     "--show-source"=>true,
+     "--statistics"=>true,
+     "--testsuite"=>false,
+     "--verbose"=>true,
+     "--version"=>false}
+
+You can access positional arguments in `ARGV`.
+
+`doc` string format for your usage-message
+===============================================================================
+
+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 "-"
+
+- 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
+
+- Use two spaces to separate options with their informal description.
+
+        --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
+
+- 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>]`.
+
+        -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:
+===============================================================================
+
+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:
+
+    Usage: my_program.rb [options] <arguments>...
+
+or
+
+    Usage: my_program.rb [options] <argument>
+
+or
+
+    Usage: my_program.rb [options]
+
+(followed by an empty line), where you are free to change `my_program.rb`
+and `argument(s)` name inside of `<...>`.

data/docopt.rb

@@ -0,0 +1,116 @@
+require 'getoptlong'
+
+
+class Option
+
+    attr_reader :short, :long, :argcount, :value
+
+    def initialize(short=nil, long=nil, argcount=0, value=false)
+        @short, @long, @argcount, @value = short, long, argcount, value
+    end
+
+    def getopt
+        [@long, @short, @argcount].compact
+    end
+
+    def inspect
+        "Option.new(#{@short}, #{@long}, #{@argcount}, #{@value})"
+    end
+
+    def == other
+        self.inspect == other.inspect
+    end
+
+end
+
+
+def option parse
+    options, _, description = parse.strip.partition('  ')
+    options = options.sub(',', ' ').sub('=', ' ')
+    short, long, argcount, value = nil, nil, 0, false
+    for s in options.split
+        if s.start_with? '--'
+            long = s
+        elsif s.start_with? '-'
+            short = s
+        else
+            argcount = 1
+        end
+    end
+    if argcount == 1
+        matched = description.scan(/\[default: (.*)\]/)[0]
+        value = matched ? matched[0] : false
+    end
+    Option.new(short, long, argcount, value)
+end
+
+
+class MyHash < Hash
+    def inspect
+        "{#{self.to_a.sort.map {|i| "%p=>%p" % i}.join(",\n ")}}"
+    end
+end
+
+
+def docopt(doc, version=nil, help=true)
+    ret = MyHash.new
+    docopts = []
+    doc.split(/^ *-|\n *-/)[1..-1].each do |s|
+        docopt = option('-' + s)
+        docopts += [docopt]
+        ret[(docopt.long or docopt.short)] = docopt.value
+    end
+    begin
+        GetoptLong.new(*docopts.map {|e| e.getopt}).each do |opt, arg|
+            if help and (opt == '--help' or opt == '-h')
+                puts doc.strip
+                exit
+            elsif version and opt == '--version'
+                puts version
+                exit
+            elsif (docopts.select {|d|(d.long or d.short)==opt})[0].argcount==0
+                ret[opt] = true
+            else
+                ret[opt] = arg
+            end
+        end
+    rescue
+        exit 1
+    end
+    ret
+end
+
+
+if __FILE__ == $0
+
+    def assert cond
+        print cond ? '.' : 'F'
+    end
+
+    assert option('-h') == Option.new('-h', nil)
+    assert option('--help') == Option.new(nil, '--help')
+    assert option('-h --help') == Option.new('-h', '--help')
+    assert option('-h, --help') == Option.new('-h', '--help')
+
+    assert option('-h TOPIC') == Option.new('-h', nil, 1)
+    assert option('--help TOPIC') == Option.new(nil, '--help', 1)
+    assert option('-h TOPIC --help TOPIC') == Option.new('-h', '--help', 1)
+    assert option('-h TOPIC, --help TOPIC') == Option.new('-h', '--help', 1)
+    assert option('-h TOPIC, --help=TOPIC') == Option.new('-h', '--help', 1)
+
+    assert option('-h  Description...') == Option.new('-h', nil)
+    assert option('-h --help  Description...') == Option.new('-h', '--help')
+    assert option('-h TOPIC  Description...') == Option.new('-h', nil, 1)
+
+    assert option('    -h') == Option.new('-h', nil)
+
+    assert option('-h TOPIC  Descripton... [default: 2]') ==
+               Option.new('-h', nil, 1, '2')
+    assert option('-h TOPIC  Descripton... [default: topic-1]') ==
+               Option.new('-h', nil, 1, 'topic-1')
+    assert option('--help=TOPIC  ... [default: 3.14]') ==
+               Option.new(nil, '--help', 1, '3.14')
+    assert option('-h, --help=DIR  ... [default: ./]') ==
+               Option.new('-h', '--help', 1, "./")
+
+end

metadata

@@ -0,0 +1,47 @@
+--- !ruby/object:Gem::Specification
+name: docopt
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Vladimir Keleshev
+- Alex Speller
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-06-03 00:00:00.000000000 Z
+dependencies: []
+description: A command line option parser, that will make you smile.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- docopt.rb
+homepage: http://github.com/alexspeller/docopt.rb
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A command line option parser, that will make you smile.
+test_files: []