gli_aziz_light 2.8.1

data/lib/gli/command_finder.rb

@@ -0,0 +1,41 @@
+module GLI
+  class CommandFinder
+    # Initialize a finder on the given list of commands, using default_command as the default if none found
+    def initialize(commands,default_command)
+      @default_command = default_command
+      @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
+    end
+
+    # Finds the command with the given name, allowing for partial matches.  Returns the command named by
+    # the default command if no command with +name+ matched
+    def find_command(name)
+      name ||= @default_command
+
+      raise UnknownCommand.new("No command name given nor default available") if String(name).strip == ''
+
+      command_found = @names_to_commands.fetch(name.to_s) do |command_to_match|
+        find_command_by_partial_name(@names_to_commands, command_to_match)
+      end
+      if Array(command_found).empty?
+        raise UnknownCommand.new("Unknown command '#{name}'")
+      elsif command_found.kind_of? Array
+        raise AmbiguousCommand.new("Ambiguous command '#{name}'. It matches #{command_found.sort.join(',')}")
+      end
+      command_found
+    end
+
+  private
+
+    def find_command_by_partial_name(names_to_commands, command_to_match)
+      partial_matches = names_to_commands.keys.select { |command_name| command_name =~ /^#{command_to_match}/ }
+      return names_to_commands[partial_matches[0]] if partial_matches.size == 1
+      partial_matches
+    end
+  end
+end

data/lib/gli/command_line_option.rb

@@ -0,0 +1,34 @@
+require 'gli/command_line_token.rb'
+
+module GLI
+  # An option, not a command or argument, on the command line
+  class CommandLineOption < CommandLineToken #:nodoc:
+
+    attr_accessor :default_value
+    # Command to which this option "belongs", nil if it's a global option
+    attr_accessor :associated_command
+
+    # 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
+    def initialize(names,options = {})
+      super(names,options[:desc],options[:long_desc])
+      @default_value = options[:default_value]
+    end
+
+    def self.name_as_string(name,negatable=true)
+      string = name.to_s
+      if string.length == 1 
+        "-#{string}" 
+      elsif negatable
+        "--[no-]#{string}"
+      else
+        "--#{string}"
+      end
+    end
+  end
+end

data/lib/gli/command_line_token.rb

@@ -0,0 +1,63 @@
+module GLI
+  # Abstract base class for a logical element of a command line, mostly so that subclasses can have similar
+  # initialization and interface
+  class CommandLineToken
+    attr_reader :name #:nodoc:
+    attr_reader :aliases #:nodoc:
+    attr_reader :description #:nodoc:
+    attr_reader :long_description #:nodoc:
+
+    def initialize(names,description,long_description=nil) #:nodoc:
+      @description = description
+      @long_description = long_description
+      @name,@aliases,@names = parse_names(names)
+    end
+
+    # Sort based on primary name
+    def <=>(other)
+      self.name.to_s <=> other.name.to_s
+    end
+
+    # Array of the name and aliases, as string
+    def names_and_aliases
+      [self.name,self.aliases].flatten.compact.map(&:to_s)
+    end
+
+    private
+    # 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
+      forms.join(joiner)
+    end
+
+
+    # Handles dealing with the "names" param, parsing
+    # it into the primary name and aliases list
+    def parse_names(names)
+      # Allow strings; convert to symbols
+      names = [names].flatten.map { |name| name.to_sym } 
+      names_hash = {}
+      names.each do |name| 
+        raise ArgumentError.new("#{name} has spaces; they are not allowed") if name.to_s =~ /\s/
+        names_hash[self.class.name_as_string(name)] = true
+      end
+      name = names.shift
+      aliases = names.length > 0 ? names : nil
+      [name,aliases,names_hash]
+    end
+
+    def negatable?
+      false;
+    end
+
+    def all_forms_a
+      forms = [self.class.name_as_string(name,negatable?)]
+      if aliases
+        forms |= aliases.map { |one_alias| self.class.name_as_string(one_alias,negatable?) }.sort { |one,two| one.length <=> two.length }
+      end
+      forms
+    end
+  end
+end

data/lib/gli/command_support.rb

@@ -0,0 +1,181 @@
+module GLI
+  # Things unrelated to the true public interface of Command that are needed for bookkeeping
+  # and help support.  Generally, you shouldn't be calling these methods; they are technically public
+  # but are essentially part of GLI's internal implementation and subject to change
+  module CommandSupport
+    # The parent of this command, either the GLI app, or another command
+    attr_accessor :parent
+
+    def context_description
+      "in the command #{name}"
+    end
+
+    # Return true to avoid including this command in your help strings
+    def nodoc
+      false
+    end
+
+    # Return the arguments description
+    def arguments_description 
+      @arguments_description
+    end
+
+    def arguments_options
+      @arguments_options
+    end
+
+    # If true, this command doesn't want the pre block run before it executes
+    def skips_pre 
+      @skips_pre
+    end
+
+    # If true, this command doesn't want the post block run before it executes
+    def skips_post 
+      @skips_post
+    end
+
+    # If true, this command doesn't want the around block called
+    def skips_around
+      @skips_around
+    end
+
+    # Return the Array of the command's names
+    def names 
+      all_forms
+    end
+
+    # Get an array of commands, ordered by when they were declared
+    def commands_declaration_order # :nodoc:
+      @commands_declaration_order
+    end
+
+    def flag(*names)
+      if send_declarations_to_parent?
+        new_flag = if parent.kind_of? Command
+                     super(*names)
+                     parent.flag(*names)
+                   else
+                     super(*names)
+                   end
+        new_flag.associated_command = self
+        new_flag
+      else
+        super(*names)
+      end
+    end
+
+    def switch(*names)
+      if send_declarations_to_parent?
+        new_switch = if parent.kind_of? Command
+                       super(*names)
+                       parent.switch(*names)
+                     else
+                       super(*names)
+                     end
+        new_switch.associated_command = self
+        new_switch
+      else
+        super(*names)
+      end
+    end
+
+    def desc(d)
+      parent.desc(d) if parent.kind_of?(Command) && send_declarations_to_parent?
+      super(d)
+    end
+
+    def long_desc(d)
+      parent.long_desc(d) if parent.kind_of?(Command) && send_declarations_to_parent?
+      super(d)
+    end
+
+    def arg_name(d,options=[])
+      parent.arg_name(d,options) if parent.kind_of?(Command) && send_declarations_to_parent?
+      super(d,options)
+    end
+
+    def default_value(d)
+      parent.default_value(d) if parent.kind_of?(Command) && send_declarations_to_parent?
+      super(d)
+    end
+
+    # Return the flags as a Hash
+    def flags 
+      @flags ||= {}
+    end
+    # Return the switches as a Hash
+    def switches 
+      @switches ||= {}
+    end
+
+    def commands # :nodoc:
+      @commands ||= {}
+    end
+
+    def default_description
+      @default_desc
+    end
+
+    # Executes the command
+    def execute(global_options,options,arguments) 
+      get_action(arguments).call(global_options,options,arguments)
+    end
+
+    def topmost_ancestor
+      some_command = self
+      top = some_command
+      while some_command.kind_of? self.class
+        top = some_command
+        some_command = some_command.parent
+      end
+      top
+    end
+
+    def has_action?
+      !!@action
+    end
+
+    def get_default_command
+      @default_command
+    end
+
+  private
+
+    def send_declarations_to_parent?
+      app = topmost_ancestor.parent
+      app.nil? ? true : (app.subcommand_option_handling_strategy == :legacy)
+    end
+
+    def get_action(arguments)
+      if @action
+        @action
+      else
+        generate_error_action(arguments)
+      end
+    end
+
+    def generate_error_action(arguments)
+      lambda { |global_options,options,arguments|
+        if am_subcommand?
+          if arguments.size > 0
+            raise UnknownCommand,"Unknown command '#{arguments[0]}'"
+          else
+            raise BadCommandLine,"Command '#{name}' requires a subcommand"
+          end
+        elsif have_subcommands?
+          raise BadCommandLine,"Command '#{name}' requires a subcommand #{self.commands.keys.join(',')}"
+        else
+          raise "Command '#{name}' has no action block"
+        end
+      }
+    end
+
+    def am_subcommand?
+      parent.kind_of?(Command)
+    end
+
+    def have_subcommands?
+      !self.commands.empty?
+    end
+  end
+end

data/lib/gli/commands/compound_command.rb

@@ -0,0 +1,42 @@
+module GLI
+  module Commands
+    # A command that calls other commands in order
+    class CompoundCommand < Command
+      # base:: object that respondes to +commands+
+      # configuration:: Array of arrays: index 0 is the array of names of this command and index 1
+      #                 is the names of the compound commands.
+      def initialize(base,configuration,options={})
+        name = configuration.keys.first
+        super(options.merge(:names => [name]))
+
+        command_names = configuration[name]
+
+        check_for_unknown_commands!(base,command_names)
+
+        @wrapped_commands = command_names.map { |name| self.class.find_command(base,name) }
+      end
+
+      def execute(global_options,options,arguments) #:nodoc:
+        @wrapped_commands.each do |command| 
+          command.execute(global_options,options,arguments)
+        end
+      end
+
+    private 
+
+      def check_for_unknown_commands!(base,command_names)
+        known_commands = base.commands.keys.map(&:to_s)
+        unknown_commands = command_names.map(&:to_s) - known_commands
+
+        unless unknown_commands.empty?
+          raise "Unknown commands #{unknown_commands.join(',')}"
+        end
+      end
+
+      def self.find_command(base,name)
+        base.commands.values.find { |command| command.name == name }
+      end
+
+    end
+  end
+end

data/lib/gli/commands/doc.rb

@@ -0,0 +1,231 @@
+module GLI
+  module Commands
+    # Takes a DocListener which will be called with all of the meta-data and documentation
+    # about your app, so as to create documentation in whatever format you want
+    class Doc < Command
+      FORMATS = {
+        'rdoc' => GLI::Commands::RdocDocumentListener,
+      }
+      # Create the Doc generator based on the GLI app passed in
+      def initialize(app)
+        super(:names       => "_doc",
+              :description => "Generate documentation of your application's UI",
+              :long_desc   => "Introspects your application's UI meta-data to generate documentation in a variety of formats.  This is intended to be extensible via the DocumentListener interface, so that you can provide your own documentation formats without them being a part of GLI",
+              :skips_pre   => true, :skips_post => true, :skips_around => true, :hidden => true)
+
+        @app = app
+        @parent = @app
+        @subcommand_option_handling_strategy = @app.subcommand_option_handling_strategy
+
+        desc          'The format name of the documentation to generate or the class name to use to generate it'
+        default_value 'rdoc'
+        arg_name      'name_or_class'
+        flag          :format
+
+        action do |global_options,options,arguments|
+          self.document(format_class(options[:format]).new(global_options,options,arguments,app))
+        end
+      end
+
+      def nodoc
+        true
+      end
+
+      # Generates documentation using the listener
+      def document(document_listener)
+        document_listener.beginning
+        document_listener.program_desc(@app.program_desc) unless @app.program_desc.nil?
+        document_listener.program_long_desc(@app.program_long_desc) unless @app.program_long_desc.nil?
+        document_listener.version(@app.version_string)
+        if any_options?(@app)
+          document_listener.options 
+        end
+        document_flags_and_switches(document_listener,
+                                    @app.flags.values.sort(&by_name),
+                                    @app.switches.values.sort(&by_name))
+        if any_options?(@app)
+          document_listener.end_options 
+        end
+        document_listener.commands
+        document_commands(document_listener,@app)
+        document_listener.end_commands
+        document_listener.ending
+      end
+
+      # Interface for a listener that is called during various parts of the doc process
+      class DocumentListener
+        def initialize(global_options,options,arguments,app)
+          @global_options = global_options
+          @options        = options
+          @arguments      = arguments
+          @app            = app
+        end
+        # Called before processing begins
+        def beginning
+          abstract!
+        end
+
+        # Called when processing has completed
+        def ending
+          abstract!
+        end
+
+        # Gives you the program description
+        def program_desc(desc)
+          abstract!
+        end
+
+        # Gives you the program long description
+        def program_long_desc(desc)
+          abstract!
+        end
+
+        # Gives you the program version
+        def version(version)
+          abstract!
+        end
+
+        # Called at the start of options for the current context
+        def options
+          abstract!
+        end
+
+        # Called when all options for the current context have been vended
+        def end_options
+          abstract!
+        end
+
+        # Called at the start of commands for the current context
+        def commands
+          abstract!
+        end
+
+        # Called when all commands for the current context have been vended
+        def end_commands
+          abstract!
+        end
+
+        # Gives you a flag in the current context
+        def flag(name,aliases,desc,long_desc,default_value,arg_name,must_match,type)
+          abstract!
+        end
+
+        # Gives you a switch in the current context
+        def switch(name,aliases,desc,long_desc,negatable)
+          abstract!
+        end
+
+        # Gives you the name of the current command in the current context
+        def default_command(name)
+          abstract!
+        end
+
+        # Gives you a command in the current context and creates a new context of this command
+        def command(name,aliases,desc,long_desc,arg_name,arg_options)
+          abstract!
+        end
+
+        # Ends a command, and "pops" you back up one context
+        def end_command(name)
+          abstract!
+        end
+
+      private
+        def abstract!
+          raise "Subclass must implement"
+        end
+      end
+
+    private
+
+      def format_class(format_name)
+        FORMATS.fetch(format_name) { 
+          begin
+            return format_name.split(/::/).reduce(Kernel) { |context,part| context.const_get(part) }
+          rescue => ex
+            raise IndexError,"Couldn't find formatter or class named #{format_name}"
+          end
+        }
+      end
+
+      def document_commands(document_listener,context)
+        context.commands.values.reject {|_| _.nodoc }.sort(&by_name).each do |command|
+          call_command_method_being_backwards_compatible(document_listener,command)
+          document_listener.options if any_options?(command)
+          document_flags_and_switches(document_listener,command_flags(command),command_switches(command))
+          document_listener.end_options if any_options?(command)
+          document_listener.commands if any_commands?(command)
+          document_commands(document_listener,command)
+          document_listener.end_commands if any_commands?(command)
+          document_listener.end_command(command.name)
+        end
+        document_listener.default_command(context.get_default_command)
+      end
+
+      def call_command_method_being_backwards_compatible(document_listener,command)
+        command_args = [command.name,
+                        Array(command.aliases),
+                        command.description,
+                        command.long_description,
+                        command.arguments_description]
+        if document_listener.method(:command).arity == 6
+          command_args << command.arguments_options
+        end
+        document_listener.command(*command_args)
+      end
+
+      def by_name
+        lambda { |a,b| a.name.to_s <=> b.name.to_s }
+      end
+
+      def command_flags(command)
+        if @subcommand_option_handling_strategy == :legacy
+          command.topmost_ancestor.flags.values.select { |flag| flag.associated_command == command }.sort(&by_name)
+        else
+          command.flags.values.sort(&by_name)
+        end
+      end
+
+      def command_switches(command)
+        if @subcommand_option_handling_strategy == :legacy
+          command.topmost_ancestor.switches.values.select { |switch| switch.associated_command == command }.sort(&by_name)
+        else
+          command.switches.values.sort(&by_name)
+        end
+      end
+
+      def document_flags_and_switches(document_listener,flags,switches)
+        flags.each do |flag|
+          document_listener.flag(flag.name,
+                                 Array(flag.aliases),
+                                 flag.description,
+                                 flag.long_description,
+                                 flag.safe_default_value,
+                                 flag.argument_name,
+                                 flag.must_match,
+                                 flag.type)
+        end
+        switches.each do |switch|
+          document_listener.switch(switch.name,
+                                   Array(switch.aliases),
+                                   switch.description,
+                                   switch.long_description,
+                                   switch.negatable)
+        end
+      end
+
+      def any_options?(context)
+        options = if context.kind_of?(Command)
+                    command_flags(context) + command_switches(context)
+                  else
+                    context.flags.values + context.switches.values
+                  end
+        !options.empty?
+      end
+
+      def any_commands?(command)
+        !command.commands.empty?
+      end
+    end
+  end
+end