clive 0.8.1 → 1.0.0

data/lib/clive/parser.rb

@@ -1,104 +1,197 @@
-module Clive
-
-  # A module wrapping the command line parsing of clive. In the future this
-  # will be the only way of using clive.
-  #
-  # @example
-  #
-  #   require 'clive'
-  # 
-  #   class CLI
-  #     include Clive::Parser
-  #     option_hash :opts
-  #   
-  #     switch :v, :verbose, "Run verbosely" do
-  #       opts[:verbose] = true
-  #     end
-  #   end
-  #
-  #   CLI.parse ARGV
-  #   p CLI.opts
-  #
-  module Parser
-    
-    # When the module is included we need to keep track of the new class it
-    # is now in and we need to create a new base command. So here instance 
-    # variables are set directly in the new class, and the class is made to
-    # extend the methods in Parser so they are available as class methods.
-    # 
-    def self.included(klass)
-      klass.instance_variable_set("@klass", klass)
-      klass.extend(self)
-      klass.instance_variable_set "@base", Clive::Command.setup(klass)
+class Clive
+
+  class Parser
+
+    class MissingArgumentError < Error
+      reason 'missing argument for #0, found #1, needed #2'
+    end
+
+    class MissingOptionError < Error
+      reason 'option could not be found: #0'
     end
-    
-    # @return [Clive::Command]
-    #   The base command to forward method calls to.
+
+    DEFAULTS = {
+      :state => ::Clive::StructHash
+    }
+
+    # @param base [Command]
     #
-    def base; @base; end
-    
-    # @see Clive::Command#run
-    def parse(argv)
-      base.run(argv)
+    # @param config [Hash]
+    # @option config [.new, #[], #[]=, #alias] :state
+    #   What class the state should be
+    def initialize(base, config)
+      @base = base
+      @config = DEFAULTS.merge(config)
     end
-    
-    # @see Clive::Command#flag
-    def flag(*args, &block)
-      base.flag(*args, &block)
+
+    # The parser should work how you expect. It allows you to put global options before and after
+    # a command section (if it exists, which it doesn't), so you have something like.
+    #
+    #    my_app.rb [global options] ([command] [options] [args]) [g. options] [g. args] [g. options] etc.
+    #            |  global section  |    command section       |      global section
+    #
+    # Only one command can be run, if you attempt to use two the other will be caught as an argument.
+    #
+    # @param argv [Array]
+    #   The input to parse from the command line, usually ARGV.
+    #
+    # @param pre_state [Hash]
+    #   A pre-populated state to be used.
+    #
+    def parse(argv, pre_state)
+      @argv = argv
+      @i    = 0
+
+      @state = @config[:state].new(pre_state)
+      @state.store :args, []
+
+      # Pull out 'help' command immediately if found
+      if @argv[0] == 'help'
+        if @argv[1]
+          if @base.has?(@argv[1])
+            command = @base.find(@argv[1])
+            command.run_block({})
+            puts command.help
+          else
+            puts "Error: command #{@argv[1]} could not be found. Try `help` to see the available commands."
+          end
+        else
+          puts @base.help
+        end
+      end
+
+      until ended?
+        # does +curr+ exist? (and also check that if it is a command a command hasn't been run yet
+        if @base.has?(curr) && ((@base.find(curr).kind_of?(Command) && !command_ran?) || @base.find(curr).kind_of?(Option))
+
+          found = @base.find(curr)
+
+          # is it a command?
+          if found.kind_of?(Command)
+            @command_ran = true
+            @state.store found.names, found.run_block(@config[:state].new)
+
+            inc
+            args = []
+
+            until ended?
+              if found.has?(curr)
+                run_option found.find(curr), found
+              else
+                break unless found.args.possible?(args + [curr])
+                args << curr
+              end
+              inc
+            end
+            dec
+
+            found.run @state, validate_arguments(found, args), found
+
+          # otherwise it is an option
+          else
+            run_option found
+          end
+
+        # it's a no- option
+        elsif curr[0..4] == '--no-' && @base.find("--#{curr[5..-1]}").config[:boolean] == true
+          @base.find("--#{curr[5..-1]}").run @state, [false]
+
+        # it's one (or more) short options
+        elsif curr[0..0] == '-' && curr.size > 2 && @base.has?("-#{curr[1..1]}")
+          currs = curr[1..-1].split('').map {|i| "-#{i}" }
+
+          currs.each do |c|
+            opt = @base.find(c)
+            raise MissingOptionError.new(c) unless opt
+
+            if c == currs.last
+              run_option opt
+            else
+              # can't take any arguments as an option is next to it
+              if opt.args.min > 0
+                raise MissingArgumentError.new(opt, [], opt.args)
+              else
+                opt.run @state, [true]
+              end
+            end
+          end
+
+        # otherwise it is an argument
+        else
+          @state.args << curr
+        end
+
+        inc
+      end
+
+      @state
     end
-    
-    # @see Clive::Command#switch
-    def switch(*args, &block)
-      base.switch(*args, &block)
+
+
+    private
+
+    def run_option(opt, within=nil)
+      args = opt.args.max > 0 ? do_arguments_for(opt) : [true]
+      opt.run @state, args, within
     end
-    
-    # @see Clive::Command#command
-    def command(*args, &block)
-      base.command(*args, &block)
+
+    # Increment the index
+    def inc
+      @i += 1
     end
-    
-    # @see Clive::Command#bool
-    def bool(*args, &block)
-      base.bool(*args, &block)
+
+    # Decrement the index
+    def dec
+      @i -= 1
     end
-    
-    # @see Clive::Command#desc
-    def desc(*args)
-      base.desc(*args)
+
+    # @return [String] The current token
+    def curr
+      @argv[@i]
     end
-    
-    # @see Clive::Command#help_formatter
-    def help_formatter(*args, &block)
-      base.help_formatter(*args, &block)
+
+    # Whether the index is at the end of the argv
+    def ended?
+      @i >= @argv.size
     end
-    
-    # This is a bit nicer, I think, for defining CLIs.
-    def option_var(name, value=nil)
-      if value
-        @klass.class_attr_accessor name => value
-      else
-        @klass.class_attr_accessor name
-      end
+
+    def command_ran?
+      @command_ran || false
     end
-    
-    # Create a new hash which is accessible to the options in the new class
-    # but can also be accessed from outside the class. Defines getters and 
-    # setters for the symbols given, and sets their initial value to +{}+.
-    #
-    # @param args [Symbol]
-    #
-    def option_hash(*args)
-      args.each do |arg|
-        option_var(arg, {})
+
+    # Returns the finished argument list for +opt+ which can then be pushed to the state.
+    def do_arguments_for(opt)
+      arg_list = collect_arguments(opt)
+      arg_list = validate_arguments(opt, arg_list)
+
+      arg_list
+    end
+
+    # Collects the arguments for +opt+.
+    def collect_arguments(opt)
+      inc
+      arg_list = []
+      while !ended? && arg_list.size < opt.args.max
+        break unless opt.args.possible?(arg_list + [curr])
+        arg_list << curr
+        inc
       end
+      dec
+      arg_list
     end
-    
-    def option_array(*args)
-      args.each do |arg|
-        option_var(arg, [])
+
+    # Makes sure the found list of arguments is valid, if not raises
+    # MissingArgumentError. Returns the valid argument list with the arguments
+    # as the correct type, in the correct positions and with default values
+    # inserted if necessary.
+    def validate_arguments(opt, arg_list)
+      # If we don't have enough args
+      unless opt.args.valid?(arg_list)
+        raise MissingArgumentError.new(opt, arg_list, opt.args.to_s)
       end
+
+      opt.args.create_valid(arg_list)
     end
-    alias_method :option_list, :option_array
 
   end
 end

data/lib/clive/struct_hash.rb

@@ -0,0 +1,109 @@
+class Clive
+
+  # A Struct-like Hash (or Hash-like Struct)
+  #
+  #   sh = StructHash.new(:a => 1)
+  #   sh.a       #=> 1
+  #   sh[:a]     #=> 1
+  #
+  #   sh.set 42, [:answer, :life]
+  #   sh.answer  #=> 42
+  #   sh.life    #=> 42
+  #
+  #   sh.to_h
+  #   #=> {:a => 1, :answer => 42}
+  #   sh.to_struct('Thing')
+  #   #=> #<struct Struct::Thing @a=1 @answer=42>
+  #
+  class StructHash
+
+    alias_method :__respond_to?, :respond_to?
+
+    skip_methods = %w(object_id respond_to_missing? inspect === to_s class)
+    instance_methods.each do |m|
+      undef_method m unless skip_methods.include?(m.to_s) || m =~ /^__/
+    end
+
+    def initialize(kvs={})
+      @data = kvs
+      @aliases = Hash[ kvs.map {|k,v| [k, k] } ]
+    end
+
+    # Sets a value in the StructHash, this can be set with multiple keys but the
+    # first will be set as the most important key, the others will not show up in
+    # #to_h or #to_struct.
+    #
+    # @param keys [#to_sym, Array<#to_sym>]
+    # @param val
+    def store(keys, val)
+      keys = Array(keys).map(&:to_sym)
+
+      keys.each do |key|
+        @aliases[key] = keys.first
+      end
+
+      @data[keys.first] = val
+    end
+
+    # Gets the value from the StructHash corresponding to the key given.
+    #
+    # @param key [Symbol]
+    def fetch(key)
+      @data.fetch @aliases[key]
+    end
+    alias_method :[], :fetch
+
+    # Checks whether the StructHash contains an entry for the key given.
+    def key?(key)
+      @aliases.key? key
+    end
+
+    # @return [Hash] The data without the +:args+ key.
+    def data
+      @data.reject {|k,v| k == :args }
+    end
+
+    # Returns a hash representation of the StructHash instance, using only the
+    # important keys. This acts recursively, so any contained StructHashes
+    # will have #to_h called on them.
+    #
+    # @return [Hash]
+    def to_h
+      Hash[ data.map {|k,v| v.is_a?(StructHash) ? [k, v.to_h] : [k, v] } ]
+    end
+    alias_method :to_hash, :to_h
+
+    # Returns a struct representation of the StructHash instance, using only the
+    # important keys. This does not modify any contained StructHash instances
+    # like #to_h, but leaves them as they are.
+    #
+    # @return [Struct]
+    def to_struct(name=nil)
+      Struct.new(name, *data.keys).new *data.values
+    end
+
+    # Checks whether the method corresponds to a key, if so gets the value.
+    # Checks whether the method ends with '?', then checks if the key exists.
+    # Otherwise calls super.
+    def method_missing(sym, *args, &block)
+      if key?(sym)
+        fetch sym
+      elsif sym.to_s[-1..-1] == "?"
+        key? sym.to_s[0..-2].to_sym
+      else
+        super sym, *args, &block
+      end
+    end
+
+    def respond_to?(sym, include_private=false)
+      return true if key?(sym)
+      return true if sym.to_s[-1..-1] == "?" && key?(sym.to_s[0..-2].to_sym)
+      return __respond_to?(sym, include_private)
+    end
+
+    def ==(other)
+      to_h == other.respond_to?(:to_h) ? other.to_h : other
+    end
+
+  end
+end

data/lib/clive/type.rb

@@ -0,0 +1,117 @@
+class Clive
+  class Type
+
+    # @param arg [::String]
+    def valid?(arg)
+      false
+    end
+
+    # @param arg [::String]
+    def typecast(arg)
+      nil
+    end
+
+    class << self
+
+      # Find the class for +name+.
+      # @param name [::String]
+      def find_class(name)
+        name = name.split('::').last
+        Clive::Type.const_get(name) if Clive::Type.const_defined?(name)
+      end
+
+      # Shorthand to define #valid? for subclasses of {Type}, pass a
+      # regular expression that should be matched or a symbol for a
+      # method which will be called on the argument that returns either
+      # +true+ (valid) or +false+ (invalid).
+      #
+      # @param other [#to_proc, ::Regexp]
+      #
+      # @example With a regular expression
+      #
+      #   class YesNo < Type
+      #     match /yes|no/
+      #     # ...
+      #   end
+      #
+      # @example With a method symbol
+      #
+      #   class String
+      #     def five?
+      #       size == 5
+      #     end
+      #   end
+      #
+      #   class FiveChars < Type
+      #     match :five?
+      #     # ...
+      #   end
+      #
+      def match(other)
+        if other.respond_to?(:to_proc)
+          @valid = other.to_proc
+        else
+          @valid = proc {|arg| other =~ arg.to_s }
+        end
+      end
+
+      # Similar to {.match} but opposite, so where {.match} would be valid
+      # refute is invalid.
+      #
+      # @param other [#to_proc, ::Regexp]
+      def refute(other)
+        if other.respond_to?(:to_proc)
+          @valid = proc {|arg| !arg.send(other) }
+        else
+          @valid = proc {|arg| other !~ arg.to_s }
+        end
+      end
+
+      # Shorthand to define a method which is called on the string argument
+      # to return the correct type.
+      #
+      # @param sym [::Symbol]
+      #
+      # @example
+      #
+      #   class Symbol < Type
+      #     # ...
+      #     cast :to_sym
+      #   end
+      #
+      def cast(sym, *args)
+        @cast = [sym, args]
+      end
+
+      # Checks whether the +arg+ passed is valid, if {.match} or {.refute}
+      # have been called it uses the Proc created by them otherwise calls
+      # {#valid?}.
+      #
+      # @param arg [::String]
+      def valid?(arg)
+        if @valid
+          @valid.call arg
+        else
+          new.valid? arg
+        end
+      end
+
+      # Casts the +arg+ to the correct type, if {.cast} has been called it
+      # uses the proc created otherwise it calls {#typecast}.
+      #
+      # @param arg [::String]
+      def typecast(arg)
+        if @cast
+          arg.send @cast[0], *@cast[1]
+        else
+          new.typecast arg
+        end
+      end
+
+    end
+
+  end
+end
+
+require 'clive/type/definitions'
+require 'clive/type/lookup'