clive 0.3.1 → 0.4.0

data/.gitignore

@@ -21,5 +21,5 @@ pkg
 ## PROJECT::SPECIFIC
 .yardoc
 doc
-ideas.rb
 research
+cov

data/VERSION

@@ -1 +1 @@
-0.3.1
+0.4.0

data/clive.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{clive}
-  s.version = "0.3.1"
+  s.version = "0.4.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-21}
+  s.date = %q{2010-09-19}
   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 = [

data/lib/clive.rb

@@ -22,30 +22,75 @@ require 'clive/bool'
 #   end
 #   c.parse(ARGV)
 #
+# @example Non-simple Example
+#
+#   opts = {}
+#   c = Clive.new do
+#     bool(:v, :verbose, "Run verbosely") {|i| opts[:verbose] = i}
+#     
+#     command :add, "Add a new project" do
+#       opts[:add] = {}
+#       
+#       switch(:force, "Force overwrite") {opts[:add][:force] = true}
+#       flag :framework, "Add framework" do |i| 
+#         opts[:add][:framework] ||= []
+#         opts[:add][:framework] << i
+#       end
+#       
+#       command :init, "Initialize the project after creating" do
+#         switch(:m, :minimum, "Use minimum settings") {opts[:add][:min] = true}
+#         flag(:w, :width) {|i| opts[:add][:width] = i.to_i}
+#       end
+#     
+#     end
+#     
+#     switch :version, "Show version" do
+#       puts "1.0.0"
+#       exit
+#     end
+#   end
+#   ARGV = c.parse(ARGV)
+#
 class Clive
-
+  
+  # This is the base command, the only way it differs from a normal command
+  # is that it has no name and it's block is executed immediately on creation.
+  #
+  # @return [Command] the base command
+  #   
   attr_accessor :base
   
   def initialize(&block)
     @base = Command.new(true, &block)
   end
   
+  # Parse the base command
   def parse(argv)
     @base.run(argv)
   end
   
+# @group Base Proxy Methods
+  
+  # @see Command#switches
+  # @return [Array] switches in +base+
   def switches
     @base.switches
   end
   
+  # @see Command#commands
+  # @return [Array] commands in +base+
   def commands
     @base.commands
   end
   
+  # @see Command#flags
+  # @return [Array] flags in +base+
   def flags
     @base.flags
   end
   
+  # @see Command#bools
+  # @return [Array] bools in +base+
   def bools
     @base.bools
   end

data/lib/clive/bool.rb

@@ -1,13 +1,14 @@
 class Clive
   
-  # A switch which can be triggered with either --no-verbose or --verbose
-  # for example.
+  # A switch which can be triggered with either --no-[name] and --[name].
+  # The 'truthness' of this is then passed to the block.
   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+.
+    # NOTE: this does not happen within this class!
     #
     # +short+ and/or +desc+ can be omitted when creating a Boolean, all
     # other arguments must be present.
@@ -19,6 +20,7 @@ class Clive
     #   @param [String] desc description of use/purpose
     #
     # @yield [Boolean] A block to be run when the switch is triggered
+    # @raise [MissingLongName] raises when a long name is not given
     #
     def initialize(*args, truth, &block)
       @names = []
@@ -35,6 +37,7 @@ class Clive
         end
       end
       
+      # booleans require a long name to add --no- to
       unless @names.find_all {|i| i.length > 1}.length > 0
         raise MissingLongName, @names[0]
       end
@@ -48,6 +51,8 @@ class Clive
       @block.call(@truth)
     end
     
+    # @param [Integer] width the total ideal width of help
+    # @param [Integer] prepend the number of spaces to add before each line
     # @return [String] summary for help or nil if +@truth = false+
     def summary(width=30, prepend=5)
       return nil unless @truth

data/lib/clive/command.rb

@@ -98,8 +98,15 @@ class Clive
         when :switch
           v.run
         when :flag
-          raise MissingArgument.new(v.sort_name) unless i[2] || v.optional
-          v.run(i[2])
+          args = i[2..-1]
+          opt_args = v.arg_num(true)
+          nec_args = v.arg_num(false)
+          # check for missing args
+          if args.size < nec_args
+            raise MissingArgument.new(v.sort_name)
+          end
+          
+          v.run(args)
         when :argument
           r << v
         end
@@ -170,8 +177,8 @@ class Clive
         else
           if k == :word
             # add to last flag?
-            if r.last && r.last[0] == :flag && r.last[2].nil?
-              r.last[2] = v
+            if r.last && r.last[0] == :flag && r.last.size - 2 < r.last[1].args.size
+              r.last.push(v)
             else
               r << [:argument, v]
             end
@@ -261,6 +268,7 @@ class Clive
       if @options.length > 0
         summary << "\n Options:\n"
         @options.sort.each do |i|
+          next if i.names.include?("help")
           summary << i.summary(width, prepend) << "\n" if i.summary
         end
       end

data/lib/clive/exceptions.rb

@@ -1,6 +1,6 @@
 class Clive
   
-  # general problem
+  # General problem
   class CliveError < StandardError
     attr_accessor :args
     
@@ -26,21 +26,27 @@ class Clive
   
   end
   
-  # general problem with input
+  # General problem with input
   class ParseError < CliveError
     def reason; "parse error"; end
   end
   
-  # a flag has a missing argument
+  # A flag has a missing argument
   class MissingArgument < ParseError
     def reason; "missing argument"; end
   end
   
-  # a option that wasn't defined has been found
+  # A flag has a wrong argument
+  class InvalidArgument < ParseError
+    def reason; "invalid argument"; end
+  end
+  
+  # An option that wasn't defined has been found
   class InvalidOption < ParseError
     def reason; "invalid option"; end
   end
   
+  # Long name is missing for bool
   class MissingLongName < CliveError
     def reason; "missing long name"; end
   end

data/lib/clive/ext.rb

@@ -2,7 +2,7 @@ class Clive
 
   class Array < ::Array
     
-    # If passed a Symbol or String will get the item with that name.
+    # If passed a Symbol or String will get the option or command with that name.
     # Otherwise does what you expect of an Array (see ::Array#[])
     #
     # @param [Symbol, String, Integer, Range] val name or index of item to return
@@ -16,5 +16,38 @@ class Clive
       end
     end
     
+    # Attempts to fill +self+ with values from +input+, giving priority to 
+    # true, then false. If insufficient input to fill all false will use nil.
+    #
+    # @param [Array] input array of values to fill +self+ with
+    # @return [Array] filled array
+    #
+    # @example
+    #
+    #   [true, false, false, true].optimise_fill(["a", "b", "c"])
+    #   #=> ["a", "b", nil, "c"]
+    #
+    #
+    def optimise_fill(input)
+      match = self
+      diff = input.size - match.reject{|i| i == false}.size
+      
+      result = []
+      match.each_index do |i|
+        curr_item = match[i]
+        if curr_item == true
+          result << input.shift
+        else
+          if diff > 0
+            result << input.shift
+            diff -= 1
+          else
+            result << nil
+          end
+        end
+      end
+      result
+    end
+    
   end
 end

data/lib/clive/flag.rb

@@ -1,44 +1,75 @@
 class Clive
   
-  # A switch that takes an argument, with or without an equals
+  # A switch that takes one or more arguments.
   #   eg. wget --tries=10
   #       wget -t 10
   #
   class Flag < Option
-    attr_accessor :arg_name, :optional
+    attr_accessor :args
         
-    # Creates a new Flag instance.
+    # Creates a new Flag instance. A flag is a switch that can take one or more
+    # arguments.
     #
-    # +short+ _or_ +long+ can be omitted but not both.
+    # +short+ *or* +long+ can be omitted but not both.
+    # +args+ can also be omitted (is "ARG" by default)
     #
-    # @overload flag(short, long, desc, &block)
-    #   Creates a new flag
+    # @overload flag(short, long, args, desc, &block)
     #   @param [Symbol] short single character for short flag, eg. +:t+ => +-t 10+
     #   @param [Symbol] long longer switch to be used, eg. +:tries+ => +--tries=10+
+    #   @param [String, Array] args
+    #     either a string showing the arguments to be given, eg.
+    #    
+    #       "FROM"    # single arg, or
+    #       "FROM TO" # two args, or
+    #       "[VIA]"   # optional arg surrounded by square brackets
+    #
+    #     or an array of acceptable inputs, eg.
+    #
+    #       ["large", "medium", "small"] # will only accept these args
+    #
     #   @param [String] desc the description for the flag
     #
     # @yield [String] A block to be run if switch is triggered
     #
     def initialize(*args, &block)
-      @names    = []
-      @optional = false
-      @arg_name = "ARG"
+      @names = []
+      @args  = []
       
+      # Need to be able to make each arg_name optional or not
+      # and allow for type in future
       args.each do |i|
         if i.is_a? String
-          if i =~ /^[\[\]A-Z0-9]+$/
-            @arg_name = i
+          if i =~ /\A(([A-Z0-9\[\]]+)\s?)+\Z/
+            i.split(' ').each do |arg|
+              type = String
+              if arg[0] == "["
+                @args << {
+                  :name => arg[1..arg.length-2], 
+                  :optional => true,
+                  :type => type
+                }
+              else
+                @args << {
+                  :name => arg, 
+                  :optional => false, 
+                  :type => type
+                }
+              end
+            end
           else
             @desc = i
           end
         else
-          @names << i.to_s
+          if i.class == Symbol
+            @names << i.to_s 
+          else
+            @args = i
+          end
         end
       end
       
-      if @arg_name[0] == "["
-        @arg_name = @arg_name[1..@arg_name.length-2]
-        @optional = true
+      if @args == []
+        @args = [{:name => "ARG", :optional => false, :type => String}]
       end
 
       @block = block
@@ -46,20 +77,45 @@ class Clive
     
     # Runs the block that was given with an argument
     #
-    # @param [String] arg argument to pass to the block
-    def run(arg)
-      @block.call(arg)
+    # @param [Array] args arguments to pass to the block
+    # @raise [InvalidArgument] only if +args+ is an array of acceptable inputs
+    #   and a match is not found.
+    def run(args)
+      if @args[0].is_a? Hash
+        args = Clive::Array.new(@args.collect {|i| !i[:optional]}).optimise_fill(args)
+      else # list
+        unless @args.include? args[0]
+          raise InvalidArgument.new(args)
+        end
+      end
+      @block.call(*args)
+    end
+    
+    # @param [Boolean] optional whether to include optional arguments
+    # @return [Integer] number of arguments this takes
+    def arg_num(optional)
+      if @args[0].is_a? Hash
+        @args.find_all {|i| i[:optional] == optional }.size
+      else
+        1
+      end
     end
     
     # @return [String] summary for help
     def summary(width=30, prepend=5)
       n = names_to_strings.join(', ')
-      if @optional
-        n << " [#{@arg_name}]"
+      a = nil
+      if @args[0].is_a? Hash
+        a = @args.map {|i| i[:name]}.join(' ')
+        if @optional
+          n << " [#{a}]"
+        else
+          n << " #{a}"
+        end
       else
-        n << " #{@arg_name}"
+        n << " {" << @args.join(', ') << "}"
       end
-      
+
       spaces = width-n.length
       spaces = 1 if spaces < 1
       s = spaces(spaces)

data/lib/clive/option.rb

@@ -1,16 +1,17 @@
 class Clive
   
+  # @abstract Subclass and override {#initialize} and {#run} to create a new Option class.
   class Option
     attr_accessor :names, :desc, :block
     
-    def initialize(desc, *names, &block)
-      @names = names
-      @desc = desc
-      @block = block
+    def initialize(*args, &block)
+      # assign name and description
+      # @block = block
     end
     
     def run
-      @block.call
+      # call the block!
+      # @block.call
     end
     
     def summary(width=30, prepend=5)
@@ -22,7 +23,8 @@ class Clive
       "#{p}#{n}#{s}#{@desc}"
     end
     
-    # Convert the names to strings, depending on length
+    # Convert the names to strings, if name is single character appends
+    # +-+, else appends +--+.
     #
     # @param [Boolean] bool whether to add [no-] to long
     #
@@ -69,6 +71,7 @@ class Clive
       r
     end
     
+    # Compare options based on Option#sort_name
     def <=>(other)
       self.sort_name <=> other.sort_name
     end

data/lib/clive/tokens.rb

@@ -11,13 +11,17 @@ class Clive
   #   ["Value", "--verbose", "-r"]
   #
   class Tokens < Array
-      
+    
     TOKEN_KEYS = [:word, :short, :long]
     
     # Create a new Tokens instance. Pass either an array of tokens
     # or a plain array, they will be converted correctly.
     #
-    # @param [::Array]
+    # @param [Array] args 
+    #   pass either
+    #     ["command", "--flag"]
+    #     # or
+    #     [[:word, "command"], [:long, "flag"]]
     # @return [Tokens]
     #
     def initialize(args=[])
@@ -51,7 +55,10 @@ class Clive
       arr
     end
     
-    # Creates an array of tokens based on +self+
+    # Creates an array of tokens based on +self+.
+    # Strings beginning with a -, eg. -n become [:short, "n"].
+    # Strings beginning with --, eg. --verbose become [:long, "verbose"].
+    # Strings which begin with neither become [:word, "value"].
     #
     # @return [::Array] the tokens that are held
     def tokens
@@ -78,10 +85,12 @@ class Clive
       t
     end
     
+    # @see #tokens
     def self.to_tokens(arr)
       Tokens.new(arr).tokens
     end
     
+    # @see #array
     def self.to_array(tokens)
       Tokens.new(tokens).array
     end

data/test/bin_test

@@ -48,6 +48,7 @@ c = Clive.new do
 
 end
 
+p ARGV
 p c.parse(ARGV)
 p options
 

data/test/helper.rb

@@ -1,10 +1,13 @@
+require 'duvet'
+Duvet.start :filter => 'clive/lib'
+
 require 'test/unit'
 require 'shoulda'
 require 'rr'
 
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 $LOAD_PATH.unshift(File.dirname(__FILE__))
-require 'clive'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'clive')
 
 class Test::Unit::TestCase
   include RR::Adapters::TestUnit

data/test/test_clive.rb

@@ -155,6 +155,12 @@ class TestClive < Test::Unit::TestCase
       assert_equal ["argument"], args
     end
     
+    should "recognise a quoted argument" do
+      c = Clive.new {}
+      args = c.parse ['a quoted argument']
+      assert_equal ["a quoted argument"], args
+    end
+    
     should "recognise multiple arguments" do
       c = Clive.new do
         bool(:v, :verbose, "Run verbosely") {}

data/test/test_flag.rb

@@ -6,7 +6,7 @@ class TestFlag < Test::Unit::TestCase
     
     setup do
       @c = Clive.new do
-        flag(:t, :type, "TEXT", "Change type to TYPE") {|i| $stdout.puts(i)}
+        flag(:t, :type, "TEXT", "Change type to TYPE") {|i| puts(i)}
       end
     end
     
@@ -15,14 +15,14 @@ class TestFlag < Test::Unit::TestCase
       @c.parse(["--type", "text"])
     end
     
-    should "have an arg name" do
-      assert_equal "TEXT", @c.flags["t"].arg_name
+    should "have a arguments" do
+      r = {:name => "TEXT", :optional => false, :type => String}
+      assert_equal r, @c.flags["t"].args[0]
     end
     
     should "not be optional" do
-      assert_equal false, @c.flags["t"].optional
+      assert_equal false, @c.flags["t"].args[0][:optional]
     end
-    
   end
   
   context "A new flag with default" do
@@ -37,11 +37,12 @@ class TestFlag < Test::Unit::TestCase
     end
     
     should "have an arg name" do
-      assert_equal "TEXT", @c.flags["t"].arg_name
+      r = {:name => "TEXT", :optional => true, :type => String}
+      assert_equal r, @c.flags["t"].args[0]
     end
     
     should "be optional" do
-      assert_equal true, @c.flags["t"].optional
+      assert_equal true, @c.flags["t"].args[0][:optional]
     end
     
     should "pass an argument to block" do
@@ -55,4 +56,105 @@ class TestFlag < Test::Unit::TestCase
     end
   end
   
+  context "A new flag with multiple arguments" do
+    
+    setup do
+      @c = Clive.new do
+        flag(:s, :send, "FROM TO", "Send the message from FROM to TO") do |from, to|
+          puts from
+          puts to
+        end
+      end
+    end 
+    
+    should "pass two arguments to the block" do
+      mock($stdout).puts("John")
+      mock($stdout).puts("Dave")
+      @c.parse(["--send", "John", "Dave"])
+    end
+    
+    should "have a useful summary" do
+      s = "-s, --send FROM TO Send the message from FROM to TO"
+      assert_equal s, @c.flags['s'].summary(0, 0)
+    end
+    
+    should "work for more than two arguments" do
+      mock($stdout).puts("from: Josh, to: John, via: Hong Kong, because: It's far away")
+      c = Clive.new do
+        flag(:s, :send, "FROM TO VIA BECAUSE", "Send the message...etc") do |f, t, v, b|
+          puts "from: #{f}, to: #{t}, via: #{v}, because: #{b}"
+        end
+      end
+      c.parse ['-s', 'Josh', 'John', "Hong Kong", "It's far away"]
+    end
+    
+    context "and optional arguments" do
+      setup do
+        @c = Clive.new do
+          flag(:s, :send, "FROM [VIA] TO [BECAUSE]", "Send the message...etc") do |f, v, t, b|
+            s = "from: #{f}"
+            s << ", via: #{v}" if v
+            s << ", to: #{t}"
+            s << ", because: #{b}" if b
+            puts s
+          end
+        end
+      end
+      
+      should "correctly parse argument string" do
+        r = [
+          {:name => "FROM",    :optional => false, :type => String},
+          {:name => "VIA",     :optional => true,  :type => String},
+          {:name => "TO",      :optional => false, :type => String},
+          {:name => "BECAUSE", :optional => true,  :type => String}
+        ]
+        assert_equal r, @c.flags[:s].args
+      end
+      
+      should "give all arguments when found in input" do
+        mock($stdout).puts("from: Josh, via: Hong Kong, to: John, because: It's far away")
+        @c.parse ["-s", "Josh", "Hong Kong", "John", "It's far away"]
+      end
+      
+      should "try to give only needed arguments if some missing" do
+        mock($stdout).puts("from: Josh, to: John")
+        @c.parse ["-s", "Josh", "John"]
+      end
+      
+      should "fill optional arguments starting from left" do
+        mock($stdout).puts("from: Josh, via: Hong Kong, to: John")
+        @c.parse ["-s", "Josh", "Hong Kong", "John"]
+      end
+      
+    end
+  end
+  
+  context "A new flag with a list of acceptable arguments" do
+    
+    setup do
+      @c = Clive.new do
+        flag(:t, :type, ["large", "medium", "small"], "Choose the type to use") {}
+      end
+    end
+    
+    should "raise error when correct argument not found" do
+      assert_raise Clive::InvalidArgument do
+        @c.parse(["--type", "apple"])
+      end
+    end
+    
+    should "not raise error when correct argument given" do
+      @c.parse(["--type", "large"])
+    end
+    
+    should "make list arguments" do
+      r = ["large", "medium", "small"]
+      assert_equal r, @c.flags['t'].args
+    end
+    
+    should "have a useful summary" do
+      s = "-t, --type {large, medium, small} Choose the type to use"
+      assert_equal s, @c.flags['t'].summary(0, 0)
+    end
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: clive
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 15
   prerelease: false
   segments: 
   - 0
-  - 3
-  - 1
-  version: 0.3.1
+  - 4
+  - 0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Joshua Hawxwell
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-21 00:00:00 +01:00
+date: 2010-09-19 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency