docopt 0.0.4 → 0.5.0

data/docopt.gemspec

@@ -0,0 +1,83 @@
+## This is the rakegem gemspec template. Make sure you read and understand
+## all of the comments. Some sections require modification, and others can
+## be deleted if you don't need them. Once you understand the contents of
+## this file, feel free to delete any comments that begin with two hash marks.
+## You can find comprehensive Gem::Specification documentation, at
+## http://docs.rubygems.org/read/chapter/20
+Gem::Specification.new do |s|
+  s.specification_version = 2 if s.respond_to? :specification_version=
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.rubygems_version = '1.3.5'
+  s.required_ruby_version = '>= 1.8.7'
+  ## Leave these as is they will be modified for you by the rake gemspec task.
+  ## If your rubyforge_project name is different, then edit it and comment out
+  ## the sub! line in the Rakefile
+  s.name              = 'docopt'
+  s.version           = '0.5.0'
+  s.date              = '2012-09-01'
+  # s.rubyforge_project = 'docopt'
+
+  ## Make sure your summary is short. The description may be as long
+  ## as you like.
+  s.summary = "A command line option parser, that will make you smile."
+  s.description = "Isn't it awesome how `optparse` and other option parsers generate help and usage-messages based on your code?! Hell no!\nYou 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! That's what docopt does!"
+
+  ## List the primary authors. If there are a bunch of authors, it's probably
+  ## better to set the email to an email list or something. If you don't have
+  ## a custom homepage, consider using your GitHub URL or the like.
+  s.authors = ["Blake Williams", "Vladimir Keleshev", "Alex Speller", "Nima Johari"]
+  s.email = "code@shabbyrobe.org"
+  s.homepage = "http://github.com/docopt/docopt.rb"
+  s.license = 'MIT'
+  ## This gets added to the $LOAD_PATH so that 'lib/NAME.rb' can be required as
+  ## require 'NAME.rb' or'/lib/NAME/file.rb' can be as require 'NAME/file.rb'
+  s.require_paths = %w[lib]
+
+  ## This sections is only necessary if you have C extensions.
+  # s.require_paths << 'ext'
+  # s.extensions = %w[ext/extconf.rb]
+
+  ## If your gem includes any executables, list them here.
+  # s.executables = ["name"]
+
+  ## Specify any RDoc options here. You'll want to add your README and
+  ## LICENSE files to the extra_rdoc_files list.
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.extra_rdoc_files = %w[README.md LICENSE]
+
+  ## List your runtime dependencies here. Runtime dependencies are those
+  ## that are needed for an end user to actually USE your code.
+  # s.add_dependency('DEPNAME', [">= 1.1.0", "< 2.0.0"])
+
+  ## List your development dependencies here. Development dependencies are
+  ## those that are only needed during development
+  s.add_development_dependency('json', "~> 1.6.5")
+
+  ## Leave this section as-is. It will be automatically generated from the
+  ## contents of your Git repository via the gemspec task. DO NOT REMOVE
+  ## THE MANIFEST COMMENTS, they are used as delimiters by the task.
+  # = MANIFEST =
+  s.files = %w[
+    Gemfile
+    LICENSE
+    README.md
+    Rakefile
+    docopt.gemspec
+    examples/any_options_example.rb
+    examples/calculator.rb
+    examples/counted_example.rb
+    examples/example_options.rb
+    examples/git_example.rb
+    examples/naval_fate.rb
+    examples/odd_even_example.rb
+    examples/quick_example.rb
+    lib/docopt.rb
+    test/test_docopt.rb
+    test/testee.rb
+  ]
+  # = MANIFEST =
+
+  ## Test files will be grabbed from the file list. Make sure the path glob
+  ## matches what you actually use.
+  s.test_files = s.files.select { |path| path =~ /^test\/test_.*\.rb/ }
+end

data/examples/any_options_example.rb

@@ -0,0 +1,24 @@
+require File.expand_path("../../lib/docopt.rb", __FILE__)
+
+doc = <<DOCOPT
+Example of program which uses [options] shortcut in pattern.
+
+Usage:
+  #{__FILE__} [options] <port>
+
+Options:
+  -h --help                show this help message and exit
+  --version                show version and exit
+  -n, --number N           use N as a number
+  -t, --timeout TIMEOUT    set timeout TIMEOUT seconds
+  --apply                  apply changes to database
+  -q                       operate in quiet mode
+
+DOCOPT
+
+
+begin
+  puts Docopt::docopt(doc, version: '1.0.0rc2').to_s
+rescue Docopt::Exit => e
+  puts e.message
+end

data/examples/calculator.rb

@@ -0,0 +1,16 @@
+require File.expand_path("../../lib/docopt.rb", __FILE__)
+
+doc = <<DOCOPT
+Usage:
+  #{__FILE__} tcp <host> <port> [--timeout=<seconds>]
+  #{__FILE__} serial <port> [--baud=9600] [--timeout=<seconds>]
+  #{__FILE__} -h | --help | --version
+
+DOCOPT
+
+begin
+  require "pp"
+  pp Docopt::docopt(doc)
+rescue Docopt::Exit => e
+  puts e.message
+end

data/examples/counted_example.rb

@@ -0,0 +1,22 @@
+require File.expand_path("../../lib/docopt.rb", __FILE__)
+
+doc = <<DOCOPT
+Usage: #{__FILE__} --help
+       #{__FILE__} -v...
+       #{__FILE__} go [go]
+       #{__FILE__} (--path=<path>)...
+       #{__FILE__} <file> <file>
+
+Try: #{__FILE__} -vvvvvvvvvv
+     #{__FILE__} go go
+     #{__FILE__} --path ./here --path ./there
+     #{__FILE__} this.txt that.txt
+
+DOCOPT
+
+begin
+  require "pp"
+  pp Docopt::docopt(doc)
+rescue Docopt::Exit => e
+  puts e.message
+end

data/examples/example_options.rb

@@ -0,0 +1,44 @@
+require File.expand_path("../../lib/docopt.rb", __FILE__)
+
+doc = <<DOCOPT
+Example of program with many options using docopt.
+
+Usage:
+  #{__FILE__} [-hvqrf NAME] [--exclude=PATTERNS]
+                     [--select=ERRORS | --ignore=ERRORS] [--show-source]
+                     [--statistics] [--count] [--benchmark] PATH...
+  #{__FILE__} (--doctest | --testsuite=DIR)
+  #{__FILE__} --version
+
+Arguments:
+  PATH  destination path
+
+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]
+  -f NAME --file=NAME  when parsing directories, only check filenames matching
+                       these comma separated patterns [default: *#{__FILE__}]
+  --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
+
+
+DOCOPT
+
+begin
+  require "pp"
+  pp Docopt::docopt(doc)
+rescue Docopt::Exit => e
+  puts e.message
+end

data/examples/git_example.rb

@@ -0,0 +1,44 @@
+require File.expand_path("../../lib/docopt.rb", __FILE__)
+
+doc = <<DOCOPT
+Usage:
+    #{__FILE__} remote [-v | --verbose]
+    #{__FILE__} remote add [-t <branch>] [-m <master>] [-f]
+                   [--tags|--no-tags] [--mirror] <name> <url>
+    #{__FILE__} remote rename <old> <new>
+    #{__FILE__} remote rm <name>
+    #{__FILE__} remote set-head <name> (-a | -d | <branch>)
+    #{__FILE__} remote set-branches <name> [--add] <branch>...
+    #{__FILE__} remote set-url [--push] <name> <newurl> [<oldurl>]
+    #{__FILE__} remote set-url --add [--push] <name> <newurl>
+    #{__FILE__} remote set-url --delete [--push] <name> <url>
+    #{__FILE__} remote [-v | --verbose] show [-n] <name>
+    #{__FILE__} remote prune [-n | --dry-run] <name>
+    #{__FILE__} remote [-v | --verbose] update [-p | --prune]
+                   [(<group> | <remote>)...]
+
+Options:
+    -v, --verbose
+    -t <branch>
+    -m <master>
+    -f
+    --tags
+    --no-tags
+    --mittor
+    -a
+    -d
+    -n, --dry-run
+    -p, --prune
+    --add
+    --delete
+    --push
+    --mirror
+
+DOCOPT
+
+begin
+  require "pp"
+  pp Docopt::docopt(doc)
+rescue Docopt::Exit => e
+  puts e.message
+end

data/examples/naval_fate.rb

@@ -0,0 +1,30 @@
+require File.expand_path("../../lib/docopt.rb", __FILE__)
+
+#The *popular* naval fate example
+
+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 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

data/examples/odd_even_example.rb

@@ -0,0 +1,19 @@
+require File.expand_path("../../lib/docopt.rb", __FILE__)
+
+doc = <<DOCOPT
+Usage: #{__FILE__} [-h | --help] (ODD EVEN)...
+
+Example, try:
+  #{__FILE__} 1 2 3 4
+
+Options:
+  -h, --help
+
+DOCOPT
+
+begin
+  require "pp"
+  pp Docopt::docopt(doc)
+rescue Docopt::Exit => e
+  puts e.message
+end

data/examples/quick_example.rb

@@ -0,0 +1,16 @@
+require File.expand_path("../../lib/docopt.rb", __FILE__)
+
+doc = <<DOCOPT
+Usage:
+  #{__FILE__} tcp <host> <port> [--timeout=<seconds>]
+  #{__FILE__} serial <port> [--baud=9600] [--timeout=<seconds>]
+  #{__FILE__} -h | --help | --version
+
+DOCOPT
+
+begin
+  require "pp"
+  pp Docopt::docopt(doc)
+rescue Docopt::Exit => e
+  puts e.message
+end

data/lib/docopt.rb

@@ -1,112 +1,663 @@
-require 'getoptlong'
-
-class Docopt
-  attr_reader :docopts
-  
-  class UnknownOptionError < StandardError; end
-  
-  class Option
-    attr_reader :short, :long, :argcount, :value
-    
-    def initialize parse
-      @argcount                = 0
-      options, _, description = parse.strip.partition('  ')
-      options                 = options.sub(',', ' ').sub('=', ' ')
+module Docopt
+  VERSION = '0.5.0'
+end
+module Docopt
+  class DocoptLanguageError < SyntaxError
+  end
 
-      for s in options.split
-        if s.start_with? '--'
-          @long = s
-        elsif s.start_with? '-'
-          @short = s
+  class Exit < RuntimeError
+    def self.usage
+      @@usage
+    end
+
+    def self.set_usage(usage)
+      @@usage = usage ? usage : ''
+    end
+
+    def message
+      @@message
+    end
+
+    def initialize(message='')
+      @@message = ((message && message != '' ? (message + "\n") : '') + @@usage)
+    end
+  end
+
+  class Pattern
+    attr_accessor :children
+
+    def ==(other)
+      return self.inspect == other.inspect
+    end
+
+    def to_str
+      return self.inspect
+    end
+
+    def dump
+      puts ::Docopt::dump_patterns(self)
+    end
+
+    def fix
+      fix_identities
+      fix_list_arguments
+      return self
+    end
+
+    def fix_identities(uniq=nil)
+      if not instance_variable_defined?(:@children)
+        return self
+      end
+      uniq ||= flat.uniq
+
+      @children.each_with_index do |c, i|
+        if not c.instance_variable_defined?(:@children)
+          if !uniq.include?(c)
+            raise RuntimeError
+          end
+          @children[i] = uniq[uniq.index(c)]
         else
-          @argcount = 1
+          c.fix_identities(uniq)
         end
       end
-      
-      if @argcount == 1
-        matched = description.scan(/\[default: (.*)\]/)[0]
-        @value = matched ? matched[0] : nil
+    end
+
+    def fix_list_arguments
+      either.children.map { |c| c.children }.each do |case_|
+        case_.select { |c| case_.count(c) > 1 }.each do |e|
+          if e.class == Argument or (e.class == Option and e.argcount > 0)
+            e.value = []
+          end
+          if e.class == Command or (e.class == Option and e.argcount == 0)
+            e.value = 0
+          end
+        end
       end
+
+      return self
     end
-    
-    def set_value val
-      if argcount.zero?
-        @value = true
-      else
-        @value = val
+
+    def either
+      ret = []
+      groups = [[self]]
+      while groups.count > 0
+        children = groups.shift
+        types = children.map { |c| c.class }
+
+        if types.include?(Either)
+          either = children.select { |c| c.class == Either }[0]
+          children.slice!(children.index(either))
+          for c in either.children
+            groups << [c] + children
+          end
+        elsif types.include?(Required)
+          required = children.select { |c| c.class == Required }[0]
+          children.slice!(children.index(required))
+          groups << required.children + children
+
+        elsif types.include?(Optional)
+          optional = children.select { |c| c.class == Optional }[0]
+          children.slice!(children.index(optional))
+          groups << optional.children + children
+
+        elsif types.include?(OneOrMore)
+          oneormore = children.select { |c| c.class == OneOrMore }[0]
+          children.slice!(children.index(oneormore))
+          groups << (oneormore.children * 2) + children
+
+        else
+          ret << children
+        end
       end
+
+      args = ret.map { |e| Required.new(*e) }
+      return Either.new(*args)
     end
-    
-    def synonyms
-      ([short, long] + symbols).compact
+  end
+
+
+  class ChildPattern < Pattern
+    attr_accessor :name, :value
+
+    def initialize(name, value=nil)
+      @name = name
+      @value = value
     end
-    
-    def symbols
-      [short, long].compact.map do |name|
-        name.gsub(/^-+/, '').to_sym
+
+    def inspect()
+      "#{self.class.name}(#{self.name}, #{self.value})"
+    end
+
+    def flat
+      [self]
+    end
+
+
+    def match(left, collected=nil)
+      collected ||= []
+      pos, match = self.single_match(left)
+      if match == nil
+        return [false, left, collected]
       end
+
+      left_ = left.dup
+      left_.slice!(pos)
+
+      same_name = collected.select { |a| a.name == self.name }
+      if @value.is_a? Array or @value.is_a? Integer
+        increment = @value.is_a?(Integer) ? 1 : [match.value]
+        if same_name.count == 0
+          match.value = increment
+          return [true, left_, collected + [match]]
+        end
+        same_name[0].value += increment
+        return [true, left_, collected]
+      end
+      return [true, left_, collected + [match]]
     end
+  end
 
-    def getopt
-      [long, short, argcount].compact
+  class ParentPattern < Pattern
+    attr_accessor :children
+
+    def initialize(*children)
+      @children = children
     end
 
     def inspect
-      "#<Docopt::Option short: #{short}, long: #{long}, argcount: #{argcount}, value: #{value}>"
+      childstr = self.children.map { |a| a.inspect }
+      return "#{self.class.name}(#{childstr.join(", ")})"
+    end
+
+    def flat
+      self.children.map { |c| c.flat }.flatten
     end
+  end
+
+  class Argument < ChildPattern
+
+    # def initialize(*args)
+    #   super(*args)
+    # end
+
+    def single_match(left)
+      left.each_with_index do |p, n|
+        if p.class == Argument
+          return [n, Argument.new(self.name, p.value)]
+        end
+      end
+      return [nil, nil]
+    end
+  end
+
 
-    def == other
-      self.inspect == other.inspect
+  class Command < Argument
+    def initialize(name, value=false)
+      @name = name
+      @value = value
+    end
+
+    def single_match(left)
+      left.each_with_index do |p, n|
+        if p.class == Argument
+          if p.value == self.name
+            return n, Command.new(self.name, true)
+          else
+            break
+          end
+        end
+      end
+      return [nil, nil]
     end
   end
-  
-  
-  def initialize(doc, version=nil, help=true)
-    @docopts = doc.split(/^ *-|\n *-/)[1..-1].map do |line|
-      Option.new('-' + line)
-    end
-    
-    GetoptLong.new(*docopts.map(&:getopt)).each do |opt, arg|
-      docopt_option = option(opt)
-      if help and (opt == '--help' or opt == '-h')
-        puts doc.strip
-        exit
-      elsif version and opt == '--version'
-        puts version
-        exit
+
+
+  class Option < ChildPattern
+    attr_reader :short, :long
+    attr_accessor :argcount
+
+    def initialize(short=nil, long=nil, argcount=0, value=false)
+      unless [0, 1].include? argcount
+        raise RuntimeError
+      end
+
+      @short, @long = short, long
+      @argcount, @value = argcount, value
+
+      if value == false and argcount > 0
+        @value = nil
       else
-        docopt_option.set_value arg
+        @value = value
+      end
+    end
+
+    def self.parse(option_description)
+      short, long, argcount, value = nil, nil, 0, false
+      options, _, description = option_description.strip.partition('  ')
+
+      options.gsub!(",", " ")
+      options.gsub!("=", " ")
+
+      for s in options.split
+        if s.start_with?('--')
+          long = s
+        elsif s.start_with?('-')
+          short = s
+        else
+          argcount = 1
+        end
       end
+      if argcount > 0
+        matched = description.scan(/\[default: (.*)\]/i)
+        value = matched[0][0] if matched.count > 0
+      end
+      ret = self.new(short, long, argcount, value)
+      return ret
+    end
+
+    def single_match(left)
+      left.each_with_index do |p, n|
+        if self.name == p.name
+          return [n, p]
+        end
+      end
+      return [nil, nil]
+    end
+
+    def name
+      return self.long ? self.long : self.short
+    end
+
+    def inspect
+      return "Option(#{self.short}, #{self.long}, #{self.argcount}, #{self.value})"
     end
   end
-  
-  def option name
-    option = @docopts.detect do |docopt|
-      docopt.synonyms.include?(name)
+
+  class Required < ParentPattern
+    def match(left, collected=nil)
+      collected ||= []
+      l = left
+      c = collected
+
+      for p in self.children
+        matched, l, c = p.match(l, c)
+        if not matched
+          return [false, left, collected]
+        end
+      end
+      return [true, l, c]
     end
-    raise UnknownOptionError.new("#{name} option not found") unless option
-    option
   end
 
+  class Optional < ParentPattern
+    def match(left, collected=nil)
+      collected ||= []
+      for p in self.children
+        m, left, collected = p.match(left, collected)
+      end
+      return [true, left, collected]
+    end
+  end
 
-  
-  def value name
-    option(name).value
+  class OneOrMore < ParentPattern
+    def match(left, collected=nil)
+      if self.children.count != 1
+        raise RuntimeError
+      end
+
+      collected ||= []
+      l = left
+      c = collected
+      l_ = nil
+      matched = true
+      times = 0
+      while matched
+        # could it be that something didn't match but changed l or c?
+        matched, l, c = self.children[0].match(l, c)
+        times += (matched ? 1 : 0)
+        if l_ == l
+          break
+        end
+        l_ = l
+      end
+      if times >= 1
+        return [true, l, c]
+      end
+      return [false, left, collected]
+    end
   end
-  alias_method :[], :value
-    
-  def size
-    @docopts.size
+
+  class Either < ParentPattern
+    def match(left, collected=nil)
+      collected ||= []
+      outcomes = []
+      for p in self.children
+        matched, _, _ = outcome = p.match(left, collected)
+        if matched
+          outcomes << outcome
+        end
+      end
+
+      if outcomes.count > 0
+        ret = outcomes.min_by do |outcome|
+          outcome[1] == nil ? 0 : outcome[1].count
+        end
+        return ret
+      end
+      return [false, left, collected]
+    end
   end
-  
-  def inspect
-    @docopts.map do |option|
-      "#{option.short} #{option.long}=#{option.value.inspect}".strip
-    end.join("\n")
+
+  class TokenStream < Array
+    attr_reader :error
+
+    def initialize(source, error)
+      if !source
+        source = []
+      elsif source.class != ::Array
+        source = source.split
+      end
+      super(source)
+      @error = error
+    end
+
+    def move
+      return self.shift
+    end
+
+    def current
+      return self[0]
+    end
   end
-end
 
-# Convenience method for Docopt.parse
-def Docopt *args
-  Docopt.new *args
-end
+  class << self
+    def parse_long(tokens, options)
+      raw, eq, value = tokens.move().partition('=')
+      value = (eq == value and eq == '') ? nil : value
+
+      opt = options.select { |o| o.long and o.long == raw }
+
+      if tokens.error == Exit and opt == []
+        opt = options.select { |o| o.long and o.long.start_with?(raw) }
+      end
+
+      if opt.count < 1
+        if tokens.error == Exit
+          raise tokens.error, "#{raw} is not recognized"
+        else
+          o = Option.new(nil, raw, eq == '=' ? 1 : 0)
+          options << o
+          return [o]
+        end
+      end
+      if opt.count > 1
+        ostr = opt.map { |o| o.long }.join(', ')
+        raise tokens.error, "#{raw} is not a unique prefix: #{ostr}?"
+      end
+      o = opt[0]
+      opt = Option.new(o.short, o.long, o.argcount, o.value)
+      if opt.argcount == 1
+        if value == nil
+          if tokens.current() == nil
+            raise tokens.error, "#{opt.name} requires argument"
+          end
+          value = tokens.move()
+        end
+      elsif value != nil
+        raise tokens.error, "#{opt.name} must not have an argument"
+      end
+
+      if tokens.error == Exit
+        opt.value = value ? value : true
+      else
+        opt.value = value ? nil : false
+      end
+      return [opt]
+    end
+
+    def parse_shorts(tokens, options)
+      raw = tokens.move()[1..-1]
+      parsed = []
+      while raw != ''
+        first = raw.slice(0, 1)
+        opt = options.select { |o| o.short and o.short.sub(/^-+/, '').start_with?(first) }
+
+        if opt.count > 1
+          raise tokens.error, "-#{first} is specified ambiguously #{opt.count} times"
+        end
+
+        if opt.count < 1
+          if tokens.error == Exit
+            raise tokens.error, "-#{first} is not recognized"
+          else
+            o = Option.new('-' + first, nil)
+            options << o
+            parsed << o
+            raw = raw[1..-1]
+            next
+          end
+        end
+
+        o = opt[0]
+        opt = Option.new(o.short, o.long, o.argcount, o.value)
+        raw = raw[1..-1]
+        if opt.argcount == 0
+          value = tokens.error == Exit ? true : false
+        else
+          if raw == ''
+            if tokens.current() == nil
+              raise tokens.error, "-#{opt.short.slice(0, 1)} requires argument"
+            end
+            raw = tokens.move()
+          end
+          value, raw = raw, ''
+        end
+
+        if tokens.error == Exit
+          opt.value = value
+        else
+          opt.value = value ? nil : false
+        end
+        parsed << opt
+      end
+      return parsed
+    end
+
+
+    def parse_pattern(source, options)
+      tokens = TokenStream.new(source.gsub(/([\[\]\(\)\|]|\.\.\.)/, ' \1 '), DocoptLanguageError)
+
+      result = parse_expr(tokens, options)
+      if tokens.current() != nil
+        raise tokens.error, "unexpected ending: #{tokens.join(" ")}"
+      end
+      return Required.new(*result)
+    end
+
+
+    def parse_expr(tokens, options)
+      seq = parse_seq(tokens, options)
+      if tokens.current() != '|'
+        return seq
+      end
+      result = seq.count > 1 ? [Required.new(*seq)] : seq
+
+      while tokens.current() == '|'
+        tokens.move()
+        seq = parse_seq(tokens, options)
+        result += seq.count > 1 ? [Required.new(*seq)] : seq
+      end
+      return result.count > 1 ? [Either.new(*result)] : result
+    end
+
+    def parse_seq(tokens, options)
+      result = []
+      stop = [nil, ']', ')', '|']
+      while !stop.include?(tokens.current)
+        atom = parse_atom(tokens, options)
+        if tokens.current() == '...'
+          atom = [OneOrMore.new(*atom)]
+          tokens.move()
+        end
+        result += atom
+      end
+      return result
+    end
+
+    def parse_atom(tokens, options)
+      token = tokens.current()
+      result = []
+
+      if ['(' , '['].include? token
+        tokens.move()
+        if token == '('
+          matching = ')'
+          pattern = Required
+        else
+          matching = ']'
+          pattern = Optional
+        end
+        result = pattern.new(*parse_expr(tokens, options))
+        if tokens.move() != matching
+          raise tokens.error, "unmatched '#{token}'"
+        end
+        return [result]
+      elsif token == 'options'
+        tokens.move()
+        return options
+      elsif token.start_with?('--') and token != '--'
+        return parse_long(tokens, options)
+      elsif token.start_with?('-') and not ['-', '--'].include? token
+        return parse_shorts(tokens, options)
+
+      elsif token.start_with?('<') and token.end_with?('>') or token.upcase == token
+        return [Argument.new(tokens.move())]
+      else
+        return [Command.new(tokens.move())]
+      end
+    end
+
+    def parse_argv(source, options)
+      tokens = TokenStream.new(source, Exit)
+      parsed = []
+      while tokens.current() != nil
+        if tokens.current() == '--'
+          return parsed + tokens.map { |v| Argument.new(nil, v) }
+        elsif tokens.current().start_with?('--')
+          parsed += parse_long(tokens, options)
+        elsif tokens.current().start_with?('-') and tokens.current() != '-'
+          parsed += parse_shorts(tokens, options)
+        else
+          parsed << Argument.new(nil, tokens.move())
+        end
+      end
+      return parsed
+    end
+
+    def parse_doc_options(doc)
+      return doc.split(/^ *-|\n *-/)[1..-1].map { |s| Option.parse('-' + s) }
+    end
+
+    def printable_usage(doc)
+      usage_split = doc.split(/([Uu][Ss][Aa][Gg][Ee]:)/)
+      if usage_split.count < 3
+        raise DocoptLanguageError, '"usage:" (case-insensitive) not found.'
+      end
+      if usage_split.count > 3
+        raise DocoptLanguageError, 'More than one "usage:" (case-insensitive).'
+      end
+      return usage_split[1..-1].join().split(/\n\s*\n/)[0].strip
+    end
+
+    def formal_usage(printable_usage)
+      pu = printable_usage.split()[1..-1]  # split and drop "usage:"
+
+      ret = []
+      for s in pu[1..-1]
+        if s == pu[0]
+          ret << ') | ('
+        else
+          ret << s
+        end
+      end
+
+      return '( ' + ret.join(' ') + ' )'
+    end
+
+    def dump_patterns(pattern, indent=0)
+      ws = " " * 4 * indent
+      out = ""
+      if pattern.class == Array
+        if pattern.count > 0
+          out << ws << "[\n"
+          for p in pattern
+            out << dump_patterns(p, indent+1).rstrip << "\n"
+          end
+          out << ws << "]\n"
+        else
+          out << ws << "[]\n"
+        end
+
+      elsif pattern.class.ancestors.include?(ParentPattern)
+        out << ws << pattern.class.name << "(\n"
+        for p in pattern.children
+          out << dump_patterns(p, indent+1).rstrip << "\n"
+        end
+        out << ws << ")\n"
+
+      else
+        out << ws << pattern.inspect
+      end
+      return out
+    end
+
+    def extras(help, version, options, doc)
+      ofound = false
+      vfound = false
+      for o in options
+        if o.value and (o.name == '-h' or o.name == '--help')
+          ofound = true
+        end
+        if o.value and (o.name == '--version')
+          vfound = true
+        end
+      end
+
+      if help and ofound
+        Exit.set_usage(nil)
+        raise Exit, doc.strip
+      end
+      if version and vfound
+        Exit.set_usage(nil)
+        raise Exit, version
+      end
+    end
+
+    def docopt(doc, params={})
+      default = {:version => nil, :argv => nil, :help => true}
+      params = default.merge(params)
+      params[:argv] = ARGV if !params[:argv]
+
+      Exit.set_usage(printable_usage(doc))
+      options = parse_doc_options(doc)
+      pattern = parse_pattern(formal_usage(Exit.usage), options)
+      argv = parse_argv(params[:argv], options)
+      extras(params[:help], params[:version], argv, doc)
+
+      matched, left, collected = pattern.fix().match(argv)
+      collected ||= []
+
+      if matched and (!left or left.count == 0)
+        ret = {}
+        for a in pattern.flat + options + collected
+          name = a.name
+          if name and name != ''
+            ret[name] = a.value
+          end
+        end
+        return ret
+      end
+      raise Exit
+    end
+  end
+end