gli 1.6.0 → 2.0.0.rc3

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

@@ -2,12 +2,12 @@ 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 #:ndoc:
-    attr_reader :aliases #:ndoc:
-    attr_reader :description #:ndoc:
-    attr_reader :long_description #:ndoc:
+    attr_reader :name #:nodoc:
+    attr_reader :aliases #:nodoc:
+    attr_reader :description #:nodoc:
+    attr_reader :long_description #:nodoc:
 
-    def initialize(names,description,long_description=nil) #:ndoc:
+    def initialize(names,description,long_description=nil) #:nodoc:
       @description = description
       @long_description = long_description
       @name,@aliases,@names = parse_names(names)
@@ -17,7 +17,7 @@ module GLI
       all_forms
     end
 
-    # Sort based on name
+    # Sort based on primary name
     def <=>(other)
       self.name.to_s <=> other.name.to_s
     end
@@ -37,7 +37,7 @@ module GLI
     def parse_names(names)
       # Allow strings; convert to symbols
       names = [names].flatten.map { |name| name.to_sym } 
-      names_hash = Hash.new
+      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
@@ -47,10 +47,14 @@ module GLI
       [name,aliases,names_hash]
     end
 
+    def negatable?
+      false;
+    end
+
     def all_forms_a
-      forms = [self.class.name_as_string(name)]
+      forms = [self.class.name_as_string(name,negatable?)]
       if aliases
-        forms |= aliases.collect { |one_alias| self.class.name_as_string(one_alias) }.sort { |one,two| two.length <=> one.length }
+        forms |= aliases.map { |one_alias| self.class.name_as_string(one_alias,negatable?) }.sort { |one,two| one.length <=> two.length }
       end
       forms
     end

data/lib/gli/command_support.rb

@@ -0,0 +1,200 @@
+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
+
+    # 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
+
+    # Return the Array of the command's names
+    def names 
+      all_forms
+    end
+
+    def flag(*names)
+      new_flag = if parent.kind_of? Command
+                   parent.flag(*names)
+                 else
+                   super(*names)
+                 end
+      new_flag.associated_command = self
+      new_flag
+    end
+
+    def switch(*names)
+      new_switch = if parent.kind_of? Command
+                     parent.switch(*names)
+                   else
+                     super(*names)
+                   end
+      new_switch.associated_command = self
+      new_switch
+    end
+
+    def desc(d)
+      if parent.kind_of? Command
+        parent.desc(d)
+      else
+        super(d)
+      end
+    end
+
+    def long_desc(d)
+      if parent.kind_of? Command
+        parent.long_desc(d)
+      else
+        super(d)
+      end
+    end
+
+    def arg_name(d)
+      if parent.kind_of? Command
+        parent.arg_name(d)
+      else
+        super(d)
+      end
+    end
+
+    def default_value(d)
+      if parent.kind_of? Command
+        parent.default_value(d)
+      else
+        super(d)
+      end
+    end
+
+    # Get the usage string
+    # CR: This should probably not be here
+    def usage 
+      usage = name.to_s
+      usage += ' [command options]' if !flags.empty? || !switches.empty?
+      usage += ' ' + @arguments_description if @arguments_description
+      usage
+    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) 
+      subcommand,arguments = find_subcommand(arguments)
+      if subcommand
+        subcommand.execute(global_options,options,arguments)
+      else
+        get_action(arguments).call(global_options,options,arguments)
+      end
+    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 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"
+        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
+
+    def find_subcommand(arguments)
+      subcommand = find_explicit_subcommand(arguments)
+      if subcommand
+        [subcommand,arguments[1..-1]]
+      else
+        if !@default_command.nil?
+          [find_explicit_subcommand([@default_command.to_s]),arguments]
+        else 
+          [false,arguments]
+        end
+      end
+    end
+
+    def find_explicit_subcommand(arguments)
+      arguments = Array(arguments)
+      return false if arguments.empty?
+      subcommand_name = arguments.first
+      self.commands.values.find { |command|
+        [command.name,Array(command.aliases)].flatten.map(&:to_s).any? { |name| name == subcommand_name }
+      }
+    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)
+
+        @commands = command_names.map { |name| self.class.find_command(base,name) }
+      end
+
+      def execute(global_options,options,arguments) #:nodoc:
+        @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/help.rb

@@ -0,0 +1,63 @@
+require 'erb'
+require 'gli/command'
+require 'gli/terminal'
+require 'gli/commands/help_modules/list_formatter'
+require 'gli/commands/help_modules/text_wrapper'
+require 'gli/commands/help_modules/options_formatter'
+require 'gli/commands/help_modules/global_help_format'
+require 'gli/commands/help_modules/command_help_format'
+
+module GLI
+  module Commands
+    # The help command used for the two-level interactive help system
+    class Help < Command
+      def initialize(app,output=$stdout,error=$stderr)
+        super(:names => :help,
+              :description => 'Shows a list of commands or help for one command',
+              :arguments_name => 'command',
+              :long_desc => 'Gets help for the application or its commands. Can also list the commands in a way helpful to creating a bash-style completion function',
+              :skips_pre => true,
+              :skips_post => true)
+        @app = app
+        action do |global_options,options,arguments|
+          show_help(global_options,options,arguments,output,error)
+        end
+      end
+
+    private
+
+      def show_help(global_options,options,arguments,out,error)
+        if arguments.empty?
+          out.puts HelpModules::GlobalHelpFormat.new(@app).format
+        else
+          name = arguments.shift
+          command = find_command(name,@app)
+          return if unknown_command(command,name,error)
+          while !arguments.empty?
+            name = arguments.shift
+            command = find_command(name,command)
+            return if unknown_command(command,name,error)
+          end
+          out.puts HelpModules::CommandHelpFormat.new(command,@app,File.basename($0).to_s).format
+        end
+      end
+
+      def unknown_command(command,name,error)
+        if command.nil?
+          error.puts "error: Unknown command '#{name}'.  Use 'gli help' for a list of commands."
+          true
+        else
+          false
+        end
+      end
+
+      def find_command(command_name,base)
+        base.commands.values.select { |command|
+          if [command.name,Array(command.aliases)].flatten.map(&:to_s).any? { |_| _ == command_name }
+            command
+          end
+        }.first
+      end
+    end
+  end
+end

data/lib/gli/commands/help_modules/command_help_format.rb

@@ -0,0 +1,134 @@
+require 'erb'
+
+module GLI
+  module Commands
+    module HelpModules
+      class CommandHelpFormat
+        def initialize(command,app,basic_invocation)
+          @basic_invocation = basic_invocation
+          @app = app
+          @command = command
+        end
+
+        def format
+          command_wrapper = TextWrapper.new(Terminal.instance.size[0],4 + @command.name.to_s.size + 3)
+          wrapper = TextWrapper.new(Terminal.instance.size[0],4)
+          flags_and_switches = Hash[@command.topmost_ancestor.flags.merge(@command.topmost_ancestor.switches).select { |_,option| option.associated_command == @command }]
+          options_description = OptionsFormatter.new(flags_and_switches).format
+          commands_description = format_subcommands(@command)
+
+          synopses = []
+          one_line_usage = basic_usage(flags_and_switches)
+          one_line_usage << @command.arguments_description
+          if @command.commands.empty?
+            synopses << one_line_usage
+          else
+            synopses = sorted_synopses(flags_and_switches)
+            if @command.has_action?
+              synopses.unshift(one_line_usage)
+            end
+
+          end
+
+          COMMAND_HELP.result(binding)
+        end
+
+      private
+        COMMAND_HELP = ERB.new(%q(NAME
+    <%= @command.name %> - <%= command_wrapper.wrap(@command.description) %>
+
+SYNOPSIS
+<% synopses.each do |s| %>
+    <%= s %>
+<% end %>
+<% unless @command.long_description.nil? %>
+
+DESCRIPTION
+    <%= wrapper.wrap(@command.long_description) %> 
+<% end %>
+<% if options_description.strip.length != 0 %>
+
+COMMAND OPTIONS
+<%= options_description %>
+<% end %>
+<% unless @command.commands.empty? %>
+
+COMMANDS
+<%= commands_description %>
+<% end %>),nil,'<>')
+
+        def command_with_subcommand_usage(sub,flags_and_switches,is_default_command)
+          usage = basic_usage(flags_and_switches)
+          sub_options = @command.flags.merge(@command.switches).select { |_,o| o.associated_command == sub }
+          usage << sub_options.map { |option_name,option| 
+            all_names = [option.name,Array(option.aliases)].flatten
+            all_names.map { |_| 
+              CommandLineOption.name_as_string(_,false) + (option.kind_of?(Flag) ? " #{option.argument_name }" : '')
+            }.join('|')
+          }.map { |_| "[#{_}]" }.sort.join(' ')
+          usage << ' '
+          if is_default_command
+            usage << "[#{sub.name}]"
+          else
+            usage << sub.name.to_s
+          end
+          usage
+        end
+ 
+        def basic_usage(flags_and_switches)
+          usage = @basic_invocation.dup
+          usage << " [global options] #{path_to_command} "
+          usage << "[command options] " unless global_flags_and_switches.empty?
+          usage
+        end
+ 
+        def path_to_command
+          path = []
+          c = @command
+          while c.kind_of? Command
+            path.unshift(c.name)
+            c = c.parent
+          end
+          path.join(' ')
+        end
+ 
+        def global_flags_and_switches
+          @app.flags.merge(@app.switches)
+        end
+ 
+        def format_subcommands(command)
+          commands_array = command.commands.values.sort.map { |cmd| 
+            if command.get_default_command == cmd.name
+              [cmd.names,cmd.description + " (default)"] 
+            else
+              [cmd.names,cmd.description] 
+            end
+          }
+          if command.has_action?
+            commands_array.unshift(["<default>",command.default_description])
+          end
+          formatter = ListFormatter.new(commands_array)
+          StringIO.new.tap { |io| formatter.output(io) }.string
+        end
+
+        def sorted_synopses(flags_and_switches)
+          synopses_command = {}
+          @command.commands.each do |name,sub|
+            default = @command.get_default_command == name
+            synopsis = command_with_subcommand_usage(sub,flags_and_switches,default)
+            synopses_command[synopsis] = sub
+          end
+          synopses = synopses_command.keys.sort { |one,two|
+            if synopses_command[one].name == @command.get_default_command
+              -1
+            elsif synopses_command[two].name == @command.get_default_command
+              1
+            else
+              synopses_command[one] <=> synopses_command[two]
+            end
+          }
+        end
+      end
+    end
+  end
+end