gli 1.6.0 → 2.0.0.rc3

data/lib/gli/dsl.rb

@@ -0,0 +1,194 @@
+module GLI
+  # The primary DSL for GLI.  This represents the methods shared between your top-level app and
+  # the commands.  See GLI::Command for additional methods that apply only to command objects.
+  module DSL
+    # Describe the next switch, flag, or command.  This should be a
+    # short, one-line description
+    #
+    # +description+:: A String of the short descripiton of the switch, flag, or command following
+    def desc(description); @next_desc = description; end
+    alias :d :desc
+
+    # Provide a longer, more detailed description.  This
+    # will be reformatted and wrapped to fit in the terminal's columns
+    #
+    # +long_desc+:: A String that is s longer description of the switch, flag, or command following.
+    def long_desc(long_desc); @next_long_desc = long_desc; end
+
+    # Describe the argument name of the next flag.  It's important to keep
+    # this VERY short and, ideally, without any spaces (see Example).
+    #
+    # +name+:: A String that *briefly* describes the argument given to the following command or flag.
+    #
+    # Example:
+    #     desc 'Set the filename'
+    #     arg_name 'file_name'
+    #     flag [:f,:filename]
+    #
+    # Produces:
+    #     -f, --filename=file_name      Set the filename
+    def arg_name(name); @next_arg_name = name; end
+
+    # set the default value of the next flag
+    #
+    # +val+:: A String reprensenting the default value to be used for the following flag if the user doesn't specify one
+    #         and, when using a config file, the config also doesn't specify one
+    def default_value(val); @next_default_value = val; end
+
+    # Create a flag, which is a switch that takes an argument
+    #
+    # +names+:: a String or Symbol, or an Array of String or Symbol that represent all the different names
+    #           and aliases for this flag.  The last element can be a hash of options:
+    #           +:desc+:: the description, instead of using #desc
+    #           +:long_desc+:: the long_description, instead of using #long_desc
+    #           +:default_value+:: the default value, instead of using #default_value
+    #           +:arg_name+:: the arg name, instead of using #arg_name
+    #           +:must_match+:: A regexp that the flag's value must match
+    #           +:type+:: A Class (or object you passed to GLI::App#accept) to trigger type coversion
+    #
+    # Example:
+    #
+    #     desc 'Set the filename'
+    #     flag [:f,:filename,'file-name']
+    #
+    #     flag :ipaddress, :desc => "IP Address", :must_match => /\d+\.\d+\.\d+\.\d+/
+    #
+    #     flag :names, :desc => "list of names", :type => Array
+    #
+    # Produces:
+    #
+    #     -f, --filename, --file-name=arg     Set the filename
+    def flag(*names)
+      options = extract_options(names)
+      names = [names].flatten
+
+      verify_unused(names)
+      flag = Flag.new(names,options)
+      flags[flag.name] = flag
+
+      clear_nexts
+      flag
+    end
+    alias :f :flag
+
+    # Create a switch, which is a command line flag that takes no arguments (thus, it _switches_ something on)
+    #
+    # +names+:: a String or Symbol, or an Array of String or Symbol that represent all the different names
+    #           and aliases for this switch.  The last element can be a hash of options:
+    #           +:desc+:: the description, instead of using #desc
+    #           +:long_desc+:: the long_description, instead of using #long_desc
+    #           +:negatable+:: if true, this switch will get a negatable form (e.g. <tt>--[no-]switch</tt>, false it will not.  Default is true
+    def switch(*names)
+      options = extract_options(names)
+      names = [names].flatten
+
+      verify_unused(names)
+      switch = Switch.new(names,options)
+      switches[switch.name] = switch
+
+      clear_nexts
+      switch
+    end
+    alias :s :switch
+
+    def clear_nexts # :nodoc:
+      @next_desc = nil
+      @next_arg_name = nil
+      @next_default_value = nil
+      @next_long_desc = nil
+    end
+
+    # Define a new command.  This can be done in a few ways, but the most common method is
+    # to pass a symbol (or Array of symbols) representing the command name (or names) and a block.  
+    # The block will be given an instance of the Command that was created.
+    # You then may call methods on this object to define aspects of that Command.
+    #
+    # Alternatively, you can call this with a one element Hash, where the key is the symbol representing the name
+    # of the command, and the value being an Array of symbols representing the commands to call in order, as a 
+    # chained or compound command.  Note that these commands must exist already, and that only those command-specific
+    # options defined in *this* command will be parsed and passed to the chained commands.  This might not be what you expect
+    #
+    # +names+:: a String or Symbol, or an Array of String or Symbol that represent all the different names and aliases 
+    #           for this command *or* a Hash, as described above.
+    #
+    # ==Examples
+    #
+    #     # Make a command named list
+    #     command :list do |c|
+    #       c.action do |global_options,options,args|
+    #         # your command code
+    #       end
+    #     end
+    #
+    #     # Make a command named list, callable by ls as well
+    #     command [:list,:ls] do |c|
+    #       c.action do |global_options,options,args|
+    #         # your command code
+    #       end
+    #     end
+    #
+    #     # Make a command named all, that calls list and list_contexts
+    #     command :all => [ :list, :list_contexts ]
+    #
+    #     # Make a command named all, aliased as :a:, that calls list and list_contexts
+    #     command [:all,:a] => [ :list, :list_contexts ]
+    #
+    def command(*names)
+      command_options = {
+        :description => @next_desc,
+        :arguments_name => @next_arg_name,
+        :long_desc => @next_long_desc,
+        :skips_pre => @skips_pre,
+        :skips_post => @skips_post,
+      }
+      if names.first.kind_of? Hash
+        command = GLI::Commands::CompoundCommand.new(self,
+                                                     names.first,
+                                                     command_options)
+        command.parent = self
+        commands[command.name] = command
+      else
+        command = Command.new(command_options.merge(:names => [names].flatten))
+        command.parent = self
+        commands[command.name] = command
+        yield command
+      end
+      clear_nexts
+    end
+    alias :c :command
+
+    private
+    # Checks that the names passed in have not been used in another flag or option
+    def verify_unused(names) # :nodoc:
+      names.each do |name|
+        verify_unused_in_option(name,flags,"flag")
+        verify_unused_in_option(name,switches,"switch")
+      end
+    end
+
+    def verify_unused_in_option(name,option_like,type) # :nodoc:
+      return if name.to_s == 'help'
+      raise ArgumentError.new("#{name} has already been specified as a #{type} #{context_description}") if option_like[name]
+      option_like.each do |one_option_name,one_option|
+        if one_option.aliases
+          if one_option.aliases.include? name
+            raise ArgumentError.new("#{name} has already been specified as an alias of #{type} #{one_option_name} #{context_description}") 
+          end
+        end
+      end
+    end
+
+    # Extract the options hash out of the argument to flag/switch and
+    # set the values if using classic style
+    def extract_options(names)
+      options = {}
+      options = names.pop if names.last.kind_of? Hash
+      options = { :desc => @next_desc, 
+                  :long_desc => @next_long_desc,
+                  :default_value => @next_default_value,
+                  :arg_name => @next_arg_name}.merge(options)
+    end
+
+
+  end
+end

data/lib/gli/exceptions.rb

@@ -1,7 +1,14 @@
 module GLI
+  # Mixed into all exceptions that GLI handles; you can use this to catch
+  # anything that came from GLI intentionally.  You can also mix this into non-GLI
+  # exceptions to get GLI's exit behavior.
+  module StandardException
+    def exit_code; 1; end
+  end
   # Indicates that the command line invocation was bad
-  class BadCommandLine < Exception
-    def exit_code; -1; end
+  class BadCommandLine < StandardError
+    include StandardException
+    def exit_code; 64; end
   end
 
   # Indicates the bad command line was an unknown command
@@ -14,6 +21,7 @@ module GLI
 
   # Indicates the bad command line was an unknown command argument
   class UnknownCommandArgument < BadCommandLine
+    # The command for which the argument was unknown
     attr_reader :command
     # +message+:: the error message to show the user
     # +command+:: the command we were using to parse command-specific options
@@ -24,14 +32,15 @@ module GLI
   end
 
   # Raise this if you want to use an exit status that isn't the default
-  # provided by GLI.  Note that GLI#exit_now! might be a bit more to your liking.
+  # provided by GLI.  Note that GLI::App#exit_now! might be a bit more to your liking.
   #
   # Example:
   #
   #     raise CustomExit.new("Not connected to DB",-5) unless connected?
   #     raise CustomExit.new("Bad SQL",-6) unless valid_sql?(args[0])
   #
-  class CustomExit < Exception
+  class CustomExit < StandardError
+    include StandardException
     attr_reader :exit_code #:nodoc:
     # Create a custom exit exception
     #

data/lib/gli/flag.rb

@@ -1,52 +1,41 @@
-require 'gli/command_line_token.rb'
-require 'gli/switch.rb'
+require 'gli/command_line_option.rb'
 
 module GLI
   # Defines a flag, which is to say a switch that takes an argument
-  class Flag < Switch # :nodoc:
+  class Flag < CommandLineOption # :nodoc:
 
-    attr_accessor :default_value
+    # Regexp that is used to see if the flag's argument matches
+    attr_reader :must_match
 
-    def initialize(names,description,argument_name=nil,default=nil,long_desc=nil)
-      super(names,description,long_desc)
-      @argument_name = argument_name || "arg"
-      @default_value = default
-    end
+    # Type to which we want to cast the values
+    attr_reader :type
 
-    def get_value!(args)
-      args.each_index() do |index|
-        arg = args[index]
-        present,matched,value = find_me(arg)
-        if present
-          args.delete_at index
-          if !value || value == ''
-            if args[index]
-              value = args[index]
-              args.delete_at index
-              return value
-            else
-              raise BadCommandLine.new("#{matched} requires an argument")
-            end
-          else
-            return value
-          end
-        end
-      end
-      return @default_value
+    # Name of the argument that user configured
+    attr_reader :argument_name
+
+    # Creates a new option
+    #
+    # names - Array of symbols or strings representing the names of this switch
+    # options - hash of options:
+    #           :desc - the short description
+    #           :long_desc - the long description
+    #           :default_value - the default value of this option
+    #           :arg_name - the name of the flag's argument, default is "arg"
+    #           :must_match - a regexp that the flag's value must match
+    #           :type - a class to convert the value to
+    def initialize(names,options)
+      super(names,options)
+      @argument_name = options[:arg_name] || "arg"
+      @default_value = options[:default_value]
+      @must_match = options[:must_match]
+      @type = options[:type]
     end
 
-    def find_me(arg)
-      if @names[arg]
-        return [true,arg,nil] if arg.length == 2
-        # This means we matched the long-form, but there's no argument
-        raise BadCommandLine.new("#{arg} requires an argument via #{arg}=argument")
-      end
-      @names.keys.each() do |name|
-        match_string = "^#{name}=(.*)$"
-        match_data = arg.match(match_string)
-        return [true,name,$1] if match_data;
-      end
-      [false,nil,nil]
+    def arguments_for_option_parser
+      args = all_forms_a.map { |name| "#{name} VAL" }
+      args << @must_match if @must_match
+      args << @type if @type
+      args
     end
 
     # Returns a string of all possible forms

data/lib/gli/gli_option_parser.rb

@@ -0,0 +1,98 @@
+module GLI
+  # Parses the command-line options using an actual +OptionParser+
+  class GLIOptionParser
+    def initialize(commands,flags,switches,accepts)
+      @commands = commands
+      @flags = flags
+      @switches = switches
+      @accepts = accepts
+    end
+
+    # Given the command-line argument array, returns and array of size 4:
+    #
+    # 0:: global options
+    # 1:: command, as a Command
+    # 2:: command-specific options
+    # 3:: unparsed arguments
+    def parse_options(args) # :nodoc:
+      args_clone = args.clone
+      global_options = {}
+      command = nil
+      command_options = {}
+      remaining_args = nil
+
+      global_options,command_name,args = parse_global_options(OptionParserFactory.new(@flags,@switches,@accepts), args)
+      @flags.each do |name,flag| 
+        global_options[name] = flag.default_value unless global_options[name]
+      end
+
+      command_name ||= @default_command || :help
+      command = find_command(command_name)
+      if Array(command).empty?
+        raise UnknownCommand.new("Unknown command '#{command_name}'")
+      elsif command.kind_of? Array
+        raise UnknownCommand.new("Ambiguous command '#{command_name}'. It matches #{command.sort.join(',')}")
+      end
+
+      command_options,args = parse_command_options(OptionParserFactory.new(command.flags,command.switches,@accepts),
+                                                   command,
+                                                   args)
+
+      command.flags.each do |name,flag| 
+        command_options[name] = flag.default_value unless command_options[name]
+      end
+      command.switches.each do |name,switch| 
+        command_options[name] = switch.default_value unless command_options[name] 
+      end
+
+      [global_options,command,command_options,args]
+    end
+
+  private
+
+    def parse_command_options(option_parser_factory,command,args)
+      option_parser,command_options = option_parser_factory.option_parser
+      option_parser.parse!(args)
+      [command_options,args]
+    rescue OptionParser::InvalidOption => ex
+      raise UnknownCommandArgument.new("Unknown option #{ex.args.join(' ')}",command)
+    rescue OptionParser::InvalidArgument => ex
+      raise UnknownCommandArgument.new("#{ex.reason}: #{ex.args.join(' ')}",command)
+    end
+
+    def parse_global_options(option_parser_factory,args,&error_handler)
+      if error_handler.nil?
+        error_handler = lambda { |message|
+          raise UnknownGlobalArgument.new(message)
+        }
+      end
+      option_parser,global_options = option_parser_factory.option_parser
+      command = nil
+      option_parser.order!(args) do |non_option|
+        command = non_option
+        break
+      end
+      [global_options,command,args]
+    rescue OptionParser::InvalidOption => ex
+      error_handler.call("Unknown option #{ex.args.join(' ')}")
+    rescue OptionParser::InvalidArgument => ex
+      error_handler.call("#{ex.reason}: #{ex.args.join(' ')}")
+    end
+
+    def find_command(name) # :nodoc:
+      names_to_commands = {}
+      @commands.each do |command_name,command|
+        names_to_commands[command_name.to_s] = command
+        Array(command.aliases).each do |command_alias|
+          names_to_commands[command_alias.to_s] = command
+        end
+      end
+      name = name.to_s
+      return names_to_commands[name] if names_to_commands[name]
+      # Now try to match on partial names
+      partial_matches = names_to_commands.keys.select { |command_name| command_name =~ /^#{name}/ }
+      return names_to_commands[partial_matches[0]] if partial_matches.size == 1
+      partial_matches
+    end
+  end
+end

data/lib/gli/option_parser_factory.rb

@@ -0,0 +1,44 @@
+module GLI
+  # Factory for creating an OptionParser based on app configuration and DSL calls
+  class OptionParserFactory
+    # Create an OptionParserFactory for the given
+    # flags, switches, and accepts
+    def initialize(flags,switches,accepts)
+      @flags = flags
+      @switches = switches
+      @accepts = accepts
+    end
+
+    # Return an option parser to parse the given flags, switches and accepts
+    def option_parser
+      options = {}
+      option_parser = OptionParser.new do |opts|
+        self.class.setup_accepts(opts,@accepts)
+        self.class.setup_options(opts,@switches,options)
+        self.class.setup_options(opts,@flags,options)
+      end
+      [option_parser,options]
+    end
+
+  private
+
+    def self.setup_accepts(opts,accepts)
+      accepts.each do |object,block| 
+        opts.accept(object) do |arg_as_string| 
+          block.call(arg_as_string) 
+        end
+      end
+    end
+
+    def self.setup_options(opts,tokens,options)
+      tokens.each do |ignore,token|
+        opts.on(*token.arguments_for_option_parser) do |arg|
+          [token.name,token.aliases].flatten.compact.each do |name|
+            options[name] = arg
+          end
+        end
+      end
+    end
+
+  end
+end