gli_aziz_light 2.8.1

data/lib/gli/dsl.rb

@@ -0,0 +1,226 @@
+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.
+    # +options+:: Symbol or array of symbols to annotate this argument.  This doesn't affect parsing, just
+    #             the help output.  Values recognized are:
+    #             +:optional+:: indicates this argument is optional; will format it with square brackets
+    #             +:multiple+:: indicates multiple values are accepted; will format appropriately
+    #
+    # Example:
+    #     desc 'Set the filename'
+    #     arg_name 'file_name'
+    #     flag [:f,:filename]
+    #
+    # Produces:
+    #     -f, --filename=file_name      Set the filename
+    def arg_name(name,options=[])
+      @next_arg_name = name
+      @next_arg_options = options
+    end
+
+    # set the default value of the next flag or switch
+    #
+    # +val+:: 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.  For a switch, this is
+    #         the value to be used if the switch isn't specified on the command-line.  Note that if you
+    #         set a switch to have a default of true, using the switch on the command-line has no effect.
+    #         To disable a switch where the default is true, use the <tt>--no-</tt> form.
+    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
+      flags_declaration_order << flag
+      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
+    #           +:default_value+:: if the switch is omitted, use this as the default value.  By default,  switches default to off, or +false+
+    #           +: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
+      switches_declaration_order << switch
+      switch
+    end
+    alias :s :switch
+
+    def clear_nexts # :nodoc:
+      @next_desc = nil
+      @next_arg_name = nil
+      @next_arg_options = 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,
+        :arguments_options => @next_arg_options,
+        :long_desc => @next_long_desc,
+        :skips_pre => @skips_pre,
+        :skips_post => @skips_post,
+        :skips_around => @skips_around,
+      }
+      @commands_declaration_order ||= []
+      if names.first.kind_of? Hash
+        command = GLI::Commands::CompoundCommand.new(self,
+                                                     names.first,
+                                                     command_options)
+        command.parent = self
+        commands[command.name] = command
+        @commands_declaration_order << command
+      else
+        new_command = Command.new(command_options.merge(:names => [names].flatten))
+        command = commands[new_command.name]
+        if command.nil?
+          command = new_command
+          command.parent = self
+          commands[command.name] = command
+          @commands_declaration_order << command
+        end
+        yield command
+      end
+      clear_nexts
+    end
+    alias :c :command
+
+    def flags_declaration_order # :nodoc:
+      @flags_declaration_order ||= []
+    end
+
+    def switches_declaration_order # :nodoc:
+      @switches_declaration_order ||= []
+    end
+
+
+    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

@@ -0,0 +1,71 @@
+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 < StandardError
+    include StandardException
+    def exit_code; 64; end
+  end
+
+  class PreconditionFailed < StandardError
+    include StandardException
+    def exit_code; 65; end
+  end
+
+  # Indicates the bad command line was an unknown command
+  class UnknownCommand < BadCommandLine
+  end
+
+  # The command issued partially matches more than one command
+  class AmbiguousCommand < BadCommandLine
+  end
+
+  # Indicates the bad command line was an unknown global argument
+  class UnknownGlobalArgument < BadCommandLine
+  end
+
+  class CommandException < BadCommandLine
+    # The command for which the argument was unknown
+    attr_reader :command_in_context
+    # +message+:: the error message to show the user
+    # +command+:: the command we were using to parse command-specific options
+    def initialize(message,command_in_context,exit_code=nil)
+      super(message)
+      @command_in_context = command_in_context
+      @exit_code = exit_code
+    end
+
+    def exit_code
+      @exit_code || super
+    end
+  end
+
+  # Indicates the bad command line was an unknown command argument
+  class UnknownCommandArgument < CommandException
+  end
+
+  # Raise this if you want to use an exit status that isn't the default
+  # 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 < StandardError
+    include StandardException
+    attr_reader :exit_code #:nodoc:
+    # Create a custom exit exception
+    #
+    # +message+:: String containing error message to show the user
+    # +exit_code+:: the exit code to use (as an Int), overridding GLI's default
+    def initialize(message,exit_code)
+      super(message)
+      @exit_code = exit_code
+    end
+  end
+end

data/lib/gli/flag.rb

@@ -0,0 +1,68 @@
+require 'gli/command_line_option.rb'
+
+module GLI
+  # Defines a flag, which is to say a switch that takes an argument
+  class Flag < CommandLineOption # :nodoc:
+
+    # Regexp that is used to see if the flag's argument matches
+    attr_reader :must_match
+
+    # Type to which we want to cast the values
+    attr_reader :type
+
+    # 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
+    #           :mask:: if true, the default value of this flag will not be output in the help.
+    #                   This is useful for password flags where you might not want to show it
+    #                   on the command-line.
+    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]
+      @mask = options[:mask]
+    end
+
+    def safe_default_value
+      if @mask
+        "********"
+      else
+        default_value
+      end
+    end
+
+    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
+    # of this flag.  Mostly intended for printing
+    # to the user.
+    def all_forms(joiner=', ')
+      forms = all_forms_a
+      string = forms.join(joiner)
+      if forms[-1] =~ /^\-\-/
+        string += '='
+      else
+        string += ' '
+      end
+      string += @argument_name
+      return string
+    end
+  end
+end

data/lib/gli/gli_option_block_parser.rb

@@ -0,0 +1,84 @@
+module GLI
+  # An "option block" is a set of parseable options, starting from the beginning of
+  # the argument list, stopping with the first unknown command-line element.
+  # This class handles parsing that block
+  class GLIOptionBlockParser
+
+    # Create the parser using the given +OptionParser+ instance and exception handling
+    # strategy.
+    #
+    # option_parser_factory:: An +OptionParserFactory+ instance, configured to parse wherever you are on the command line
+    # exception_klass_or_block:: means of handling exceptions from +OptionParser+.  One of:
+    #                            an exception class:: will be raised on errors with a message
+    #                            lambda/block:: will be called with a single argument - the error message.
+    def initialize(option_parser_factory,exception_klass_or_block)
+      @option_parser_factory = option_parser_factory
+      @extra_error_context = nil
+      @exception_handler = if exception_klass_or_block.kind_of?(Class)
+                             lambda { |message,extra_error_context|
+                               raise exception_klass_or_block,message
+                             }
+                           else
+                             exception_klass_or_block
+                           end
+    end
+
+    # Parse the given argument list, returning the unparsed arguments and options hash of parsed arguments.
+    # Exceptions from +OptionParser+ are given to the handler configured in the constructor
+    #
+    # args:: argument list.  This will be mutated
+    #
+    # Returns unparsed args
+    def parse!(args)
+      do_parse(args)
+    rescue OptionParser::InvalidOption => ex
+      @exception_handler.call("Unknown option #{ex.args.join(' ')}",@extra_error_context)
+    rescue OptionParser::InvalidArgument => ex
+      @exception_handler.call("#{ex.reason}: #{ex.args.join(' ')}",@extra_error_context)
+    end
+
+  protected
+
+    def do_parse(args)
+      first_non_option = nil
+      @option_parser_factory.option_parser.order!(args) do |non_option|
+        first_non_option = non_option
+        break
+      end
+      args.unshift(first_non_option)
+    end
+  end
+
+  class CommandOptionBlockParser < GLIOptionBlockParser
+
+    def command=(command_being_parsed)
+      @extra_error_context = command_being_parsed
+    end
+
+  protected
+
+    def break_on_non_option?
+      true
+    end
+
+    def do_parse(args)
+      unknown_options = []
+      @option_parser_factory.option_parser.order!(args) do |non_option|
+        unknown_options << non_option
+        break if break_on_non_option?
+      end
+      unknown_options.reverse.each do |unknown_option|
+        args.unshift(unknown_option)
+      end
+      args
+    end
+  end
+
+  class LegacyCommandOptionBlockParser < CommandOptionBlockParser
+
+  protected
+    def break_on_non_option?
+      false
+    end
+  end
+end