clive 0.6.2 → 0.7.0

data/lib/clive/flag.rb

@@ -1,4 +1,4 @@
-class Clive
+module Clive
   
   # A switch that takes one or more arguments.
   #   eg. wget --tries=10
@@ -10,68 +10,58 @@ class Clive
     # 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.
-    # +args+ can also be omitted (is "ARG" by default)
+    # @param names [Array[Symbol]]
+    #   An array of names the flag can be invoked by. Can contain a long name
+    #   and/or a short name.
     #
-    # @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
+    # @param desc [String]
+    #   A description of the flag.
     #
-    #     or an array of acceptable inputs, eg.
+    # @param args [String, Array, Range]
+    #   Either, a string showing the arguments to be given, eg.
+    #     
+    #     "FROM"          # single argument required, or
+    #     "[FROM]"        # single optional argument, or
+    #     "FROM TO"       # multiple arguments required, or
+    #     "FROM [VIA] TO" # multiple arguments with optional argument
     #
-    #       ["large", "medium", "small"] # will only accept these args
+    #   OR an array of acceptable inputs, eg.
     #
-    #   @param [String] desc the description for the flag
+    #     %w(large small medium) # will only accept these arguments
+    #   
+    #   OR a range, showing the acceptable inputs, eg.
+    #     1..10 #=> means 1, 2, 3, ..., 8, 9, 10
     #
-    # @yield [String] A block to be run if switch is triggered
+    # @yield [String] 
+    #   A block to be run if switch is triggered, will always be passed a string
     #
-    def initialize(*args, &block)
-      @names = []
-      @args  = []
+    def initialize(names, desc, args, &block)
+      @names = Clive::Array.new(names.map(&:to_s))
+      @args  = Clive::Array.new
       
       # 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(([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
+        case i
+        when String
+          i.split(' ').each do |arg|
+            optional = false
+            if arg[0] == "["
+              optional = true
+              arg = arg[1..-2]
             end
-          else
-            @desc = i
+            @args << {:name => arg, :optional => optional}
           end
         else
-          if i.class == Symbol
-            @names << i.to_s 
-          else
-            @args = i
-          end
+          @args = i
         end
       end
-      
-      if @args == []
-        @args = [{:name => "ARG", :optional => false, :type => String}]
-      end
 
+      if @args.empty?
+        @args = [{:name => "ARG", :optional => false}]
+      end
+      
+      @desc  = desc
       @block = block
     end
     
@@ -81,10 +71,10 @@ class Clive
     # @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
+      if @args.is_a?(Array) && @args[0].is_a?(Hash)
         args = Clive::Array.new(@args.collect {|i| !i[:optional]}).optimise_fill(args)
       else # list
-        unless @args.include? args[0]
+        unless @args.to_a.map(&:to_s).include? args[0]
           raise InvalidArgument.new(args)
         end
       end
@@ -94,33 +84,56 @@ class Clive
     # @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
+      if @args.is_a?(Array) && @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(', ')
-      a = nil
-      if @args[0].is_a? Hash
-        a = @args.map {|i| i[:name]}.join(' ')
-        if @optional
-          n << " [#{a}]"
-        else
-          n << " #{a}"
+    def args_to_strings
+      if @args.is_a? Range
+        [""]
+      elsif @args[0].is_a? Hash
+        r = []
+        @args.each do |arg|
+          if arg[:optional]
+            r << "[" + arg[:name] + "]"
+          else
+            r << arg[:name]
+          end
         end
+        r
       else
-        n << " {" << @args.join(', ') << "}"
+        [""]
       end
-
-      spaces = width-n.length
-      spaces = 1 if spaces < 1
-      s = spaces(spaces)
-      p = spaces(prepend)
-      "#{p}#{n}#{s}#{@desc}"
+    end
+    
+    def arg_size
+      if @args.is_a?(Range) || @args.is_a?(Array)
+        1
+      else
+        @args.size
+      end
+    end
+    
+    def options_to_strings
+      if @args.is_a? Range
+        [@args.to_s]
+      elsif @args[0].is_a? Hash
+        ['']
+      else
+        @args
+      end
+    end
+    
+    def to_h
+      {
+        'names'   => Clive::Array.new(names_to_strings),
+        'desc'    => @desc,
+        'args'    => Clive::Array.new(args_to_strings),
+        'options' => Clive::Array.new(options_to_strings)
+      }
     end
     
   end

data/lib/clive/formatter.rb

@@ -0,0 +1,180 @@
+require 'strscan'
+
+module Clive
+  
+  # The formatter controls formatting of help. It can be configured
+  # using Clive::Command#help_formatter.
+  class Formatter
+  
+    class Obj
+      def initialize(args)
+        args.each do |k, v|
+          self.class.send(:define_method, k) { v }
+        end
+      end
+      
+      # Evaluate the code given within the Obj created.
+      def evaluate(code)
+        eval(code)
+      end
+    end
+  
+    # Sizes
+    attr_accessor :width, :prepend
+  
+    def initialize(width, prepend, &block)
+      @width = width
+      @prepend = prepend
+    end
+    
+    
+    def format(header, footer, commands, options)
+      result = ""
+    
+      switches = options.find_all {|i| i.class == Clive::Switch }.map(&:to_h)
+      bools    = options.find_all {|i| i.class == Clive::Bool }.map(&:to_h).compact
+      flags    = options.find_all {|i| i.class == Clive::Flag }.map(&:to_h)
+      commands = commands.map(&:to_h)
+      
+      result << header << "\n" if header
+      
+      unless commands.empty?
+        result << "\n  Commands: \n"
+        
+        commands.each do |hash|
+          hash['prepend'] = " " * @prepend
+          result << parse(@command, hash) << "\n"
+        end
+      end
+      
+      
+      unless options.empty?
+        result << "\n  Options: \n"
+      
+        switches.each do |hash|
+          hash['prepend'] = " " * @prepend
+          result << parse(@switch, hash) << "\n"
+        end
+        
+        bools.each do |hash|
+          hash['prepend'] = " " * @prepend
+          result << parse(@bool, hash) << "\n"
+        end
+        
+        flags.each do |hash|
+          hash['prepend'] = " " * @prepend
+          result << parse(@flag, hash) << "\n"
+        end
+      end
+      
+      result << "\n" << footer << "\n" if footer
+      
+      result
+    end
+    
+    
+    def switch(format)
+      @switch = format
+    end
+    
+    def bool(format)
+      @bool = format
+    end
+    
+    def flag(format)
+      @flag = format
+    end
+    
+    def command(format)
+      @command = format
+    end
+    
+    def help(format)
+      @help = format
+    end
+    
+    def summary(format)
+      @summary = format
+    end
+    
+    
+    def parse(format, args)
+      front, back = format.split('{spaces}')
+      
+      front_p = parse_format(front, args)
+      back_p  = parse_format(back, args) 
+      
+      s = @width - front_p.length
+      s = 0 if s < 0 # can't have negative spaces!
+      spaces = " " * s
+      
+      front_p << spaces << back_p
+    end
+    
+    def parse_format(format, args)
+      if format
+        @scanner = StringScanner.new(format)
+        result = []
+  
+        # Create object to eval in
+        obj = Obj.new(args)
+        
+        until @scanner.eos?
+          a = scan_block || a = scan_text
+          result << a
+        end
+        
+        r = ""
+        result.each do |(t, v)|
+          case t
+          when :block # contains ruby to eval
+            r << obj.evaluate(v)
+          when :text # add this with no adjustment
+            r << v
+          end
+        end
+        r
+      else
+        ""
+      end
+    end
+    
+    
+    # @group Scanning     
+      def scan_block
+        return unless @scanner.scan /\{/
+        
+        pos = @scanner.pos
+        if @scanner.scan_until /\}/
+          @scanner.pos -= @scanner.matched.size
+          [:block, @scanner.pre_match[pos..-1]]
+        end
+      end
+      
+      def scan_text
+        text = nil
+        
+        pos = @scanner.pos
+        if @scanner.scan_until /(?<=[^\\])\{/
+          @scanner.pos -= @scanner.matched.size
+          text = @scanner.pre_match[pos..-1]
+        end
+        
+        if text.nil?
+          text = @scanner.rest
+          @scanner.clear
+        end
+        
+        # Remove }s from text
+        if text[0] == "}"
+          text = text[1..-1]
+        end
+        
+        text.gsub!(/\\(.)/) {|m| m[1] }
+                
+        [:text, text]
+      end
+    # @endgroup
+  
+  end
+end

data/lib/clive/option.rb

@@ -1,32 +1,44 @@
-class Clive
+module Clive
   
-  # @abstract Subclass and override {#initialize} and {#run} to create a new Option class.
+  # @abstract Subclass and override {#initialize} and {#run} to create a 
+  #   new Option class. {#to_h} can also be overriden to provide information
+  #   when building the help.
+  #
+  # Option is the base class for switches, flags, commands, etc. It should be
+  # used as a template for the way options (or whatever) are initialized, and
+  # the other methods that may need implementing.
+  #
   class Option
     attr_accessor :names, :desc, :block
     
-    def initialize(*args, &block)
-      # assign name and description
-      # @block = block
+    # Create a new Option instance. 
+    #
+    # For subclasses the method call should take the form:
+    # +initialize(names, desc, [special args], &block)+.
+    #
+    # @param names [Array[Symbol]]
+    #   An array of names the option can be invoked by.
+    #
+    # @param desc [String]
+    #   A description of what the option does.
+    #
+    # @yield A block to run if the switch is triggered
+    #
+    def initialize(names, desc, &block)
+      @names = names.map(&:to_s)
+      @desc  = desc
+      @block = block
     end
     
+    # Calls the block.
     def run
-      # call the block!
-      # @block.call
-    end
-    
-    def summary(width=30, prepend=5)
-      n = names_to_strings.join(', ')
-      spaces = width-n.length
-      spaces = 1 if spaces < 1
-      s = spaces(spaces)
-      p = spaces(prepend)
-      "#{p}#{n}#{s}#{@desc}"
+      @block.call
     end
     
     # Convert the names to strings, if name is single character appends
     # +-+, else appends +--+.
     #
-    # @param [Boolean] bool whether to add [no-] to long
+    # @param bool [Boolean] whether to add [no-] to long
     #
     # @example
     #
@@ -51,16 +63,10 @@ class Clive
       r
     end
     
-    # Create a string of +n+ spaces
-    def spaces(n)
-      s = ''
-      (0...n).each {s << ' '}
-      s
-    end
-    
-    # Tries to get the short name, if not choose lowest alphabetically
+    # Tries to get the short name, if not chooses lowest alphabetically.
     #
     # @return [String] name to sort by
+    #
     def sort_name
       r = @names.sort[0]
       @names.each do |i|
@@ -75,6 +81,16 @@ class Clive
     def <=>(other)
       self.sort_name <=> other.sort_name
     end
+    
+    # @return [Hash{String=>Object}]
+    #   Returns a hash which can be passed to the help formatter.
+    #
+    def to_h
+      {
+        "names" => names_to_strings,
+        "desc"  => @desc
+      }
+    end
   
   end
 end