clive 0.2.3 → 0.3.0

data/README.md

@@ -39,7 +39,7 @@ As we've seen above switches are created using #switch. You can provide as littl
 Boolean switches allow you to accept arguments like `--no-verbose` and `--verbose`, and deal with both situations in the same block.
 
     c = Clive.new do
-      boolean(:v, :verbose) {|i| p i}
+      bool(:v, :verbose) {|i| p i}
     end
     c.parse(ARGV)
     
@@ -59,7 +59,7 @@ As you can see the true case can be triggered with the short or long form, the f
 Flags are like switches but also take an argument:
 
     c = Clive.new do
-      flag(:p, :print, "Print the argument") do |i|
+      flag(:p, :print, "ARG", "Print ARG") do |i|
         p i
       end
     end
@@ -75,6 +75,12 @@ Flags are like switches but also take an argument:
     #=> "short"
 
 The argument is then passed into the block. As you can see you can use short, long, equals, or no equals to call flags. As with switches you can call `flag(:p) {|i| ...}` which responds to `-p ...`, `flag(:print) {|i| ...}` which responds to `--print ...` or `--print=...`.
+Flags can have default values, for that situation put square brackets round the argument name.
+
+    flag(:p, :print, "[ARG]", "Print ARG or "hey" by default) do |i|
+      i ||= "hey"
+      p i
+    end
 
 ### Commands
 
@@ -120,9 +126,9 @@ Anything that isn't a command, switch or flag is taken as an argument. These are
     
     opts = {}
     c = Clive.new do
-      switch(:v, :verbose, "Run verbosely") {opts[:verbose] = true}
+      bool(:v, :verbose, "Run verbosely") {|i| opts[:verbose] = i}
       
-      command(:add, "Add a new project")) do
+      command(:add, "Add a new project") do
         opts[:add] = {}
         
         switch(:force, "Force overwrite") {opts[:add][:force] = true}
@@ -133,7 +139,7 @@ Anything that isn't a command, switch or flag is taken as an argument. These are
         
         command(:init, "Initialize the project after creating") do
           switch(:m, :minimum, "Use minimum settings") {opts[:add][:min] = true}
-          flag(:width) {|i| opts[:add][:width] = i.to_i}
+          flag(:w, :width) {|i| opts[:add][:width] = i.to_i}
         end
       
       end

data/VERSION

@@ -1 +1 @@
-0.2.3
+0.3.0

data/clive.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{clive}
-  s.version = "0.2.3"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Joshua Hawxwell"]
-  s.date = %q{2010-08-17}
+  s.date = %q{2010-08-21}
   s.description = %q{Clive is a DSL for creating a command line interface. It is for people who, like me, love OptionParser's syntax and love GLI's commands.}
   s.email = %q{m@hawx.me}
   s.extra_rdoc_files = [
@@ -25,16 +25,19 @@ Gem::Specification.new do |s|
      "VERSION",
      "clive.gemspec",
      "lib/clive.rb",
-     "lib/clive/booleans.rb",
-     "lib/clive/commands.rb",
+     "lib/clive/bool.rb",
+     "lib/clive/command.rb",
+     "lib/clive/exceptions.rb",
      "lib/clive/ext.rb",
-     "lib/clive/flags.rb",
-     "lib/clive/switches.rb",
+     "lib/clive/flag.rb",
+     "lib/clive/option.rb",
+     "lib/clive/switch.rb",
      "lib/clive/tokens.rb",
      "test/bin_test",
      "test/helper.rb",
      "test/test_boolean.rb",
      "test/test_clive.rb",
+     "test/test_command.rb",
      "test/test_exceptions.rb",
      "test/test_flag.rb",
      "test/test_switch.rb",
@@ -49,6 +52,7 @@ Gem::Specification.new do |s|
     "test/helper.rb",
      "test/test_boolean.rb",
      "test/test_clive.rb",
+     "test/test_command.rb",
      "test/test_exceptions.rb",
      "test/test_flag.rb",
      "test/test_switch.rb",

data/lib/clive.rb

@@ -1,11 +1,14 @@
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 
+require 'clive/exceptions'
 require 'clive/tokens'
 require 'clive/ext'
-require 'clive/switches'
-require 'clive/flags'
-require 'clive/commands'
-require 'clive/booleans'
+
+require 'clive/option'
+require 'clive/command'
+require 'clive/switch'
+require 'clive/flag'
+require 'clive/bool'
 
 # Clive is a simple dsl for creating command line interfaces
 #
@@ -21,49 +24,6 @@ require 'clive/booleans'
 #
 class Clive
 
-  # general problem with input
-  class ParseError < StandardError
-    attr_accessor :args, :reason
-    
-    def initialize(*args)
-      @args = args
-      @reason = "parse error"
-    end
-    
-    def self.filter_backtrace(array)
-      unless $DEBUG
-        array = [$0]
-      end
-      array
-    end
-    
-    def set_backtrace(array)
-      super(self.class.filter_backtrace(array))
-    end
-    
-    def message
-      @reason + ': ' + args.join(' ')
-    end
-    alias_method :to_s, :message
-  
-  end
-  
-  # a flag has a missing argument
-  class MissingArgument < ParseError
-    def initialize(*args)
-      @args = args
-      @reason = "missing argument"
-    end
-  end
-  
-  # a option that wasn't defined has been found
-  class InvalidOption < ParseError
-    def initialize(*args)
-      @args = args
-      @reason = "invalid option"
-    end
-  end
-
   attr_accessor :base
   
   def initialize(&block)
@@ -86,9 +46,8 @@ class Clive
     @base.flags
   end
   
-  def booleans
-    @base.booleans
+  def bools
+    @base.bools
   end
   
 end
-

data/lib/clive/bool.rb

@@ -0,0 +1,64 @@
+class Clive
+  
+  # A switch which can be triggered with either --no-verbose or --verbose
+  # for example.
+  class Bool < Option
+    attr_accessor :truth
+    
+    # Creates a new Bool switch instance. A boolean switch has a truth, 
+    # this determines what is passed to the block. They should be created 
+    # in pairs so one can be +--something+ the other +--no-something+.
+    #
+    # +short+ and/or +desc+ can be omitted when creating a Boolean, all
+    # other arguments must be present.
+    #
+    # @overload initialize(short, long, desc, truth, &block)
+    #   Creates a new boolean switch
+    #   @param [Symbol] short single character to use
+    #   @param [Symbol] long word/longer name for boolean switch
+    #   @param [String] desc description of use/purpose
+    #
+    # @yield [Boolean] A block to be run when the switch is triggered
+    #
+    def initialize(*args, truth, &block)
+      @names = []
+      args.each do |i|
+        case i
+        when Symbol
+          if truth
+            @names << i.to_s
+          else
+            @names << "no-#{i.to_s}" if i.length > 1
+          end
+        when String
+          @desc = i
+        end
+      end
+      
+      unless @names.find_all {|i| i.length > 1}.length > 0
+        raise MissingLongName, @names[0]
+      end
+      
+      @truth = truth
+      @block = block
+    end
+    
+    # Run the block with +@truth+
+    def run
+      @block.call(@truth)
+    end
+    
+    # @return [String] summary for help or nil if +@truth = false+
+    def summary(width=30, prepend=5)
+      return nil unless @truth
+      
+      n = names_to_strings(true).join(', ')
+      spaces = width-n.length
+      spaces = 1 if spaces < 1
+      s = spaces(spaces)
+      p = spaces(prepend)
+      "#{p}#{n}#{s}#{@desc}"
+    end
+  
+  end
+end

data/lib/clive/command.rb

@@ -0,0 +1,288 @@
+class Clive
+  
+  # A string which describes the command to execute
+  #   eg. git add
+  #       git pull
+  #
+  class Command < Option
+    
+    attr_accessor :options, :commands
+    attr_accessor :argv, :base
+    attr_accessor :header, :footer
+    
+    # Create a new Command instance
+    #
+    # @overload initialize(base, &block)
+    #   Creates a new base Command to house everything else
+    #   @param [Boolean] base whether the command is the base
+    #
+    # @overload initialize(name, desc, &block)
+    #   Creates a new Command as part of the base Command
+    #   @param [Symbol] name the name of the command
+    #   @param [String] desc the description of the command
+    #
+    # @yield A block to run, containing switches, flags and commands
+    #
+    def initialize(*args, &block)
+      @argv     = []
+      @names    = []
+      @base     = false
+      @commands = Clive::Array.new
+      @options  = Clive::Array.new
+    
+      if args.length == 1 && args[0] == true
+        @base = true
+        self.instance_eval(&block)
+      else
+        args.each do |i|
+          case i
+          when Symbol
+            @names << i.to_s
+          when String
+            @desc = i
+          end
+        end
+        @block = block
+      end
+      
+      @header = "Usage: #{File.basename($0, '.*')} "
+      @header << (@base ? "[commands]" : @names.join(', '))
+      @header << " [options]"
+      @footer = nil
+      
+      self.build_help
+    end
+    
+    # @return [Clive::Array] all bools in this command
+    def bools
+      Clive::Array.new(@options.find_all {|i| i.class == Bool})
+    end
+    
+    # @return [Clive::Array] all switches in this command
+    def switches
+      Clive::Array.new(@options.find_all {|i| i.class == Switch})
+    end
+    
+    # @return [Clive::Array] all flags in this command
+    def flags
+      Clive::Array.new(@options.find_all {|i| i.class == Flag})
+    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
+    end
+    
+    # Parse the ARGV passed from the command line, and run
+    #
+    # @param [::Array] argv the command line input, usually just +ARGV+
+    # @return [::Array] any arguments that were present in the input but not used
+    #
+    def run(argv=[])
+      tokens = argv
+      tokens = tokenize(argv) if @base
+      
+      r = []
+      tokens.each do |i|
+        k, v = i[0], i[1]
+        case k
+        when :command
+          r << v.run(i[2])
+        when :switch
+          v.run
+        when :flag
+          raise MissingArgument.new(v.sort_name) unless i[2] || v.optional
+          v.run(i[2])
+        when :argument
+          r << v
+        end
+      end
+      r.flatten
+    end
+    
+    # Turns the command line input into a series of tokens.
+    # It will only raise errors if this is the base command instance.
+    #
+    # @param [::Array] argv the command line input
+    # @return [::Array] a series of tokens
+    #
+    # @example
+    #
+    #   c.tokenize(["add", "-al", "--verbose"])
+    #   #=> [[:command, #<Clive::Command>, ...args...], [:switch, "a", 
+    #        #<Clive::Switch>], [:switch, "l", #<Clive::Switch>], [:switch, 
+    #        "verbose", #<Clive::Switch>]]
+    #
+    def tokenize(argv)
+      self.find
+      r = []
+      tokens = Tokens.new(argv)
+      
+      pre_command = Tokens.new
+      command = nil
+      tokens.tokens.each do |i|
+        k, v = i[0], i[1]
+        # check if a command
+        if k == :word && commands[v]
+          command = v
+          break
+        else
+          pre_command << i
+        end
+      end
+      
+      post_command = Tokens.new(tokens.array - pre_command - [command])
+      pre_command_tokens = parse(pre_command)
+      r = pre_command_tokens
+      
+      if command
+        t = commands[command].tokenize(post_command)
+        r << [:command, commands[command], t]
+      end
+
+      r
+    end
+    
+    # This runs through the tokens from Tokens#to_tokens (or similar)
+    # and creates a new array with the type of object and the object
+    # itself, possibly with an argument in the case of Flag.
+    #
+    # @param [Tokens] tokens the tokens to run through
+    # @return [::Array] of the form 
+    #   [[:flag, #<Clive::Flag...>, "word"], [:switch, #<Clive::Switch....
+    # @raise [InvalidOption] raised if option given can't be found
+    #
+    def parse(tokens)
+      r = []
+      tokens.tokens.each do |i|
+        k, v = i[0], i[1]
+        if switch = switches[v] || switch = bools[v]
+          r << [:switch, switch]
+        elsif flag = flags[v]
+          r << [:flag, flag]
+        else
+          if k == :word
+            if r.last
+              case r.last[0]
+              when :flag
+                if r.last[2]
+                  r << [:argument, v]
+                else
+                  r.last[2] = v
+                end
+              else
+                r << [:argument, v]
+              end
+            end
+          else
+            raise InvalidOption.new(v)
+          end
+        end
+      end
+      r
+    end
+      
+      
+  #### CREATION HELPERS #### 
+  
+    # 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, &block)
+    end
+    
+    # Add a new switch to +@switches+
+    # @see Switch#initialize
+    def switch(*args, &block)
+      @options << Switch.new(*args, &block)
+    end
+
+    # Adds a new flag to +@flags+
+    # @see Flag#initialize
+    def flag(*args, &block)
+      @options << Flag.new(*args, &block)
+    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, true, &block)
+      @options << Bool.new(*args, false, &block)
+    end
+    alias_method :boolean, :bool
+    
+  #### HELP STUFF ####
+    
+    # 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
+    end
+    
+    # Set the header
+    def header(val)
+      @header = val
+    end
+    
+    # Set the footer
+    def footer(val)
+      @footer = val
+    end
+    
+    def summary(width=30, prepend=5)
+      a = @names.sort.join(', ')
+      b = @desc
+      s = spaces(width-a.length)
+      p = spaces(prepend)
+      "#{p}#{a}#{s}#{b}"
+    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(width=30, prepend=5)
+      summary = "#{@header}\n"
+      
+      if @options.length > 0
+        summary << "\n Options:\n"
+        @options.sort.each do |i|
+          summary << i.summary(width, prepend) << "\n" if i.summary
+        end
+      end
+      
+      if @commands.length > 0
+        summary << "\n Commands:\n"
+        @commands.sort.each do |i|
+          summary << i.summary(width, prepend) << "\n"
+        end
+      end
+      
+      summary << "\n#{@footer}\n" if @footer
+     
+      summary
+    end
+    
+    
+  end
+end