clive 0.6.2 → 0.7.0

data/lib/clive/bool.rb

@@ -1,7 +1,8 @@
-class Clive
-  
+module Clive
+
   # A switch which can be triggered with either --no-[name] and --[name].
-  # The 'truthness' of this is then passed to the block.
+  # The 'truth' of this is then passed to the block.
+  #
   class Bool < Option
     attr_accessor :truth
     
@@ -13,27 +14,27 @@ class Clive
     # +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
+    # @param names [Array[Symbol]]
+    #   Names that the boolean switch can be called with, must include
+    #   a long name (eg. 2 or more characters) so that the --no- can
+    #   be prefixed.
+    #
+    # @param desc [String]
+    #   A description of the bool.
+    #
+    # @param truth [true, false] 
+    #   Truth of the switch to create.
     #
-    # @yield [Boolean] A block to be run when the switch is triggered
-    # @raise [MissingLongName] raises when a long name is not given
+    # @yield [true, false] A block to be run when the switch is triggered
+    # @raise [MissingLongName] Raised when a long name is not given
     #
-    def initialize(*args, truth, &block)
+    def initialize(names, desc, 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
+      names.each do |i|
+        if truth
+          @names << i.to_s
+        else
+          @names << "no-#{i.to_s}" if i.length > 1
         end
       end
       
@@ -42,27 +43,24 @@ class Clive
         raise MissingLongName, @names[0]
       end
       
+      @desc = desc
       @truth = truth
       @block = block
     end
     
-    # Run the block with +@truth+
+    # Run the block with the switches truth.
     def run
       @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
-      
-      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}"
+    # Should only return a hash when this is the 'true' switch.
+    # @see Clive::Option#to_h
+    def to_h
+      if @truth
+        {'names' => names_to_strings(true), 'desc' => @desc}
+      else
+        nil
+      end
     end
   
   end

data/lib/clive/command.rb

@@ -1,4 +1,4 @@
-class Clive
+module Clive
   
   # A string which describes the command to execute
   #   eg. git add
@@ -8,18 +8,18 @@ class Clive
     
     attr_accessor :options, :commands
     attr_accessor :argv, :base
-    attr_accessor :header, :footer
+    attr_reader   :names, :current_desc
     
     # 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
+    #   @param base [Boolean] whether the command is the base
     #
-    # @overload initialize(name, desc, &block)
+    # @overload initialize(names, 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
+    #   @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
     #
@@ -47,10 +47,15 @@ class Clive
         @block = block
       end
       
-      @header = "Usage: #{File.basename($0, '.*')} "
-      @header << (@base ? "[commands]" : @names.join(', '))
-      @header << " [options]"
+      # 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
@@ -146,7 +151,7 @@ class Clive
           pre_command << i
         end
       end
-      
+
       post_command = Tokens.new(tokens.array - pre_command - [command])
       pre_command_tokens = parse(pre_command)
       r = pre_command_tokens
@@ -179,7 +184,7 @@ class Clive
         else
           if k == :word
             # add to last flag?
-            if r.last && r.last[0] == :flag && r.last.size - 2 < r.last[1].args.size
+            if r.last && r.last[0] == :flag && r.last.size - 2 < r.last[1].arg_size
               r.last.push(v)
             else
               r << [:argument, v]
@@ -192,13 +197,16 @@ class Clive
       r
     end
     
-  # @group Missing Helpers
+    def to_h
+      {
+        'names' => @names,
+        'desc'  => @desc
+      }
+    end
   
-    def option_missing(&block)
-      @option_missing = block
-    end      
+    
       
-  # @group Creators
+  # @group DSL
   
     # Add a new command to +@commands+
     #
@@ -211,19 +219,35 @@ class Clive
     #   and flags
     #
     def command(*args, &block)
-      @commands << Command.new(*args, &block)
+      @commands << Command.new(*args, @current_desc, &block)
+      @current_desc = ""
     end
     
     # Add a new switch to +@switches+
     # @see Switch#initialize
     def switch(*args, &block)
-      @options << Switch.new(*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)
-      @options << Flag.new(*args, &block)
+      names = []
+      arg = []
+      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
@@ -232,21 +256,48 @@ class Clive
     #
     # @see Bool#initialize
     def bool(*args, &block)
-      @options << Bool.new(*args, true, &block)
-      @options << Bool.new(*args, false, &block)
+      @options << Bool.new(args, @current_desc, true, &block)
+      @options << Bool.new(args, @current_desc, false, &block)
+      @current_desc= ""
     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
+    # Add a description for the next option in the class. Or acts as an 
+    # accessor for @desc.
+    #
+    # @example
+    #
+    #   class CLI
+    #     include Clive::Parser
+    #
+    #     desc 'Force build docs'
+    #     switch :force do
+    #       # code
+    #     end
+    #   end
+    #
+    def desc(str=nil)
+      if str
+        @current_desc = str
+      else
+        @desc
       end
     end
     
+    # Define a block to execute when the option to execute cannot be found.
+    #
+    # @example
+    #
+    #   class CLI
+    #     include Clive::Parser
+    #
+    #     option_missing do |name|
+    #       puts "#{name} couldn't be found"
+    #     end
+    #
+    def option_missing(&block)
+      @option_missing = block
+    end      
+    
     # Set the header
     def header(val)
       @header = val
@@ -257,40 +308,106 @@ class Clive
       @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
+  # @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
+    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"
+    def help
+      @formatter.format(@header, @footer, @commands, @options)
+    end
+    
+    # This allows you to define how the output from #help looks.
+    #
+    # 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:
+    #
+    # * 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
+    #
+    # And for flags you have access to:
+    #
+    # * args - an array of arguments for the flag
+    # * options - an array of options to choose from
+    #
+    #
+    # @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
+    #
+    # @overload help_formatter(name)
+    #   Use an existing help formatter.
+    #   @param name [Symbol] name of the formatter (either +:default+ or +:white+)
+    #
+    #
+    # @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}"
+    #
+    #   end
+    #   
+    #   
+    def help_formatter(*args, &block)    
+      if block_given?
+        width   = 30
+        prepend = 5
       
-      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
+        unless args.empty?
+          args[0].each do |k,v|
+            case k
+            when :width
+              width = v
+            when :prepend
+              prepend = v
+            end
+          end
         end
-      end
-      
-      if @commands.length > 0
-        summary << "\n Commands:\n"
-        @commands.sort.each do |i|
-          summary << i.summary(width, prepend) << "\n"
+        
+        @formatter = Formatter.new(width, prepend)
+        block.call(@formatter)
+        @formatter
+      else
+        case args[0]
+        when :default
+           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} {options.join('(', ', ', ')').blue.bold}"
+            h.command "{prepend}{names.join(', ')}  {spaces}{desc.grey}"
+          end
+        
+        when :white
+          help_formatter do |h|
+            h.switch  "{prepend}{names.join(', ')}  {spaces}{desc}"
+            h.bool    "{prepend}{names.join(', ')}  {spaces}{desc}"
+            h.flag    "{prepend}{names.join(', ')} {args.join(' ')}  {spaces}" << 
+                        "{desc} {options.join('(', ', ', ')').bold}"
+            h.command "{prepend}{names.join(', ')}  {spaces}{desc}"
+          end
+        
         end
       end
-      
-      summary << "\n#{@footer}\n" if @footer
-     
-      summary
     end
     
-    
   end
 end

data/lib/clive/exceptions.rb

@@ -1,4 +1,4 @@
-class Clive
+module Clive
   
   # General problem
   class CliveError < StandardError
@@ -23,7 +23,7 @@ class Clive
       self.reason + ': ' + args.join(' ')
     end
     alias_method :to_s, :message
-  
+    
   end
   
   # General problem with input

data/lib/clive/ext.rb

@@ -1,5 +1,4 @@
-class Clive
-
+module Clive
   class Array < ::Array
     
     # If passed a Symbol or String will get the option or command with that name.
@@ -49,5 +48,24 @@ class Clive
       result
     end
     
+    alias_method :_join, :join
+    
+    def join(*args)
+      case args.size
+      when 1
+        self._join(args[0])
+        
+      when 2 # use second for last eg. 1, 2 and 3
+        self[0..-2]._join(args[0]) << args[1] << self[-1]
+        
+      when 3 # prepend and append 1st and 3rd eg. (1, 2, 3)
+        if self[0] != ""
+          args[0] << self._join(args[1]) << args[2]
+        else
+          ""
+        end
+      end
+    end
+    
   end
-end
+end