clive 0.8.1 → 1.0.0

data/lib/clive/option.rb

@@ -1,100 +1,210 @@
-module Clive
-  
-  # @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.
+class Clive
+
+  # An option saves a value to the state or triggers a block if given when used.
+  # They can have a long, +--opt+, and/or short, +-o+ and can take arguments
+  # which can be constricted by passing various parameters.
   #
-  # 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 CLI < Clive
+  #     VERSION = '0.0.1'
+  #
+  #     desc 'Name of the person'
+  #     opt :name, arg: '<first> [<middle>] <last>'
+  #
+  #     opt :v, :version do
+  #       puts CLI::VERSION
+  #     end
+  #   end
+  #
+  # You can also have boolean options, created with the +bool+ or +boolean+
+  # method which are simply Options with :boolean set to true. You can pass the
+  # option name as normal to set them to true or prepend +--no-+ to the name to
+  # set them to false.
+  #
+  #   class CLI
+  #     bool :auto, 'Auto regenerate person on change'
+  #   end
   #
   class Option
-    attr_accessor :names, :desc, :block
-    
-    # Create a new Option instance. 
+
+    class InvalidNamesError < Error
+      reason '#1'
+    end
+
+    extend Type::Lookup
+
+    # @return [Array<Symbol>] List of names this Option can be called
+    attr_reader :names
+    # @return [Hash{Symbol=>Object}] Config options passed to {#initialize}
+    #   using defaults when not given
+    attr_reader :config
+    # @return [Arguments] List of arguments this Option can take when ran
+    attr_reader :args
+    # @return [String] Description of the Option
+    attr_reader :description
+
+    # Default values to use for +config+. These are also the config options that
+    # an Option takes, see {#initialize} for details.
+    DEFAULTS = {
+      :boolean => false,
+      :group   => nil,
+      :head    => false,
+      :tail    => false,
+      :runner  => Clive::Option::Runner
+    }
+
+    # @param names [Array<Symbol>]
+    #   Names for this option
     #
-    # For subclasses the method call should take the form:
-    # +initialize(names, desc, [special args], &block)+.
+    # @param description [String]
+    #   Description of the option.
     #
-    # @param names [Array[Symbol]]
-    #   An array of names the option can be invoked by.
+    # @param config [Hash]
+    # @option config [true, false] :head
+    #   If option should be at top of help list
+    # @option config [true, false] :tail
+    #   If option should be at bottom of help list
+    # @option config [String] :args
+    #   Arguments that the option takes. See {Argument}.
+    # @option config [Type, Array[Type]] :as
+    #   The class the argument(s) should be cast to. See {Type}.
+    # @option config [#match, Array[#match]] :match
+    #   Regular expression that the argument(s) must match
+    # @option config [#include?, Array[#include?]] :in
+    #   Collection that argument(s) must be in
+    # @option config :default
+    #   Default value that is used if argument is not given
+    # @option config :group
+    #   Name of the group this option belongs to
     #
-    # @param desc [String]
-    #   A description of what the option does.
+    # @example
     #
-    # @yield A block to run if the switch is triggered
+    #   Option.new(
+    #     [:N, :new],
+    #     "Add a new thing",
+    #     {:args => "<dir> [<size>]", :matches => [/^\//], :types => [nil, Integer]}
+    #   )
     #
-    def initialize(names, desc, &block)
-      @names = names.map(&:to_s)
-      @desc  = desc
+    def initialize(names=[], description="", config={}, &block)
+      @names = names.sort_by {|i| i.to_s.size }
+
+      # @return [Symbol, nil] Short name from the names (ie. +:a+)
+      def @names.short
+        find {|i| i.to_s.size == 1 }
+      end
+
+      # @return [Symbol, nil] Long name from the names (ie. +:abc+)
+      def @names.long
+        find {|i| i.to_s.size > 1 }
+      end
+
+      @description  = description
       @block = block
+
+      @args = Arguments.create( get_subhash(config, Arguments::Parser::KEYS.keys) )
+      @config = DEFAULTS.merge( get_subhash(config, DEFAULTS.keys) || {} )
     end
-    
-    # Calls the block.
-    def run
-      @block.call
+
+    # @return [Symbol] The longest name given
+    def name
+      @names.long || @names.short
     end
-    
-    # Convert the names to strings, if name is single character appends
-    # +-+, else appends +--+.
-    #
-    # @param bool [Boolean] whether to add [no-] to long
-    #
-    # @example
-    #
-    #   @names = ['v', 'verbose']
-    #   names_to_strings
-    #   #=> ['-v', '--verbose']
-    #
-    def names_to_strings(bool=false)
-      r = []
-      @names.each do |i|
-        next if i.nil?
-        if i.length == 1 # short
-          r << "-#{i}"
-        else # long
-          if bool
-            r << "--[no-]#{i}"
-          else
-            r << "--#{i}"
-          end
-        end
+
+    # @return [String] String representaion of the Option
+    def to_s
+      r = ""
+      r << "-#{@names.short}" if @names.short
+      if @names.long
+        r << ", " if @names.short
+        r << "--"
+        r << "[no-]" if @config[:boolean] == true
+        r << @names.long.to_s.gsub('_', '-')
       end
+
       r
     end
-    
-    # Tries to get the short name, if not chooses lowest alphabetically.
-    #
-    # @return [String] name to sort by
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} #{to_s}>"
+    end
+
+    # @return Whether a block was given.
+    def block?
+      @block != nil
+    end
+
+    # Runs the Option's block with the current state and arguments passed.
     #
-    def sort_name
-      r = @names.sort[0]
-      @names.each do |i|
-        if i.length == 1
-          r = i
+    # @param state [Hash] Local state for parser, this may be modified!
+    # @param args [Array] Arguments for the block which is run
+    # @param scope [Command] Scope of the state to use
+    # @return [Hash] the state which may have been modified!
+    def run(state, args=[], scope=nil)
+      mapped_args = if @config[:boolean] == true
+        [[:truth, args.first]]
+      else
+        @args.zip(args).map {|k,v| [k.name, v] }
+      end
+
+      if block?
+        if scope
+          state = @config[:runner]._run(mapped_args, state[scope.name], @block)
+        else
+          state = @config[:runner]._run(mapped_args, state, @block)
         end
+      else
+        state = set_state(state, args, scope)
       end
-      r
+
+      state
     end
-    
-    # Compare options based on Option#sort_name
+
+    include Comparable
+
+    # Compare based on the size of {#name}, makes sure tails go to the bottom
+    # and heads go to the top. If both are head or tail then sorts based on the
+    # names.
+    #
+    # @param other [Option] Option to compare with
+    # @return [Integer] Either -1, 0 or 1
     def <=>(other)
-      self.sort_name <=> other.sort_name
+      if (config[:tail] && !other.config[:tail]) ||
+          (other.config[:head] && !config[:head])
+        1
+      elsif (other.config[:tail] && !config[:tail]) ||
+          (config[:head] && !other.config[:head])
+        -1
+      else
+        self.name.to_s <=> other.name.to_s
+      end
     end
-    
-    # @return [Hash{String=>Object}]
-    #   Returns a hash which can be passed to the help formatter.
+
+
+    private
+
+    # Sets a value in the state.
     #
-    def to_h
-      {
-        "names" => names_to_strings,
-        "desc"  => @desc
-      }
+    # @param state [#store, #[]]
+    # @param args [Array]
+    # @param scope [Symbol, nil]
+    def set_state(state, args, scope=nil)
+      args = (@args.max <= 1 ? args[0] : args)
+
+      if scope
+        state[scope.name].store [@names.long, @names.short].compact, args
+      else
+        state.store [@names.long, @names.short].compact, args
+      end
+
+      state
     end
-    
-    def inspect
-      "#<#{self.class.name} [#{@names.join(', ')}]>"
+
+    # @param hash [Hash]
+    # @param keys [Array]
+    def get_subhash(hash, keys)
+      Hash[ hash.find_all {|k,v| keys.include?(k) } ]
     end
-  
+
   end
+
 end

data/lib/clive/option/runner.rb

@@ -0,0 +1,163 @@
+class Clive
+
+  # Methods for modifying a state object. Requires that the instance variable
+  # +@state+ exists and that it responds to +#fetch+, +#store+ and +#key?+.
+  module StateActions
+
+    # @param key [Symbol]
+    #
+    # @example
+    #   set :some_key, 1
+    #   opt :get_some_key do
+    #     puts get(:some_key)   #=> 1
+    #   end
+    #
+    def get(key)
+      @state.fetch key
+    end
+
+    # @param key [Symbol]
+    # @param value [Object]
+    #
+    # @example
+    #   opt :set_some_key do
+    #     set :some_key, 1
+    #   end
+    #
+    def set(key, value)
+      @state.store key, value
+    end
+
+    # @overload update(key, method, *args)
+    #   Update the value for +key+ using the +method+ which is passed +args+
+    #   @param key [Symbol]
+    #   @param method [Symbol]
+    #   @param args [Object]
+    #
+    #   @example
+    #     set :list, []
+    #     opt :add, arg: '<item>' do
+    #       update :list, :<<, item
+    #     end
+    #
+    # @overload update(key, &block)
+    #   Update the value for +key+ with a block
+    #   @param key [Symbol]
+    #
+    #   @example
+    #     set :list, []
+    #     opt :add, arg: '<item>' do
+    #       update(:list) {|l| l << item }
+    #     end
+    #
+    def update(*args)
+      if block_given?
+        key = args.first
+        set key, yield(get(key))
+      elsif args.size > 1
+        key, method = args.shift, args.shift
+        set key, get(key).send(method, *args)
+      else
+        raise ArgumentError, "wrong number of arguments (#{args.size} for 2)"
+      end
+    end
+
+    # @param key [Symbol]
+    # @return State has +key+?
+    #
+    # @example
+    #   # test.rb
+    #   set :some_key, 1
+    #   opt(:has_some_key)  { puts has?(:some_key) }
+    #   opt(:has_other_key) { puts has?(:other_key) }
+    #
+    #   # ./test.rb --has-some-key   #=> true
+    #   # ./test.rb --has-other-key  #=> false
+    #
+    def has?(key)
+      @state.key? key
+    end
+
+  end
+
+  class Option
+
+    # Runner is a class which is used for executing blocks given to Options and
+    # Commands. It allows you to inside blocks;
+    # - reference arguments by name (instead of using block params)
+    # - get values from the state hash
+    # - set value to the state hash
+    # - update values in the state hash
+    #
+    # @example Referencing Arguments by Name
+    #
+    #   opt :size, args: '<height> <width>', as: [Float, Float] do # no params!
+    #     puts "Area = #{height} * #{width} = #{height * width}"
+    #   end
+    #
+    # @example Getting Values from State
+    #
+    #   command :new, arg: '<dir>' do
+    #
+    #     opt :type, in: %w(post page blog)
+    #
+    #     action do
+    #       type = has?(:type) ? get(:type) : 'page'
+    #       puts "Creating #{type} in #{dir}!"
+    #     end
+    #
+    #   end
+    #
+    # @example Setting Values to State
+    #
+    #   opt :set, arg: '<key> <value>', as: [Symbol, Object] do
+    #     set key, value
+    #   end
+    #
+    # @example Updating Values in State
+    #
+    #   opt :modify, arg: '<key> <sym> [<args>]', as: [Symbol, Symbol, Array] do
+    #     update key, sym, *args
+    #   end
+    #
+    #
+    class Runner
+      class << self
+
+        # @param args [Array[Symbol,Object]]
+        #   An array is used because with 1.8.7 a hash has unpredictable
+        #   ordering of keys, this means an array is the only way I can be
+        #   sure that the arguments are in order.
+        # @param state [Hash{Symbol=>Object}]
+        # @param fn [Proc]
+        def _run(args, state, fn)
+          return unless fn
+          # order of this doesn't matter as it will just be accessed by key
+          @args = Hash[args]
+          @state = state
+
+          if fn.arity > 0
+            # Remember to use the ordered array version
+            instance_exec(*args.map {|i| i.last }, &fn)
+          else
+            instance_exec(&fn)
+          end
+
+          @state
+        end
+
+        include Clive::StateActions
+
+        # Allows arguments passed in to be referenced directly by name.
+        def method_missing(sym, *args)
+          if @args.has_key?(sym)
+            @args[sym]
+          else
+            super
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/clive/output.rb

@@ -1,18 +1,101 @@
-# This should control the character output to the command line.
-# It will allow you to set different colours, using:
-#
-#   "I'm red".red
-#   "I'm red and bold".red.bold
-#
-#
+class Clive
+  module Output extend self
+  
+    # If the terminal width can't be determined use a sensible default value
+    TERMINAL_WIDTH = 80
+    
+    # @param str [String] String to pad.
+    # @param len [Integer] Length to pad string to.
+    # @param with [String] String to add to +str+.
+    def pad(str, len, with=" ")
+      diff = len - str.clear_colours.size
+      str += with * diff unless diff < 0
+      str
+    end
+
+    # Wraps text. Each line is split by word and then a newline is inserted
+    # when the words exceed the allowed width. Lines after the first will
+    # have +left_margin+ spaces inserted.
+    #
+    # @example
+    #
+    #   Clive::Output.wrap_text("Lorem ipsum dolor sit amet, consectetur 
+    #   adipisicing elit, sed do eiusmod tempor incididunt ut labore et 
+    #   dolore magna aliqua.", 4, 24)
+    #   #=> "Lorem ipsum dolor
+    #   #    sit amet,
+    #   #    consectetur
+    #   #    adipisicing elit,
+    #   #    sed do eiusmod
+    #   #    tempor incididunt ut
+    #   #    labore et dolore
+    #   #    magna aliqua."
+    #
+    # @param str [String] Text to be wrapped
+    # @param left_margin [Integer] Width of space at left
+    # @param width [Integer] Total width of text, ie. from the left 
+    #   of the screen
+    def wrap_text(str, left_margin, width)
+      text_width = width - left_margin
+      
+      words = str.split(" ")
+      r = [""]
+      i = 0
+      
+      words.each do |word|
+        if (r[i] + word).clear_colours.size < text_width
+          r[i] << " " << word
+        else
+          i += 1
+          r[i] = word
+        end
+      end
+      
+      # Clean up strings
+      r.map! {|i| i.strip }
+      
+      ([r[0]] + r[1..-1].map {|i| l_pad(i, left_margin) }).join("\n")
+    end
 
-module Clive
-  module Output
+    # @return [Integer,nil] Width of terminal window, or +nil+ if it cannot be 
+    #   determined.
+    # @see https://github.com/cldwalker/hirb/blob/v0.5.0/lib/hirb/util.rb#L61
+    def terminal_width
+      if (ENV['COLUMNS'] =~ /^\d+$/)
+        ENV['COLUMNS'].to_i
+      elsif (RUBY_PLATFORM =~ /java/ || (!STDIN.tty? && ENV['TERM'])) && command_exists?('tput')
+        `tput cols`.to_i
+      elsif STDIN.tty? && command_exists?('stty')
+        # returns 'height width'
+        `stty size`.scan(/\d+/).last.to_i
+      else
+        TERMINAL_WIDTH
+      end
+    rescue
+      TERMINAL_WIDTH
+    end
+    
+    
+    private
+    
+    # Determines if a shell command exists by searching for it in ENV['PATH'].
+    # @see https://github.com/cldwalker/hirb/blob/v0.5.0/lib/hirb/util.rb#L55
+    def command_exists?(command)
+      ENV['PATH'].split(File::PATH_SEPARATOR).any? {|d| File.exists? File.join(d, command) }
+    end
+    
+    # Same as #pad but adds to the left of +str+.
+    #
+    # @param str [String] String to pad.
+    # @param margin [Integer] Amount of +with+s to add to the left of +str+.
+    # @param with [String] String to pad with.
+    def l_pad(str, margin, with=" ")
+      (with * margin) + str
+    end
   
   end
 end
 
-# Monkey patches for colour
 class String
   
   # @example
@@ -31,8 +114,28 @@ class String
   #
   #   puts "combo".blue.bold.underline.blink
   #
+  # @param code
+  #   Colour code, see http://en.wikipedia.org/wiki/ANSI_escape_code#Colors
+  #
   def colour(code)
-    "#{code}#{self}\e[0m"
+    r = "\e[#{code}m#{self}"
+    r << "\e[0m" unless self[-4..-1] == "\e[0m"
+    r
+  end
+  
+  # Like #colour but modifies the string object.
+  def colour!(code)
+    replace self.colour(code)
+  end
+  
+  # Remove any colour codes from a string.
+  def clear_colours
+    gsub /\e\[?\d\d{0,2}m/, ''
+  end
+  
+  # Same as #clear_colours, but modifies string.
+  def clear_colours!
+    gsub! /\e\[?\d\d{0,2}m/, ''
   end
   
   COLOURS = {
@@ -55,19 +158,32 @@ class String
   
   ATTRIBUTES.each do |name, code|
     define_method name do
-      colour("\e[#{code}m")
+      colour code
+    end
+    
+    define_method "#{name}!" do
+      colour! code
     end
   end
   
   COLOURS.each do |name, code|
     define_method name do
-      colour("\e[3#{code}m")
+      colour "3#{code}"
+    end
+    
+    define_method "#{name}!" do
+      colour! "3#{code}"
     end
     
     define_method "#{name}_bg" do
-      colour("\e[4#{code}m")
+      colour "4#{code}"
     end
     
+    define_method "#{name}_bg!" do
+      colour! "4#{code}"
+    end
+    
+    
     # Change name to grey instead of l_black
     l_name = "l_#{name}"
     if name == "black"
@@ -75,12 +191,21 @@ class String
     end
     
     define_method "#{l_name}" do
-      colour("\e[9#{code}m")
+      colour "9#{code}"
+    end
+    
+    define_method "#{l_name}!" do
+      colour! "9#{code}"
     end
     
     define_method "#{l_name}_bg" do
-      colour("\e[10#{code}m")
+      colour "10#{code}"
+    end
+    
+    define_method "#{l_name}_bg!" do
+      colour! "10#{code}"
     end
 
   end
+  
 end