clive 0.8.1 → 1.0.0

data/lib/clive/arguments/parser.rb

@@ -0,0 +1,210 @@
+class Clive
+  class Arguments
+    class Parser
+
+      # Raised when the argument string passed to {Option} is wrong.
+      class InvalidArgumentStringError < Error
+        reason 'Invalid argument string format: #1'
+      end
+
+      # Valid key names for creating arguments passed to Option#initialize and
+      # standard names to map them to.
+      KEYS = {
+        :arg        => [:args],
+        :type       => [:types, :kind, :as],
+        :match      => [:matches],
+        :within     => [:withins, :in],
+        :default    => [:defaults],
+        :constraint => [:constraints]
+      }.inject({}) {|hsh, (k,v)|
+        (v + [k]).each {|key|
+          hsh[key] = k
+        }
+        hsh
+      }
+
+      # @param opts [Hash]
+      def initialize(opts)
+        @opts = normalise_key_names(opts, KEYS) || {}
+      end
+
+      # This turns the arguments string and other options into a nicely formatted
+      # hash.
+      #
+      # @return [Array<Hash>]
+      def to_a
+        multiple = to_arrays(@opts.dup)
+        args = split_into_hashes(multiple)
+
+        if @opts.has_key?(:arg)
+          # Parse the argument string and merge in previous options from +singles+.
+          args = parse_args_string(args, @opts[:arg])
+        end
+
+        infer_args(args)
+      end
+
+      # @return [Array<Argument>]
+      def to_args
+        to_a.map do |arg|
+          Argument.new(arg.delete(:name) || 'arg', arg)
+        end
+      end
+
+      private
+
+      # Infer arguments that haven't been explicitly defined by name. This allows you
+      # to just say "it" should be within the range +1..5+ and have an argument
+      # created without having to pass +:arg => '<choice>'+.
+      def infer_args(opts)
+        opts.map do |hash|
+          if hash.has_key?(:name)
+            hash
+          else
+            check = [:type, :match, :constraint, :within, :default]
+            if check.any? {|key| hash.has_key?(key) }
+              hash.merge! :name => 'arg'
+            end
+
+            if hash.has_key?(:default) && !hash.has_key?(:optional)
+              hash.merge! :optional => true
+            end
+
+            hash
+          end
+        end
+      end
+
+      # @param opts [Hash] Hash to rename keys in
+      # @param keys [Hash] Map of key names to desired key names
+      #
+      # @example
+      #
+      #   normalise_key_names({:a => 1, :b => 2}, {:a => :b, :b => :c})
+      #   #=> {:b => 1, :c => 2}
+      #
+      def normalise_key_names(opts, keys)
+        opts.inject({}) do |hsh, (k,v)|
+          hsh[keys[k]] = v if keys.has_key?(k)
+          hsh
+        end
+      end
+
+      # Adds enough of +pd+ to +obj+ to make it have #size of +max+.
+      #
+      # @param obj [#size]
+      # @param max [Integer]
+      # @param pd  [Object]
+      # @return [Object]
+      def pad(obj, max, pd=nil)
+        i = (max - obj.size)
+        obj + [pd] * (i < 0 ? 0 : i)
+      end
+
+      # @param name [String]
+      # @return [String] Argument name without sqaure or angle brackets
+      def clean(name)
+        name.tr '[<>]', ''
+      end
+
+      # @param hash [Hash<Symbol=>Object, Symbol=>Array>]
+      # @return [Hash<Symbol=>Array>]
+      def to_arrays(hash)
+        # :within is weird. You will generally set it to an Array, but can use
+        # anything which responds to #include?. Unfortunately that includes String
+        # which for many reasons should be checked against. So new rules...
+        #
+        # hash[:within] = <#include?>
+        # #=> hash[:within] = [<#include?>]
+        #
+        # hash[:within] = [<#include?>]
+        # #=> hash[:within] = [<#include?>]
+        #
+        # hash[:within] = '1'..'5'
+        # #=> hash[:within] = ['1'..'5']
+        #
+        # hash[:type] = Integer
+        # hash[:within] = 1..5
+        # #=> hash[:within] = [1..5]
+        #
+        # hash[:type] = Integer
+        # hash[:within] = [1..5, nil]
+        # #=> hash[:within] = [1..5, nil]
+        #
+        if hash[:within].respond_to?(:[]) && hash[:within].respond_to?(:include?)
+          if hash[:within].all? {|o|
+              ([String] << hash[:type]).flatten.uniq.compact.any? {|t|
+                o.is_a?(t)
+              }
+            }
+            hash[:within] = [hash[:within]].compact
+
+          elsif hash[:within].any? {|o| o.respond_to?(:include?) }
+            hash[:within] = hash[:within]
+
+          else
+            hash[:within] = [hash[:within]].compact
+          end
+        else
+          hash[:within] = [hash[:within]].compact
+        end
+
+        # Make all the values Arrays
+        Hash[ hash.map {|k,v| [k, Array(v)] } ]
+      end
+
+      # Splits a single hash of arrays into a single array of hashes.
+      #
+      # @example
+      #
+      #    hash = {:a => [:g, :h, :i], :b => [:x, :y]}
+      #    split_into_hashes(hash)
+      #    #=> [
+      #    #  {:a => :b, :b => :x},
+      #    #  {:a => :h, :b => :y},
+      #    #  {:a => :i}
+      #    # ]
+      #
+      def split_into_hashes(hash)
+        # Find the largest Array...
+        max = hash.values.map(&:size).max || 0
+
+        hash.map {|k, arr| pad(arr, max).map {|i| [k, i] } }.
+          transpose.
+          map {|i| Hash[ i.reject {|a,b| b == nil || a == :arg } ] }
+      end
+
+      # Parses the string passed in as +:arg+. The string should have the
+      # following format:
+      #
+      #   <arg-name> - Indicates a required argument called "arg-name"
+      #   [...]      - Can surround one or more <arg> tokens and means they are
+      #                optional, eg. "[<optional> <and-another>]"
+      #
+      # @param hash [Hash<Symbol=>Object>]
+      # @param arg_str [String]
+      def parse_args_string(hash, arg_str)
+        optional = false
+        cancelled_optional = false
+
+        arg_str.split(' ').zip(hash).map do |arg, opts|
+          if cancelled_optional
+            optional = false
+            cancelled_optional = false
+          end
+
+          cancelled_optional = true if arg[-1..-1] == ']'
+
+          if arg[0..0] == '['
+            optional = true
+          elsif arg[0..0] != '<'
+            raise InvalidArgumentStringError.new(opts[:arg])
+          end
+
+          {:name => clean(arg), :optional => optional}.merge(opts || {})
+        end
+      end
+
+    end
+  end
+end

data/lib/clive/base.rb

@@ -0,0 +1,189 @@
+class Clive
+  class Base < Command
+
+    attr_reader :commands
+
+    DEFAULTS = {
+      :name         => File.basename($0),
+      :formatter    => Formatter::Colour.new,
+      :help_command => true,
+      :help         => true
+    }
+
+    # These options should be copied into each {Command} that is created.
+    GLOBAL_OPTIONS = [:name, :formatter, :help]
+
+    # You don't need to create an instance of this, create a class extending
+    # Clive or call Clive.new instead.
+    #
+    # @param config [Hash] Options to set for this Base, see #run for details
+    #  of the keys that can be passed.
+    def initialize(config={}, &block)
+      super([], config, &block)
+
+      @commands = []
+      @header   = proc { "Usage: #{@config[:name]} [command] [options]" }
+      @footer   = ""
+      @_group   = nil
+      @config   = DEFAULTS.merge(get_subhash(config, DEFAULTS.keys))
+
+      # Need to keep a state before #run is called so #set works.
+      @state = {}
+      instance_exec &block if block
+    end
+
+    # Runs the Clive with the args passed which defaults to +ARGV+.
+    #
+    # @param args [Array<String>]
+    #   Command line arguments to run with
+    #
+    # @param config [Hash]
+    # @option config [Boolean] :help
+    #   Whether to create a help option.
+    # @option config [Boolean] :help_command
+    #   Whether to create a help command.
+    # @option config [Formatter] :formatter
+    #   Help formatter to use.
+    # @option config [String] :name
+    #   Name to use in headers, this is usually better than setting a header as
+    #   commands will use this to generate their own headers for use in help.
+    #
+    def run(args=ARGV, config={})
+      @config = @config.merge(get_subhash(config, DEFAULTS.keys))
+
+      add_help_option
+      add_help_command
+
+      Clive::Parser.new(self, config).parse(args, @state)
+    end
+
+
+    # @group DSL Methods
+
+    # @overload command(*names, description=current_desc, opts={}, &block)
+    #   Creates a new Command.  @param names [Array<Symbol>] Names that the
+    #   command can be called with.  @param description [String] Description of
+    #   the command.  @param opts [Hash] Options to be passed to the new
+    #   Command, see {Command#initialize}.
+    #
+    # @example
+    #
+    #   class CLI
+    #     desc 'Creates a new thing'
+    #     command :create, arg: '<thing>' do
+    #       # ...
+    #     end
+    #   end
+    #
+    def command(*args, &block)
+      ns, d, o = [], current_desc, {}
+      args.each do |i|
+        case i
+          when ::Symbol then ns << i
+          when ::String then d = i
+          when ::Hash   then o = i
+        end
+      end
+      o = DEFAULTS.merge(Hash[global_opts]).merge(o)
+      @commands << Command.new(ns, d, o.merge({:group => @_group}), &block)
+    end
+
+    include Clive::StateActions
+
+    # Set configuration values for the base, as if you passed an options hash
+    # to #initialize.
+    #
+    # @param [Hash] See #initialize
+    # @example
+    #
+    #   config arg: '<dir>'
+    #
+    def config(opts=nil)
+      if opts
+        @config = @config.merge(get_subhash(opts, DEFAULTS.keys))
+      else
+        @config
+      end
+    end
+
+    # @endgroup
+
+    # Finds the option or command represented by +arg+, this can the name of a command
+    # or an option which should include the correct number of dashes. If the option or
+    # command cannot be found +nil+ is returned.
+    #
+    # @param arg [String]
+    # @see Command#find
+    # @example
+    #
+    #   c = Clive.new {
+    #     command :new
+    #     opt :v, :version
+    #   }
+    #
+    #   c.find('-v')
+    #   #=> #<Clive::Option -v, --version>
+    #   c.find('new')
+    #   #=> #<Clive::Command new>
+    #   c.find('test')
+    #   #=> nil
+    #
+    def find(arg)
+      if arg[0..0] == '-'
+        super
+      else
+        find_command(arg.to_sym)
+      end
+    end
+
+    # Finds the command with the name given, if the command cannot be found
+    # returns +nil+.
+    #
+    # @param arg [Symbol, nil]
+    # @example
+    #
+    #   c = Clive.new {
+    #     command :new
+    #   }
+    #
+    #   c.find_command(:new)
+    #   #=> #<Clive::Command new>
+    #
+    def find_command(arg)
+      @commands.find {|i| i.names.include?(arg) }
+    end
+
+    # Attempts to find the command with the name given, returns true if the
+    # command exits.
+    #
+    # @param arg [Symbol]
+    # @example
+    #
+    #   c = Clive.new {
+    #     command :new
+    #   }
+    #
+    #   c.has_command? :new     #=> true
+    #   c.has_command? :create  #=> false
+    #
+    def has_command?(arg)
+      !!find_command(arg)
+    end
+
+    private
+
+    # Options which should be copied into each Command created.
+    def global_opts
+      @config.find_all {|k,v| GLOBAL_OPTIONS.include?(k) }
+    end
+
+    # Adds the help command, which accepts the name of a command to display help
+    # for, to this if it is wanted.
+    def add_help_command
+      if @config[:help] && @config[:help_command] && !has_command?(:help)
+        self.command(:help, 'Display help', :arg => '[<command>]', :tail => true)
+      end
+    end
+
+  end
+end

data/lib/clive/command.rb

@@ -1,510 +1,408 @@
-module Clive
-  
-  # A string which describes the command to execute
-  #   eg. git add
-  #       git pull
+class Clive
+
+  # A command allows you to separate groups of commands under their own
+  # namespace. But it can also take arguments like an Option. Instead of
+  # executing the block passed to it executes the block passed to {#action}.
+  #
+  # @example
+  #
+  #   class CLI < Clive
+  #
+  #     command :new, arg: '<dir>' do
+  #       # options
+  #       bool :force
+  #
+  #       action do |dir|
+  #         # code
+  #       end
+  #     end
+  #
+  #   end
   #
   class Command < Option
-    
-    attr_accessor :options, :commands
-    attr_accessor :argv, :base
-    attr_reader   :names, :current_desc
-    attr_reader   :top_klass
-    
-    # Create the base Command instance. Replacement for the #initialize
-    # overloading.
-    #
-    def self.setup(klass, &block)
-      new([], "", klass, &block)
-    end
-    
-    # Create a new Command instance
-    #
-    # @overload initialize(base, &block)
-    #   Creates a new base Command to house everything else
-    #   @param base [Boolean] whether the command is the base
-    #
-    # @overload initialize(names, desc, &block)
-    #   Creates a new Command as part of the base Command
-    #   @param names [Symbol] the name of the command
-    #   @param desc [String] the description of the command
-    #
-    # @yield A block to run, containing switches, flags and commands
-    #
-    def initialize(names, desc, top_klass, &block)
-      @argv      = []
-      @names     = names.map {|i| i.to_s }
-      @top_klass = top_klass
-      @desc      = desc
-      @commands  = []
-      @options   = []
-      @block     = block
-      @base      = false
-      
-      if @names == [] && @desc == ""
-        @base = true
-        self.instance_eval(&block) if block_given?
-      end
-      
-      @option_missing = Proc.new {|e| raise NoOptionError.new(e)}
-      
-      # Create basic header "Usage: filename [command] [options]
-      #                  or "Usage: filename commandname(s) [options]
-      @header = "Usage: #{File.basename($0, '.*')} " << 
-                (@base ? "[command]" : @names.join(', ')) << 
-                " [options]"
-                
-      @footer = nil
-      @current_desc = ""
-      help_formatter :default
-      
-      self.build_help
-    end
-    
-    # @return [Array] all bools in this command
-    def bools
-      @options.find_all {|i| i.class == Bool}
-    end
-    
-    # @return [Array] all switches in this command
-    def switches
-      @options.find_all {|i| i.class == Switch}
-    end
-    
-    # @return [Array] all flags in this command
-    def flags
-      @options.find_all {|i| i.class == Flag}
+
+    # @return [Array<Option>] List of options created in the Command instance
+    attr_reader :options
+
+    DEFAULTS = {
+      :group     => nil,
+      :head      => false,
+      :tail      => false,
+      :runner    => Clive::Option::Runner,
+
+      # these two are copied in from Base, so will be merged over
+      :formatter => nil,
+      :help      => nil,
+      :name      => nil
+    }
+
+    # @param names [Array[Symbol]]
+    #   Names that the Command can be ran with.
+    #
+    # @param desc [String]
+    #   Description of the Command, this is shown in help and will be wrapped properly.
+    #
+    # @param config [Hash]
+    # @option config [Boolean] :head
+    #   If option should be at top of help list.
+    # @option config [Boolean] :tail
+    #   If option should be at bottom of help list.
+    # @option config [String] :group
+    #   Name of the group this option belongs to. This is actually set when
+    #   {Command#group} is used.
+    # @option config [Runner] :runner
+    #   Class to use for running the block passed to #action. This doesn't have
+    #   to be Option::Runner, but you probably never need to change this.
+    # @option config [Formatter] :formatter
+    #   Help formatter to use for this command, defaults to top-level formatter.
+    # @option config [Boolean] :help
+    #   Whether to add a '-h, --help' option to this command which displays help.
+    # @option config [String] :args
+    #   Arguments that the option takes. See {Argument}.
+    # @option config [Type, Array[Type]] :as
+    #   The class the argument(s) should be cast to. See {Type}.
+    # @option config [#match, Array[#match]] :match
+    #   Regular expression that the argument(s) must match.
+    # @option config [#include?, Array[#include?]] :in
+    #   Collection that argument(s) must be in.
+    # @option config [Object] :default
+    #   Default value that is used if argument is not given.
+    #
+    def initialize(names=[], description="", config={}, &block)
+      @names       = names
+      @description = description
+      @options     = []
+      @_block      = block
+
+      @args = Arguments.create(get_subhash(config, Arguments::Parser::KEYS))
+      @config = DEFAULTS.merge(get_subhash(config, DEFAULTS.keys))
+
+      # Create basic header "Usage: filename commandname(s) [options]
+      @header = proc { "Usage: #{@config[:name]} #{to_s} [options]" }
+      @footer = ""
+      @_group = nil
+
+      add_help_option
+
+      current_desc
     end
-    
-    # Run the block that was passed to find switches, flags, etc.
-    #
-    # This should only be called if the command has been called
-    # as the block could contain other actions to perform only 
-    # when called.
-    #
-    def find
-      return nil if @base || @block.nil?
-      self.instance_eval(&@block)
-      @block = nil
+
+    # @return [Symbol] Single name to use when referring specifically to this command.
+    #  Use the first name that was passed in.
+    def name
+      names.first
     end
-    
-    # Gets the type of the option which corresponds with the name given
-    #
-    # @param name [String]
-    # @return [Constant]
-    #
-    def type_is?(name)
-      find_opt(name).class.name || Clive::Command
+
+    # @return [String]
+    def to_s
+      names.join(',')
     end
-    
-    def opt_type(name)
-      case find_opt(name).class.name
-      when "Clive::Switch"
-        :switch
-      when "Clive::Bool"
-        :switch
-      when "Clive::Flag"
-        :flag
-      when "Clive::Command"
-        :command
+
+    # Runs the block that was given to {Command#initialize} within the context of the
+    # command. The state hash is passed (and returned) so that {#set} works outside
+    # of {Runner} allowing default values to be set.
+    #
+    # @param state [Hash] The newly created state for the command.
+    # @return [Hash] The returned hash is used for the state of the command.
+    def run_block(state)
+      if @_block
+        @state = state
+        instance_exec(&@_block)
+        @state
       else
-        nil
+        @state = state
       end
     end
-    
-    # Finds the option which has the name given
+
+    # @group DSL Methods
+
+    # Set the header for {#help}.
+    # @param [String]
+    # @example
     #
-    # @param name [String]
-    # @return [Clive::Option]
+    #   header 'Usage: my_app [options] [args]'
     #
-    def find_opt(name)
-      options.find {|i| i.names.include?(name)}
+    def header(val)
+      @header = val
     end
-    
-    # Checks whether the string given is the name of a Command or not
+
+    # Set the footer for {#help}.
+    # @param [String]
+    # @example
     #
-    # @param str [String]
-    # @return [true, false]
+    #   footer 'For more help visit http://mysite.com/help'
     #
-    def is_a_command?(str)
-      find_command(str).empty?
+    def footer(val)
+      @footer = val
     end
-    
-    # Finds the command which has the name given
+
+    # Set configuration values for the command, as if you passed an options hash
+    # to #initialize.
     #
-    # @param name [String]
-    # @return [Clive::Command]
+    # @param [Hash] See #initialize
+    # @example
+    #
+    #   config arg: '<dir>'
     #
-    def find_command(str)
-      commands.find {|i| i.names.include?(str)}
+    def config(opts=nil)
+      if opts
+        @config = @config.merge(get_subhash(opts, DEFAULTS.keys))
+      else
+        @config
+      end
     end
-    
-    # Converts the array of input from the command line into a string of tokens.
-    # It replaces instances of the names of flags, switches and bools with the 
-    # actual option, but does not affect commands. Instead these are left as +words+.
+
+    include Clive::StateActions
+
+    # @overload option(short=nil, long=nil, description=current_desc, opts={}, &block)
+    #   Creates a new Option in the Command. Either +short+ or +long+ must be set.
+    #   @param short [Symbol] The short name for the option (:a would become +-a+)
+    #   @param long [Symbol] The long name for the option (:add would become +--add+)
+    #   @param description [String] Description of the option
+    #   @param opts [Hash] Options to create the Option with, see {Option#initialize}
     #
     # @example
     #
-    #   array_to_tokens ['--switch', 'command', '-f', 'arg']
-    #   #=> [[:option, "switch"], [:word, "command"], [:option, "f"], [:word, "arg"]]
-    #
-    # @param arr [Array]
-    # @return [Array]
-    #
-    def array_to_tokens(arr)
-      result = []
-      
-      arr.each do |a|
-        if a[0..1] == "--"
-          result << [:option, a[2..-1]]
-          
-        elsif a[0] == "-"
-          a[1..-1].split('').each do |i|
-            result << [:option, i]
-          end
-
-        else
-          result << [:word, a]
+    #   opt :type, arg: '<size>', in: %w(small medium large) do
+    #     case size
+    #       when "small"  then set(:size, 1)
+    #       when "medium" then set(:size, 2)
+    #       when "large"  then set(:size, 3)
+    #     end
+    #   end
+    #
+    def option(*args, &block)
+      ns, d, o = [], current_desc, {}
+      args.each do |i|
+        case i
+          when ::Symbol then ns << i
+          when ::String then d = i
+          when ::Hash   then o = i
         end
       end
-
-      result 
+      @options << Option.new(ns, d, ({:group => @_group}).merge(o), &block)
     end
-    
-    # Converts the set of tokens returned from #array_to_tokens into a tree.
-    # This is where we determine whether a +word+ is an argument or command. 
+    alias_method :opt, :option
+
+    # @overload boolean(short=nil, long, description=current_desc, opts={}, &block)
+    #   Creates a new Option in the Command which responds to calls with a 'no-' prefix.
+    #   +long+ must be set.
+    #   @param short [Symbol] The short name for the option (:a would become +-a+)
+    #   @param long [Symbol] The long name for the option (:add would become +--add+)
+    #   @param description [String] Description of the option
+    #   @param opts [Hash] Options to create the Option with, see {Option#initialize}
     #
     # @example
-    #   tokens_to_tree([[:option, "switch"], [:word, "command"], 
-    #                   [:option, "f"], [:word, "arg"]])
-    #   #=> [
-    #   #     [:switch, #<Clive::Switch [switch]>],
-    #   #     [:command, #<Clive::Command [command]>, [
-    #   #       [:flag, #<Clive::Flag [f, flag]>, [
-    #   #         [:arg, 'arg']
-    #   #       ]]
-    #   #     ]]
-    #   #   ]
-    #
-    # @param arr [Array]
-    # @return [Array]
-    #
-    def tokens_to_tree(arr)
-      tree = []
-      self.find
-      
-      l = arr.size
-      i = 0
-      while i < l
-        a = arr[i]
-        
-        if a[0] == :word
-          
-          last = tree.last || []
-          
-          if last[0] == :flag
-            last[2] ||= []
-          end
-          
-          if command = find_command(a[1])
-            if last[0] == :flag              
-              if last[2].size < last[1].arg_size(:mandatory)
-                last[2] << [:arg, a[1]]
-              else
-                tree << [:command, command, command.tokens_to_tree(arr[i+1..-1])]
-                i = l
-              end
-            else
-              tree << [:command, command, command.tokens_to_tree(arr[i+1..-1])]
-              i = l
-            end
-          else
-            if last[0] == :flag && last[2].size < last[1].arg_size(:all)
-              last[2] << [:arg, a[1]]
-            else
-              tree << [:arg, a[1]]
-            end  
-          end
-        else
-          tree << [opt_type(a[1]), find_opt(a[1])]
-        end
-
-        i += 1
-      end
-
-      tree
-    end
-    
-    # Traverses the tree created by #tokens_to_tree and runs the correct options.
-    # 
-    # @param tree [Array]
-    # @return [Array]
-    #   Any unused arguments.
-    #
-    def run_tree(tree)
-      i = 0
-      l = tree.size
-      r = []
-      
-      while i < l
-        curr = tree[i]
-        
-        case curr[0]
-        when :command
-          r << curr[1].run(curr[2])
-          
-        when :switch
-          curr[1].run
-          
-        when :flag
-          args = curr[2].map {|i| i[1] }
-          if args.size < curr[1].arg_size(:mandatory)
-            raise MissingArgument.new(curr[1].sort_name)
-          end
-          curr[1].run(args)
-          
-        when :arg
-          r << curr[1]
+    #
+    #   bool :auto, 'Auto regenerate on changes'
+    #
+    #   # Usage
+    #   #  --auto      sets :auto to true
+    #   #  --no-auto   sets :auto to false
+    #
+    def boolean(*args, &block)
+      ns, d, o = [], current_desc, {}
+      args.each do |i|
+        case i
+          when ::Symbol then ns << i
+          when ::String then d = i
+          when ::Hash   then o = i
         end
-        
-        i += 1
       end
-      r.flatten
+      @options << Option.new(ns, d, ({:group => @_group, :boolean => true}).merge(o), &block)
     end
-    
-    
-    # Parse the ARGV passed from the command line, and run
+    alias_method :bool, :boolean
+
+    # If an argument is given it will set the description to that, otherwise it will
+    # return the description for the command.
+    #
+    # @param arg [String]
+    # @example
     #
-    # @param [Array] argv the command line input, usually just +ARGV+
-    # @return [Array] any arguments that were present in the input but not used
+    #   description 'Displays the current version'
+    #   opt(:version) { puts $VERSION }
     #
-    def run(argv=[])
-      to_run = argv
-      if @base # if not base we will have been passed the parsed tree already
-        to_run = tokens_to_tree( array_to_tokens(argv) )
-      end
-      run_tree(to_run)
-    end
-    
-    
-    def to_h
-      {
-        'names' => @names,
-        'desc'  => @desc
-      }
-    end
-    
-    def method_missing(sym, *args, &block)
-      if @top_klass.respond_to?(sym)
-        @top_klass.send(sym, *args)
+    def description(arg=nil)
+      if arg
+        @_last_desc = arg
+      else
+        @description
       end
     end
-  
-    
-      
-  # @group DSL
-  
-    # Add a new command to +@commands+
-    #
-    # @overload command(name, ..., desc, &block)
-    #   Creates a new command
-    #   @param [Symbol] name the name(s) of the command, eg. +:add+ for +git add+
-    #   @param [String] desc description of the command
-    # 
-    # @yield A block to run when the command is called, can contain switches
-    #   and flags
-    #
-    def command(*args, &block)
-      @commands << Command.new(args, @current_desc, @top_klass, &block)
-      @current_desc = ""
-    end
-    
-    # Add a new switch to +@switches+
-    # @see Switch#initialize
-    def switch(*args, &block)
-      @options << Switch.new(args, @current_desc, &block)
-      @current_desc = ""
-    end
 
-    # Adds a new flag to +@flags+
-    # @see Flag#initialize
-    def flag(*args, &block)
-      names = []
-      arg = nil
-      args.each do |i|
-        if i.is_a? Symbol
-          names << i
-        else
-          if i[:arg]
-            arg = i[:arg]
-          else
-            arg = i[:args]
-          end
-        end
-      end
-      @options << Flag.new(names, @current_desc, arg, &block)
-      @current_desc = ""
-    end
-    
-    # Creates a boolean switch. This is done by adding two switches of
-    # Bool type to +@switches+, one is created normally the other has
-    # "no-" appended to the long name and has no short name.
-    #
-    # @see Bool#initialize
-    def bool(*args, &block)
-      @options << Bool.new(args, @current_desc, true, &block)
-      @options << Bool.new(args, @current_desc, false, &block)
-      @current_desc= ""
+    # Short version of {#description} which can only set.
+    #
+    # @param arg [String]
+    # @example
+    #
+    #   desc 'Displays the current version'
+    #   opt(:version) { puts $VERSION }
+    #
+    def desc(arg)
+      @_last_desc = arg
     end
-    
-    # Add a description for the next option in the class. Or acts as an 
-    # accessor for @desc.
+
+    # The action block is the block which will be executed with any arguments that
+    # are found for it. It sets +@block+ so that {Option#run} does not have to be redefined.
     #
     # @example
     #
-    #   class CLI
-    #     include Clive::Parser
+    #   command :create, arg: '<name>', 'Creates a new project' do
+    #     bool :bare, "Don't add boilerplate code to created files"
     #
-    #     desc 'Force build docs'
-    #     switch :force do
-    #       # code
+    #     action do |name|
+    #       if get(:bare)
+    #         # write some empty files
+    #       else
+    #         # create some files with stuff in
+    #       end
     #     end
     #   end
     #
-    def desc(str=nil)
-      if str
-        @current_desc = str
-      else
-        @desc
-      end
+    def action(&block)
+      @block = block
     end
-    
-    # Define a block to execute when the option to execute cannot be found.
+
+    # Set the group name for all options defined after it.
     #
+    # @param name [String]
     # @example
     #
-    #   class CLI
-    #     include Clive::Parser
+    #   group 'Files'
+    #   opt :move,   'Moves a file',   args: '<from> <to>'
+    #   opt :delete, 'Deletes a file', arg:  '<file>'
+    #   opt :create, 'Creates a file', arg:  '<name>'
     #
-    #     option_missing do |name|
-    #       puts "#{name} couldn't be found"
-    #     end
+    #   group 'Network'
+    #   opt :upload,   'Uploads everything'
+    #   opt :download, 'Downloads everyhting'
     #
-    def option_missing(&block)
-      @option_missing = block
-    end      
-    
-    # Set the header
-    def header(val)
-      @header = val
-    end
-    
-    # Set the footer
-    def footer(val)
-      @footer = val
-    end
-    
-  # @group Help
-    
-    # This actually creates a switch with "-h" and "--help" that controls
-    # the help on this command.
-    def build_help
-      @options << Switch.new([:h, :help], "Display help") do
-        puts self.help
-        exit 0
-      end
+    def group(name)
+      @_group = name
     end
 
-    # Generate the summary for help, show all flags and switches, but do not
-    # show the flags and switches within each command. Should also prepend the
-    # header and append the footer if set.
-    def help
-      @formatter.format(@header, @footer, @commands, @options)
+    # Sugar for +group(nil)+
+    def end_group
+      group nil
     end
-    
-    # This allows you to define how the output from #help looks.
+
+    # @endgroup
+
+    # Finds the option represented by +arg+, this can either be the long name +--opt+
+    # or the short name +-o+, if the option can't be found +nil+ is returned.
     #
-    # For this you have access to several tokens which are evaluated in an object
-    # with the correct values, this means you are able to use #join on arrays or
-    # prepend, etc. The variables (tokens) are:
+    # @param arg [String]
+    # @return [Option, nil]
+    # @example
     #
-    # * prepend - a string of spaces as specified when #help_formatter is called
-    # * names - an array of names for the option
-    # * spaces - a string of spaces to align the descriptions properly
-    # * desc - a string of the description for the option
+    #   a = Command.new [:command] do
+    #     bool :force
+    #   end
     #
-    # And for flags you have access to:
+    #   a.find('--force')
+    #   #=> #<Clive::Option --[no-]force>
     #
-    # * args - an array of arguments for the flag
-    # * options - an array of options to choose from
+    def find(arg)
+      if arg[0..1] == '--'
+        find_option(arg[2..-1].gsub('-', '_').to_sym)
+      elsif arg[0..0] == '-'
+        find_option(arg[1..-1].to_sym)
+      end
+    end
+    alias_method :[], :find
+
+    # Attempts to find the option represented by the string +arg+, returns true if
+    # it exists and false if not.
     #
+    # @param arg [String]
+    # @example
     #
-    # @overload help_formatter(args, &block)
-    #   Create a new help formatter to use.
-    #   @param args [Hash]
-    #   @option args [Integer] :width Width before flexible spaces
-    #   @option args [Integer] :prepend Width of spaces to prepend with
+    #   a = Command.new [:command] do
+    #     bool :force
+    #     bool :auto
+    #   end
     #
-    # @overload help_formatter(name)
-    #   Use an existing help formatter.
-    #   @param name [Symbol] name of the formatter (either +:default+ or +:white+)
+    #   a.has?('--force')    #=> true
+    #   a.has?('--auto')     #=> true
+    #   a.has?('--no-auto')  #=> false
+    #   a.has?('--not-real') #=> false
     #
+    def has?(arg)
+      !!find(arg)
+    end
+
+    # Finds the option with the name given by +arg+, this must be in Symbol form so
+    # does not have a dash before it. As with {#find} if the option does not exist +nil+
+    # will be returned.
     #
+    # @param arg [Symbol]
+    # @return [Option, nil]
     # @example
-    #   
-    #   CLI.help_formatter do |h|
-    #
-    #     h.switch  "{prepend}{names.join(', ')} {spaces}{desc.grey}"
-    #     h.bool    "{prepend}{names.join(', ')} {spaces}{desc.grey}"
-    #     h.flag    "{prepend}{names.join(', ')} {args.join(' ')} {spaces}{desc.grey}"
-    #     h.command "{prepend}{names.join(', ')} {spaces}{desc.grey}"
     #
+    #   a = Command.new [:command] do
+    #     bool :force
     #   end
-    #   
-    #   
-    def help_formatter(*args, &block)    
-      if block_given?
-        width   = 30
-        prepend = 4
-      
-        unless args.empty?
-          args[0].each do |k,v|
-            case k
-            when :width
-              width = v
-            when :prepend
-              prepend = v
-            end
-          end
-        end
-        
-        @formatter = Formatter.new(width, prepend)
-        block.call(@formatter)
-        @formatter
-      else
-        case args[0]
-        when :default
-          help_formatter(&HELP_FORMATTERS[:default])
-        when :white
-          help_formatter(&HELP_FORMATTERS[:white])
+    #
+    #   a.find_option(:force)
+    #   #=> #<Clive::Option --[no-]force>
+    #
+    def find_option(arg)
+      @options.find {|opt| opt.names.include?(arg) }
+    end
+
+    # Attempts to find the option with the Symbol name given, returns true if the option
+    # exists and false if not.
+    #
+    # @param arg [Symbol]
+    def has_option?(arg)
+      !!find_option(arg)
+    end
+
+    # @see Formatter
+    # @return [String] Help string for this command.
+    def help
+      f = @config[:formatter]
+
+      f.header   = @header.respond_to?(:call) ? @header.call : @header
+      f.footer   = @footer.respond_to?(:call) ? @footer.call : @footer
+      f.commands = @commands if @commands
+      f.options  = @options
+
+      f.to_s
+    end
+
+    private
+
+    # Sets a value in the state.
+    #
+    # @param state [#store, #[]]
+    # @param args [Array]
+    # @param scope [nil]
+    def set_state(state, args, scope=nil)
+      # scope will always be nil, so ignore it for Option compatibility
+      state[name].store :args, (@args.max <= 1 ? args[0] : args)
+      state
+    end
+
+    # Adds the '--help' option to the Command instance if it should be added.
+    def add_help_option
+      if @config[:help] && !(has_option?(:help) || has_option?(:h))
+        h = self # bind self so that it can be called in the block
+        self.option(:h, :help, "Display this help message", :tail => true) do
+          puts h.help
+          exit 0
         end
       end
     end
-    
-    HELP_FORMATTERS = {
-      :default => lambda do |h|
-        h.switch  "{prepend}{names.join(', ')}  {spaces}{desc.grey}"
-        h.bool    "{prepend}{names.join(', ')}  {spaces}{desc.grey}"
-        h.flag    "{prepend}{names.join(', ')} {args}  {spaces}{desc.grey} {options.blue.bold}"
-        h.command "{prepend}{names.join(', ')}  {spaces}{desc.grey}"
-      end,
-      :white => lambda do |h|
-        h.switch  "{prepend}{names.join(', ')}  {spaces}{desc}"
-        h.bool    "{prepend}{names.join(', ')}  {spaces}{desc}"
-        h.flag    "{prepend}{names.join(', ')} {args}  {spaces}{desc} {options.bold}"
-        h.command "{prepend}{names.join(', ')}  {spaces}{desc}"
-      end
-    }
-    
+
+    # @return [String]
+    #   Returns the last description to be set with {#description}, it then clears the
+    #   stored description so that it is not returned twice.
+    def current_desc
+      r = @_last_desc
+      @_last_desc = ""
+      r
+    end
+
   end
-end
+end