clive 0.8.1 → 1.0.0

data/lib/clive.rb

@@ -1,64 +1,144 @@
-require 'ast_ast'
-require 'attr_plus'
+$: << File.dirname(__FILE__)
 
-require 'clive/parser'
-require 'clive/exceptions'
-require 'clive/tokens'
+require 'clive/error'
+require 'clive/output'
+require 'clive/version'
+require 'clive/struct_hash'
+require 'clive/formatter'
+require 'clive/formatter/plain'
+require 'clive/formatter/colour'
 
+require 'clive/type'
+require 'clive/argument'
+require 'clive/arguments'
+require 'clive/arguments/parser'
+require 'clive/option/runner'
 require 'clive/option'
 require 'clive/command'
-require 'clive/switch'
-require 'clive/flag'
-require 'clive/bool'
+require 'clive/parser'
+require 'clive/base'
 
-require 'clive/output'
-require 'clive/formatter'
 
-# Clive is a simple dsl for creating command line interfaces
+# Clive is a DSL for creating command line interfaces. Generally to use it you
+# will inherit from it with your own class.
+#
+#   class CLI < Clive
+#     opt :working, 'Test if it is working' do
+#       puts "YEP!".green
+#     end
+#   end
 #
-# @example Simple Example
+#   CLI.run ARGV
 #
-#   require 'clive'
+#   # app.rb --working
+#   #=> "YEP!"
 #
-#   class CLI
-#     include Clive::Parser
-#     
-#     desc 'A switch'
-#     switch :s, :switch do
-#       puts "You used a switch"
-#     end
-#     
-#     desc 'A flag'
-#     flag :hello, :args => "NAME" do |name|
-#       puts "Hello, #{name}"
-#     end
-#     
-#     desc 'True or false'
-#     bool :which do |which|
-#       case which
-#       when true
-#         puts "true, yay"
-#       when false
-#         puts "false, not yay"
-#       end
-#     end
-#     
-#     option_list :purchases
-#     
-#     command :new, :buy do
-#       switch :toaster do
-#         purchases << :toaster
-#       end
-#       
-#       switch :tv do
-#         purchases << :tv
-#       end
+# But it is possible to create a new instance of Clive instead in almost the
+# same way.
+#
+#   cli = Clive.new do
+#     opt :working, 'Test if it is working' do
+#       puts "YEP!".green
 #     end
-#     
 #   end
 #
-#   CLI.parse(ARGV)
+#  cli.run ARGV
+#
+# For very small tasks where you _just_ need to collect options passed and query
+# about them you can use the {Kernel#Clive} method.
+#
+#   r = Clive(:quiet, :verbose).run(ARGV)
+#
+#   $log = Logger.new(STDOUT)
+#   $log.level = Logger::FATAL if r.quiet
+#   $log.level = Logger::DEBUG if r.verbose
 #
-module Clive
-  
+#   # do some stuff
+#
+class Clive
+
+  extend Type::Lookup
+
+  class << self
+    attr_accessor :instance
+
+    # Sets up proxy methods for each relevent method in {Base} to an instance of {Base}.
+    def inherited(klass)
+      klass.instance = Base.new
+
+      str = (Base.instance_methods(false) | Command.instance_methods(false)).map do |sym|
+        <<-EOS
+          def self.#{sym}(*args, &block)
+            instance.send(:#{sym}, *args, &block)
+          end
+        EOS
+      end.join("\n")
+      klass.instance_eval str
+    end
+
+    def method_missing(sym, *args, &block)
+      instance.send(sym, *args, &block)
+    end
+
+    def respond_to_missing?(sym, include_private=false)
+      instance.respond_to?(sym, include_private)
+    end
+
+    unless Kernel.respond_to?(:respond_to_missing?)
+      def respond_to?(sym, include_private=false)
+        respond_to_missing?(sym, include_private)
+      end
+    end
+
+  end
+
+  # This allows you to use Clive without defining a class, but while keeping all
+  # of the control.
+  #
+  # There is one caveat though when using this style: types can not be
+  # referenced with just the type name. Instead the full class path/name must be
+  # given. So instead of using +opt :num, as: Integer+ you need to use +opt
+  # :num, as: Clive::Type::Integer+, and similarly for all types.
+  #
+  # @param opts [Hash] Options to create with, see {Base#initialize}
+  # @example
+  #
+  #   c = Clive.new { opt :v, :verbose }
+  #   r = c.run ARGV
+  #
+  def self.new(opts={}, &block)
+    Base.new(opts, &block)
+  end
+
+end
+
+module Kernel
+
+  # The quickest way to grab a few options. This form does not allow arguments or
+  # commands! It is meant to be quick and simple.
+  #
+  # @example
+  #
+  #   r = Clive(:verbose, [:b, :bare]).run(%w(--verbose))
+  #   r.bare     #=> false
+  #   r.verbose  #=> true
+  #
+  #
+  #   # The above example is equivalent to
+  #   r = Clive.new {
+  #     opt :verbose
+  #     opt :b, :bare
+  #   }.run(%w(--verbose))
+  #
+  # @param names [#to_sym, Array<#to_sym>] List of names to create options for
+  # @return [Clive] A clive instance setup with the correct options
+  #
+  def Clive(*names)
+    c = Clive::Base.new
+    names.each do |o|
+      c.option *Array(o).map(&:to_sym)
+    end
+    c
+  end
+
 end

data/lib/clive/argument.rb

@@ -0,0 +1,170 @@
+class Clive
+
+  # An Argument represents an argument for an Option or Command, it can be optional
+  # and can also be constricted by various other values, see {#initialize}.
+  class Argument
+
+    # Creates an object which will respond with true to all call to the method(s)
+    # given.
+    #
+    # @example
+    #   eg = AlwaysTrue.for(:a, :b, :c)
+    #   eg.a          #=> true
+    #   eg.b(1,2,3)   #=> true
+    #   eg.c { 1 }    #=> true
+    #   eg.d          #=> NoMethodError
+    #
+    class AlwaysTrue
+
+      # @param syms [Symbol] Methods which should return true
+      def self.for(*syms)
+        c = Class.new
+        syms.each do |sym|
+          c.send(:define_method, sym) {|*a| true }
+        end
+        c.send(:define_method, :inspect) { "#<AlwaysTrue #{syms.map {|i| ":#{i}" }.join(', ') }>" }
+        c.new
+      end
+    end
+
+    # An Argument will have these traits by default.
+    DEFAULTS = {
+      :optional   => false,
+      :type       => Type::Object,
+      :match      => AlwaysTrue.for(:match),
+      :within     => AlwaysTrue.for(:include?),
+      :default    => nil,
+      :constraint => AlwaysTrue.for(:call)
+    }
+
+    attr_reader :name, :default, :type
+
+    # A new instance of Argument.
+    #
+    # @param opts [Hash]
+    #
+    # @option opts [#to_sym] :name
+    #   Name of the argument.
+    #
+    # @option opts [Boolean] :optional
+    #   Whether this argument is optional. An optional argument does not have
+    #   to be given and will pass +:default+ to the block instead.
+    #
+    # @option opts [Type] :type
+    #   Type that the matching argument should be cast to. See {Type} and the
+    #   various subclasses for details. Each {Type} defines something that the
+    #   argument must match in addition to the +:match+ argument given.
+    #
+    # @option opts [#match] :match
+    #   Regular expression the argument must match.
+    #
+    # @option opts [#include?] :within
+    #   Collection that the argument should be in. This will be checked
+    #   against the string argument and the cast object (see +:type+). So for
+    #   instance if +:type+ is set to +Integer+ you can set +:within+ to be an array
+    #   of integers, [1,2,3], or an array of strings, %w(1 2 3), and get the
+    #   same result.
+    #
+    # @option opts :default
+    #   Default value the argument takes. This is only set or used if the Option or
+    #   Command is actually called.
+    #
+    # @option opts [#call, #to_proc] :constraint
+    #   Proc which is passed the found argument and should return +true+ if the
+    #   value is ok and false if not.
+    #   If the object responds to #to_proc this will be called and the resulting
+    #   Proc object saved for later use. This allows you to pass method symbols.
+    #
+    # @example
+    #
+    #   Argument.new(:arg, :optional => true, :type => Integer, :constraint => :odd?)
+    #
+    def initialize(name, opts={})
+      @name = name.to_sym
+
+      opts[:constraint] = opts[:constraint].to_proc if opts[:constraint].respond_to?(:to_proc)
+      opts = DEFAULTS.merge(opts)
+
+      @optional   = opts[:optional]
+      @type       = Type.find_class(opts[:type].to_s) rescue opts[:type]
+      @match      = opts[:match]
+      @within     = opts[:within]
+      @default    = opts[:default]
+      @constraint = opts[:constraint]
+    end
+
+    # @return Whether the argument is optional.
+    def optional?
+      @optional
+    end
+
+    # @return [String] String representation for the argument.
+    def to_s
+      optional? ? "[<#@name>]" : "<#@name>"
+    end
+
+    # @return [String]
+    #  Choices or range of choices that can be made, for the help string.
+    def choice_str
+      if @within
+        case @within
+        when Array
+          '(' + @within.join(', ') + ')'
+        when Range
+          '(' + @within.to_s + ')'
+        else
+          ''
+        end
+      else
+        ''
+      end
+    end
+
+    def inspect
+      "#<#{self.class} #{to_s}>"
+    end
+
+    # Determines whether the object given can be this argument. Checks whether
+    # it is valid based on the options passed to {#initialize}.
+    #
+    # @param obj [String, Object]
+    #   This method will be called at least twice for each argument, the first
+    #   time when testing for {Arguments#possible?} and then for {Arguments#valid?}.
+    #   When called in {Arguments#possible?} +obj+ will be passed as a string,
+    #   for {Arguments#valid?} though +obj+ will have been cast using {#coerce}
+    #   to the correct type meaning this method must deal with both cases.
+    #
+    # @return Whether +obj+ could be this argument.
+    #
+    def possible?(obj)
+      return false if obj.is_a?(String) && !@type.valid?(obj)
+      return false unless @match.match(obj.to_s)
+
+      coerced = coerce(obj)
+
+      unless @within.include?(obj.to_s) || @within.include?(coerced)
+        return false
+      end
+
+      begin
+        return false unless @constraint.call(obj.to_s)
+      rescue
+        begin
+          return false unless @constraint.call(coerced)
+        rescue
+          return false
+        end
+      end
+
+      true
+    end
+
+    # Converts the given String argument to the correct type determined by the
+    # +:type+ passed to {#initialize}.
+    def coerce(str)
+      return str unless str.is_a?(String)
+      @type.typecast(str)
+    end
+  end
+
+end

data/lib/clive/arguments.rb

@@ -0,0 +1,139 @@
+class Clive
+  # An Array of {Clive::Argument} instances.
+  class Arguments < Array
+
+    # @example
+    #
+    #   ArgumentList.create :args => '<a> [<b>]', :as => [Integer, String]
+    #   #=> #<ArgumentList ...>
+    #
+    def self.create(opts)
+      new Parser.new(opts).to_args
+    end
+
+    # Zips a list of found arguments to this ArgumentList, but it also takes
+    # account of whether the found argument is possible and makes sure that
+    # optional Arguments are correctly handled.
+    #
+    # @example
+    #
+    #   a = Argument.new(:a, type: Integer, constraint: :even?, optional: true)
+    #   b = Argument.new(:b, type: Integer, constraint: :odd?)
+    #   c = Argument.new(:c, type: Integer, constraint: :even?)
+    #   d = Argument.new(:d, type: Integer, constraint: :odd?, optional: true)
+    #
+    #   list = ArgumentList.new([a, b, c, d])
+    #   found_args = %w(1 2 3)
+    #
+    #   list.zip(found_args).map {|i| [i[0].to_s, i[1]] }
+    #   #=> [['[<a>]', nil], ['<b>', 1], ['<c>', 2], ['[<d>]', 3]]
+    #
+    #
+    # @param other [Array<String>] Found list of arguments.
+    # @return [Array<Argument,String>]
+    #
+    def zip(other)
+      other = other.dup.compact
+      # Find the number of 'spares'
+      diff = other.size - find_all {|i| !i.optional? }.size
+      r = []
+
+      map do |arg|
+        if arg.possible?(other.first)
+          if arg.optional?
+            if diff > 0
+              [arg, other.shift]
+            else
+              [arg, nil]
+            end
+          else
+            [arg, other.shift]
+          end
+        else
+          [arg, nil]
+        end
+      end
+    end
+
+    # @return [String]
+    def to_s
+      map {|i| i.to_s }.join(' ').gsub('] [', ' ')
+    end
+
+    # @return [Integer] The minimum number of arguments that *must* be given.
+    def min
+      reject {|i| i.optional? }.size
+    end
+
+    # @return [Integer] The maximum number of arguments that *can* be given.
+    def max
+      size
+    end
+
+    # Whether the +list+ of found arguments could possibly be the arguments for
+    # this option. This does not need to check the minimum length as the list
+    # may not be completely built, this just checks it hasn't failed completely.
+    #
+    # @param list [Array<Object>]
+    def possible?(list)
+      return true if list.empty?
+      i = 0
+      optionals = []
+
+      list.each do |item|
+        break if i >= size
+
+        # Either, +item+ is self[i]
+        if self[i].possible?(item)
+          i += 1
+
+        # Or, the argument is optional and there is another argument to move to
+        # meaning it can be skipped
+        elsif self[i].optional? && (i < size - 1)
+          i += 1
+          optionals << item
+
+        # Or, an optional argument has been skipped and this could be it so bring
+        # it back from the dead and check, if it is remove it and move on
+        elsif optionals.size > 0 && self[i].possible?(optionals.first)
+          i += 1
+          optionals.shift
+
+        # Problem
+        else
+          return false
+        end
+      end
+
+      list.size <= max
+    end
+
+    # Whether the +list+ of found arguments is valid to be the arguments for this
+    # option. Here length is checked as we need to make sure enough arguments are
+    # present.
+    #
+    # It is important that when the arguments are put in the correct place
+    # that we check for missing arguments (which have been added as +nil+s)
+    # so compact the list _then_ check the size.
+    #
+    # @param list [Array<Object>]
+    def valid?(list)
+      zip(list).map do |a,i|
+        if a.optional?
+          nil
+        else
+          i
+        end
+      end.compact.size >= min && possible?(list)
+    end
+
+    # Will fill spaces in +list+ with default values, then coerces all arguments
+    # to the corect types.
+    #
+    # @return [Array]
+    def create_valid(list)
+      zip(list).map {|a,r| r ? a.coerce(r) : a.coerce(a.default) }
+    end
+
+  end
+end