clive 0.8.1 → 1.0.0

data/lib/clive/error.rb

@@ -0,0 +1,66 @@
+class Clive
+
+  # For general errors with Clive. It stripts most of the backtrace which 
+  # you don't really want, and allows you to set nice error messages
+  # using {.reason}. Arguments can be passed and then used in messages by 
+  # referencing with +#n+ tokens, where +n+ is the index of the argument.
+  #
+  # A lot of this is pulled from OptionParser::ParseError see
+  # http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/index.html.
+  #
+  # @example
+  #
+  #   class MissingArgumentError < Error
+  #     reason 'missing argument for #0'
+  #   end
+  #
+  #   raise MissingArgumentError.new(some_option)
+  #
+  class Error < StandardError
+    attr_accessor :args
+    
+    # @param args
+    #   Arguments that can be accessed with '#n' in {.reason}.
+    def initialize(*args)
+      @args = args
+    end
+    
+    # Removes all references to files which are not the file being run
+    # unless in $DEBUG mode.
+    def self.filter_backtrace(array)
+      unless $DEBUG
+        array = [$0]
+      end
+      array
+    end
+    
+    # Set the reason for the error class.
+    # @param str [String]
+    def self.reason(str)
+      @reason = str
+    end
+    
+    # Accessor for the reason set with {.reason}.
+    def self._reason
+      @reason
+    end
+    
+    def set_backtrace(array)
+      super(self.class.filter_backtrace(array))
+    end
+    
+    # Build the message by substituting the arguments into the reason.
+    def message
+      self.class._reason.gsub(/#\d/) do |i|
+        arg = args[i[1].to_i]
+        if arg.is_a?(Array)
+          arg.map(&:to_s).to_s
+        else
+          arg.to_s
+        end
+      end
+    end
+    alias_method :to_s, :message
+    
+  end
+end

data/lib/clive/formatter.rb

@@ -1,145 +1,61 @@
-module Clive
-  
-  # The formatter controls formatting of help. It can be configured
-  # using Clive::Command#help_formatter.
+class Clive
+
+  # @abstract Subclass and override {#to_s} (and probably {#initialize}) to
+  #  implement a custom Formatter. {#initialize} *should* take an options
+  #  hash.
+  #
+  # Takes care of formatting the help string. Look at {Formatter::Plain}
+  # for a good (if not a bit complex) reference of how to do it.
+  #
+  # Then it is just a case of passing an instance of the new formatter to
+  # {Clive.run}. You can use a different formatter for commands by
+  # passing it when creating them.
+  #
+  # @example
+  #
+  #   class MainFormatter < Clive::Formatter
+  #     # ...
+  #   end
+  #
+  #   class CommandFormatter < Clive::Formatter
+  #     # ...
+  #   end
+  #
+  #   # Uses MainFormatter
+  #   class CLI
+  #     # ...
+  #
+  #     # Uses CommandFormatter
+  #     command :new, formatter: CommandFormatter.new do
+  #       # ...
+  #     end
+  #
+  #     # Uses MainFormatter
+  #     command :normal do
+  #       # ...
+  #     end
+  #   end
+  #
+  #   CLI.run formatter: MainFormatter.new
+  #
   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
+
+    attr_writer :header, :footer, :options, :commands
+
+    def initialize(opts={})
+      @opts = opts
+
+      @header, @footer = '', ''
+      @commands, @options = [], []
+    end
+
+    def to_s
+      ([@header] + @commands + @options + [@footer]).join("\n")
+    end
+
+    def inspect
+      "#<#{self.class.name} @opts=#@opts>"
     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
-        obj = Obj.new(args)
-        r = ""
-        Lexer.tokenise(format).each do |t,v|
-          case t
-          when :block
-            r << obj.evaluate(v)
-          when :text 
-            r << v
-          end
-        end
-        r
-      else
-        ""
-      end
-    end
-    
-    class Lexer < Ast::Tokeniser
-      rule :text, /%(.)/ do |i|
-        i[1]
-      end
-    
-      rule :block, /\{(.*?)\}/ do |i|
-        i[1]
-      end
-      
-      missing do |i|
-        Ast::Token.new(:text, i)
-      end
-    end
-  
   end
+
 end

data/lib/clive/formatter/colour.rb

@@ -0,0 +1,37 @@
+class Clive
+  class Formatter
+
+    class Colour < Plain
+
+      def after_for(opt)
+        r = ""
+        after = description_for(opt).dup << " " << choices_for(opt)
+        unless after == " "
+          r << "# ".grey << Output.wrap_text(after,
+                                             left_width + padding(2).size,
+                                             @opts[:width])
+        end
+        r
+      end
+
+      def description_for(opt)
+        s = super
+        if s.empty?
+          s
+        else
+          s.grey
+        end
+      end
+
+      def choices_for(opt)
+        s = super
+        if s.empty?
+          s
+        else
+          s.blue.bold
+        end
+      end
+
+    end
+  end
+end

data/lib/clive/formatter/plain.rb

@@ -0,0 +1,172 @@
+class Clive
+  class Formatter
+
+    class Plain < Formatter
+
+      DEFAULTS = {
+        :padding   => 2,
+        :width     => Output.terminal_width,
+        :min_ratio => 0.2,
+        :max_ratio => 0.5
+      }
+
+      # @param opts [Hash]
+      # @option opts [Integer] :width
+      #   Total width of screen to use
+      # @option opts [Integer] :padding
+      #   Amount of padding to use
+      # @option opts [Float] :min_ratio
+      #   Minimum proportion of screen the left side can use
+      # @option opts [Float] :max_ratio
+      #   Maximum proportion of screen the left side can use
+      def initialize(opts={})
+        @opts = DEFAULTS.merge(opts)
+
+        if @opts[:min_ratio] > @opts[:max_ratio]
+          @opts[:max_ratio] = @opts[:min_ratio]
+        end
+
+        @header, @footer = "", ""
+        @commands, @options = [], []
+      end
+
+      # Builds the help string. Formatted like:
+      #
+      #  Usage: the header
+      #
+      #    Commands:
+      #      command            # Description
+      #
+      #    Options:
+      #      -a, --abc <arg>    # Description
+      #
+      #  A footer
+      #
+      # @return [String]
+      def to_s
+        groups = (@options + @commands).group_by {|i| i.config[:group] }
+
+        # So no groups were created, let's create some nice defaults
+        if groups.size == 1 && groups.keys.first == nil
+          # Use an array so that the order is always correct
+          groups = [['Commands', @commands.sort], ['Options', @options.sort]]
+        end
+
+        r = @header.dup << "\n\n"
+
+        groups.each do |name, group|
+          unless group.empty?
+            r << (name ? "#{padding}#{name}:\n" : '')
+            group.sort.sort_by {|i| i.instance_of?(Command) ? 0 : 1 }.each do |opt|
+              r << build_option_string(opt)
+            end
+            r << "\n"
+          end
+        end
+
+        r << @footer
+        r.split("\n").map {|i| i.rstrip }.join("\n")
+      end
+
+      protected
+
+      # @return [String] Default padding
+      def padding(n=1)
+        ' ' * (@opts[:padding] * n)
+      end
+
+      # @return [Integer] Width of the left half, ie. up to {#after}
+      def left_width
+        w = max + padding(2).size
+        if w > @opts[:max_ratio] * @opts[:width]
+          (@opts[:max_ratio] * @opts[:width]).to_i
+        elsif w < @opts[:min_ratio] * @opts[:width]
+          (@opts[:min_ratio] * @opts[:width]).to_i
+        else
+          w.to_i
+        end
+      end
+
+      # @return [Integer] The greatest width the left part of the screen
+      #  can be. This allows you to use _a_ max width in calculations
+      #  without creating a loop.
+      def max_left_width
+        (@opts[:max_ratio] * @opts[:width]).to_i
+      end
+
+      # @return [Integer] The length of the longest {#before}, ignoring any that break
+      #  the line.
+      def max
+        (@options + @commands).map {|i|
+          before_for(i).size
+        }.reject {|i|
+          i > max_left_width
+        }.max
+      end
+
+      # Builds a single line for an Option of the form.
+      #
+      #  before padding   # after
+      #
+      # @param [Option]
+      def build_option_string(opt)
+        before_for(opt) << padding_for(opt) << padding << after_for(opt).rstrip << "\n"
+      end
+
+      # @param opt [Option]
+      # @return [String] Builds the first half of the help string for an Option.
+      def before_for(opt)
+        b = padding(2) << names_for(opt).dup << " " << args_for(opt)
+        b << "\n" if b.size > max_left_width
+        b
+      end
+
+      # @return [String] Padding for between an Option's #before and #after.
+      def padding_for(opt)
+        width = left_width - before_for(opt).clear_colours.split("\n").last.size
+        if width >= 0
+          ' ' * width
+        else
+          ' ' * left_width
+        end
+      end
+
+      # @param opt [Option]
+      # @return [String] Builds the second half of the help string for an Option.
+      def after_for(opt)
+        r = ""
+        after = description_for(opt).dup << " " << choices_for(opt)
+        unless after == " "
+          r << "# "
+          r << Output.wrap_text(after, left_width + padding(2).size, @opts[:width])
+        end
+        r
+      end
+
+      def names_for(opt)
+        opt.to_s
+      end
+
+      def description_for(opt)
+        opt.description
+      end
+
+      def args_for(opt)
+        if opt.args != [] && !opt.config[:boolean] == true
+          opt.args.to_s
+        else
+          ""
+        end
+      end
+
+      def choices_for(opt)
+        if opt.args.size == 1 && !opt.args.first.choice_str.empty?
+          opt.args.first.choice_str
+        else
+          ""
+        end
+      end
+
+    end
+  end
+end