gli 1.2.5 → 1.2.6

data/README.rdoc

@@ -39,7 +39,7 @@ Though likely works on various other versions.
 
 == Documentation
 
-Extensive documentation is {available at the wiki}[https://github.com/davetron5000/gli/wiki]
+Extensive documentation is {available at the wiki}[https://github.com/davetron5000/gli/wiki].  For API Documentation, start with the GLI module.
 
 == Links
 

data/bin/gli

@@ -3,7 +3,7 @@
 # have this method, so we add it so we get resolved symlinks
 # and compatibility
 unless File.respond_to? :realpath
-  class File
+  class File #:nodoc:
     def self.realpath path
       return realpath(File.readlink(path)) if symlink?(path)
       path

data/gli.rdoc

@@ -15,7 +15,6 @@ These options are available for any command and are specified before the name of
                           This is the directory where the projects directory will be made, so if you specify a project name foo and the root dir of ., the directory ./foo will be created
 
 [<tt>-v</tt>] Be verbose
-[<tt>--version</tt>] Show version
 == Commands
 [<tt>help</tt>] Shows list of commands or help for one command
 [<tt>init</tt>] Create a new GLI-based project

data/lib/gli.rb

@@ -23,9 +23,15 @@ module GLI
   @@config_file = nil
   @@use_openstruct = false
   @@version = nil
+  @@stderr = $stderr
 
-  # Reset the GLI module internal data structures; mostly for testing
-  def reset
+  # Override the device of stderr; exposed only for testing
+  def error_device=(e) #:nodoc:
+    @@stderr = e
+  end
+
+  # Reset the GLI module internal data structures; mostly useful for testing
+  def reset # :nodoc:
     switches.clear
     flags.clear
     commands.clear
@@ -35,21 +41,51 @@ module GLI
     clear_nexts
   end
 
-  # describe the next switch, flag, or command.  This should be a
+  # 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
 
   # Provide a longer, more detailed description.  This
-  # will be reformatted and wrapped to fit in 80 columns
+  # 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
+  # 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.
+  #
+  # Example:
+  #
+  #     desc 'Set the filename'
+  #     flag [:f,:filename,'file-name']
+  #
+  # Produces:
+  #
+  #     -f, --filename, --file-name=arg     Set the filename
   def flag(*names)
     names = [names].flatten
     verify_unused(names,flags,switches,"in global options")
@@ -58,7 +94,10 @@ module GLI
     clear_nexts
   end
 
-  # Create a switch
+  # 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.
   def switch(*names)
     names = [names].flatten
     verify_unused(names,flags,switches,"in global options")
@@ -67,8 +106,11 @@ module GLI
     clear_nexts
   end
 
-  # Sets the config file.  If not an absolute path
-  # sets the path to the user's home directory
+  # Sets that this app uses a config file as well as the name of the config file.  
+  #
+  # +filename+:: A String representing the path to the file to use for the config file.  If it's an absolute
+  #              path, this is treated as the path to the file.  If it's *not*, it's treated as relative to the user's home
+  #              directory as produced by <code>Etc.getpwuid.dir</code>.
   def config_file(filename)
     if filename =~ /^\//
       @@config_file = filename
@@ -79,7 +121,11 @@ module GLI
     @@config_file
   end
 
-  # Define a command.
+  # Define a new command.  This takes a block that 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.
+  #
+  # +names+:: a String or Symbol, or an Array of String or Symbol that represent all the different names and aliases for this command.
+  #
   def command(*names)
     command = Command.new([names].flatten,@@next_desc,@@next_arg_name,@@next_long_desc)
     commands[command.name] = command
@@ -97,8 +143,8 @@ module GLI
     @@pre_block = a_proc
   end
 
-  # Define a block to run after command hase been executed, only
-  # if there was not an error.
+  # Define a block to run after the command was executed, <b>only
+  # if there was not an error</b>.
   # The block will receive the global-options,command,options, and arguments
   def post(&a_proc)
     @@post_block = a_proc
@@ -106,65 +152,103 @@ module GLI
 
   # Define a block to run if an error occurs.
   # The block will receive any Exception that was caught.
-  # It should return false to avoid the built-in error handling (which basically just
-  # prints out a message)
+  # It should evaluate to false to avoid the built-in error handling (which basically just
+  # prints out a message). GLI uses a variety of exceptions that you can use to find out what 
+  # errors might've occurred during command-line parsing:
+  # * GLI::CustomExit
+  # * GLI::UnknownCommandArgument
+  # * GLI::UnknownGlobalArgument
+  # * GLI::UnknownCommand
+  # * GLI::BadCommandLine
   def on_error(&a_proc)
     @@error_block = a_proc
   end
 
   # Indicate the version of your application
+  #
+  # +version+:: String containing the version of your application.  
   def version(version)
     @@version = version
   end
 
-  # Call this with "true" will cause the <tt>global_options</tt> and
-  # <tt>options</tt> passed to your code to be wrapped in
-  # GLI::Option, which is a subclass of OpenStruct that adds
+  # Call this with +true+ will cause the +global_options+ and
+  # +options+ passed to your code to be wrapped in
+  # Options, which is a subclass of +OpenStruct+ that adds
   # <tt>[]</tt> and <tt>[]=</tt> methods.
+  #
+  # +use_openstruct+:: a Boolean indicating if we should use OpenStruct instead of Hashes
   def use_openstruct(use_openstruct)
     @@use_openstruct = use_openstruct
   end
 
   # Runs whatever command is needed based on the arguments. 
   #
-  # args - the command line ARGV array
+  # +args+:: the command line ARGV array
   #
   # Returns a number that would be a reasonable exit code
-  def run(args)
+  def run(args) #:nodoc:
     rdoc = RDocCommand.new
     commands[:rdoc] = rdoc if !commands[:rdoc]
     commands[:help] = DefaultHelpCommand.new(@@version,rdoc) if !commands[:help]
+    exit_code = 0
     begin
       config = parse_config
       global_options,command,options,arguments = parse_options(args,config)
       copy_options_to_aliased_versions(global_options,command,options)
-      proceed = true
-      global_options = convert_to_option?(global_options)
-      options = convert_to_option?(options)
-      proceed = @@pre_block.call(global_options,command,options,arguments) if @@pre_block 
-      if proceed
+      global_options = convert_to_openstruct?(global_options)
+      options = convert_to_openstruct?(options)
+      if proceed?(global_options,command,options,arguments)
         command = commands[:help] if !command
         command.execute(global_options,options,arguments)
         @@post_block.call(global_options,command,options,arguments) if @@post_block 
       end
-      0
     rescue Exception => ex
-      regular_error_handling = true
-      regular_error_handling = @@error_block.call(ex) if @@error_block
 
-      if regular_error_handling
-        $stderr.puts "error: #{ex.message}"
-      end
+      @@stderr.puts error_message(ex) if regular_error_handling?(ex)
 
       raise ex if ENV['GLI_DEBUG'] == 'true'
 
-      case ex
-      when BadCommandLine then -1
-      when CustomExit then ex.exit_code
-      else 
+      exit_code = if ex.respond_to? :exit_code
+        ex.exit_code
+      else
         -2
       end
     end
+    exit_code
+  end
+
+  # True if we should proceed with executing the command; this calls
+  # the pre block if it's defined
+  def proceed?(global_options,command,options,arguments) #:nodoc:
+    if @@pre_block 
+      @@pre_block.call(global_options,command,options,arguments) 
+    else
+      true
+    end
+  end
+
+  # Returns true if we should proceed with GLI's basic error handling.
+  # This calls the error block if the user provided one
+  def regular_error_handling?(ex) #:nodoc:
+    if @@error_block
+      @@error_block.call(ex)
+    else
+      true
+    end
+  end
+
+  # Returns a String of the error message to show the user
+  # +ex+:: The exception we caught that launched the error handling routines
+  def error_message(ex) #:nodoc:
+    msg = "error: #{ex.message}"
+    case ex
+    when UnknownCommand
+      msg += ". Use '#{program_name} help' for a list of commands"
+    when UnknownCommandArgument
+      msg += ". Use '#{program_name} help #{ex.command.name}' for a list of command options"
+    when UnknownGlobalArgument
+      msg += ". Use '#{program_name} help' for a list of global options"
+    end
   end
 
   # Simpler means of exiting with a custom exit code.  This will 
@@ -174,17 +258,36 @@ module GLI
     raise CustomExit.new(message,exit_code)
   end
 
+  # Set or get the name of the program, if you don't want the default (which is
+  # the name of the command line program).  This
+  # is only used currently in the help and rdoc commands.
+  #
+  # +override+:: A String that represents the name of the program to use, other than the default.
+  #
+  # Returns the current program name, as a String
+  def program_name(override=nil)
+    if override
+      @@program_name = override
+    end
+    @@program_name
+  end
+
+  alias :d :desc
+  alias :f :flag
+  alias :s :switch
+  alias :c :command
+
   # Possibly returns a copy of the passed-in Hash as an instance of GLI::Option.
-  # By default, it will *not*, however by putting <tt>use_openstruct true</tt>
+  # By default, it will *not*. However by putting <tt>use_openstruct true</tt>
   # in your CLI definition, it will
-  def convert_to_option?(options)
+  def convert_to_openstruct?(options) # :nodoc:
     @@use_openstruct ? Options.new(options) : options
   end
 
   # Copies all options in both global_options and options to keys for the aliases of those flags.
   # For example, if a flag works with either -f or --flag, this will copy the value from [:f] to [:flag]
   # to allow the user to access the options by any alias
-  def copy_options_to_aliased_versions(global_options,command,options)
+  def copy_options_to_aliased_versions(global_options,command,options) # :nodoc:
     copy_options_to_aliases(global_options,self)
     copy_options_to_aliases(options,command)
   end
@@ -194,7 +297,7 @@ module GLI
   #
   # options - Hash of options parsed from command line; this is an I/O param
   # gli_like - Object resonding to flags and switches in the same way that GLI or a Command instance do
-  def copy_options_to_aliases(options,gli_like)
+  def copy_options_to_aliases(options,gli_like) # :nodoc:
     new_options = {}
     options.each do |key,value|
       if gli_like.flags[key] && gli_like.flags[key].aliases
@@ -210,7 +313,7 @@ module GLI
     options.merge!(new_options)
   end
 
-  def parse_config
+  def parse_config # :nodoc:
     return nil if @@config_file.nil?
     require 'yaml'
     if File.exist?(@@config_file)
@@ -220,19 +323,12 @@ module GLI
     end
   end
 
-  def program_name(override=nil)
-    if override
-      @@program_name = override
-    end
-    @@program_name
-  end
-
   # Returns an array of four values:
   #  * global options (as a Hash)
   #  * Command 
   #  * command options (as a Hash)
   #  * arguments (as an Array)
-  def parse_options(args,config=nil)
+  def parse_options(args,config=nil) # :nodoc:
     command_configs = {}
     if config.nil?
       config = {}
@@ -247,7 +343,7 @@ module GLI
 
   # Finds the index of the first non-flag
   # argument or -1 if there wasn't one.
-  def find_non_flag_index(args)
+  def find_non_flag_index(args) # :nodoc:
     args.each_index do |i|
       return i if args[i] =~ /^[^\-]/;
       return i-1 if args[i] =~ /^\-\-$/;
@@ -255,12 +351,7 @@ module GLI
     -1;
   end
 
-  alias :d :desc
-  alias :f :flag
-  alias :s :switch
-  alias :c :command
-
-  def clear_nexts
+  def clear_nexts # :nodoc:
     @@next_desc = nil
     @@next_arg_name = nil
     @@next_default_value = nil
@@ -269,17 +360,23 @@ module GLI
 
   clear_nexts
 
-  def flags; @@flags ||= {}; end
-  def switches; @@switches ||= {}; end
-  def commands; @@commands ||= {}; end
+  def flags # :nodoc:
+    @@flags ||= {}
+  end
+  def switches # :nodoc:
+    @@switches ||= {}
+  end
+  def commands # :nodoc:
+    @@commands ||= {}
+  end
 
   # Recursive helper for parsing command line options
-  # [args] the arguments that have yet to be processed
-  # [global_options] the global options hash
-  # [command] the Command that has been identified (or nil if not identified yet)
-  # [command_options] options for Command
-  # [arguments] the arguments for Command
-  # [command_configs] the configuration file for all commands, used as defaults
+  # <code>args</code>:: the arguments that have yet to be processed
+  # <code>global_options</code>:: the global options hash
+  # <code>command</code>:: the Command that has been identified (or nil if not identified yet)
+  # <code>command_options</code>:: options for Command
+  # <code>arguments</code>:: the arguments for Command
+  # <code>command_configs</code>:: the configuration file for all commands, used as defaults
   #
   # This works by finding the first non-switch/flag argument, and taking that sublist and trying to pick out
   # flags and switches.  After this is done, one of the following is true:
@@ -292,7 +389,7 @@ module GLI
   #
   # Once the command has been found, we start looking for command-specific flags and switches.
   # When those have been found, we know the rest of the argument list is arguments for the command
-  def parse_options_helper(args,global_options,command,command_options,arguments,command_configs)
+  def parse_options_helper(args,global_options,command,command_options,arguments,command_configs) # :nodoc:
     non_flag_i = find_non_flag_index(args)
     all_flags = false
     if non_flag_i == 0
@@ -300,7 +397,7 @@ module GLI
       if !command
         command_name = args.shift
         command = find_command(command_name)
-        raise BadCommandLine.new("Unknown command '#{command_name}'") if !command
+        raise UnknownCommand.new("Unknown command '#{command_name}'") if !command
         return parse_options_helper(args,
                                     global_options,
                                     command,
@@ -366,16 +463,16 @@ module GLI
             try_me.delete arg
             break 
           end
-          raise BadCommandLine.new("Unknown argument #{arg}") if arg =~ /^\-/ 
+          raise UnknownCommandArgument.new("Unknown option #{arg}",command) if arg =~ /^\-/ 
         end
         return [global_options,command,command_options,try_me + rest]
       else
         # Now we have our command name
         command_name = try_me.shift
-        raise BadCommandLine.new("Unknown argument #{command_name}") if command_name =~ /^\-/
+        raise UnknownGlobalArgument.new("Unknown option #{command_name}") if command_name =~ /^\-/
 
         command = find_command(command_name)
-        raise BadCommandLine.new("Unknown command '#{command_name}'") if !command
+        raise UnknownCommand.new("Unknown command '#{command_name}'") if !command
 
         return parse_options_helper(rest,
                                     global_options,
@@ -388,11 +485,11 @@ module GLI
 
   end
 
-  def default_command_options(command,command_configs)
+  def default_command_options(command,command_configs) # :nodoc:
     options = (command_configs && command_configs[command.name.to_sym]) || {}
   end
 
-  def find_command(name)
+  def find_command(name) # :nodoc:
     sym = name.to_sym
     return commands[name.to_sym] if commands[sym]
     commands.keys.each do |command_name|
@@ -403,7 +500,7 @@ module GLI
   end
 
   # Checks that the names passed in have not been used in another flag or option
-  def verify_unused(names,flags,switches,context)
+  def verify_unused(names,flags,switches,context) # :nodoc:
     names.each do |name|
       verify_unused_in_option(name,flags,"flag",context)
       verify_unused_in_option(name,switches,"switch",context)
@@ -412,7 +509,7 @@ module GLI
 
   private
 
-  def verify_unused_in_option(name,option_like,type,context)
+  def verify_unused_in_option(name,option_like,type,context) # :nodoc:
     raise ArgumentError.new("#{name} has already been specified as a #{type} #{context}") if option_like[name]
     option_like.each do |one_option_name,one_option|
       if one_option.aliases

data/lib/gli/command.rb

@@ -1,47 +1,62 @@
 require 'gli/command_line_token.rb'
 
 module GLI
-  # A command to be run, in context of global flags and switches
+  # A command to be run, in context of global flags and switches.  You are given an instance of this class
+  # to the block you use for GLI#command.  You then use the methods described here to describe the 
+  # command-specific command-line arguments, much as you use the methods in GLI to describe the global
+  # command-line interface
   class Command < CommandLineToken
 
     # Create a new command
     #
-    # [names] the name or names of this command (symbol or Array of symbols)
-    # [description] description of this command
-    # [arguments_name] description of the arguments, or nil if this command doesn't take arguments
-    # [long_desc] a longer description of the command, possibly with multiple lines and text formatting
-    #
-    def initialize(names,description,arguments_name=nil,long_desc=nil)
+    # +names+:: A String, Symbol, or Array of String or Symbol that represents the name(s) of this command.
+    # +description+:: short description of this command as a Strign
+    # +arguments_name+:: description of the arguments as a String, or nil if this command doesn't take arguments
+    # +long_desc+:: a longer description of the command, possibly with multiple lines and text formatting
+    def initialize(names,description,arguments_name=nil,long_desc=nil) # :nodoc:
       super(names,description,long_desc)
       @arguments_description = arguments_name || ''
       clear_nexts
     end
 
-    def arguments_description; @arguments_description; end
+    # Return the arguments description
+    def arguments_description #:nodoc:
+      @arguments_description
+    end
 
-    def names
+    # Return the Array of the command's names
+    def names #:nodoc:
       all_forms
     end
 
-    def usage
+    # Get the usage string
+    # CR: This should probably not be here
+    def usage #:nodoc:
       usage = name.to_s
-      usage += ' [options]' if !flags.empty? || !switches.empty?
+      usage += ' [command options]' if !flags.empty? || !switches.empty?
       usage += ' ' + @arguments_description if @arguments_description
       usage
     end
 
-    def flags; @flags ||= {}; end
-    def switches; @switches ||= {}; end
+    # Return the flags as a Hash
+    def flags #:nodoc:
+      @flags ||= {}
+    end
+    # Return the switches as a Hash
+    def switches #:nodoc:
+      @switches ||= {}
+    end
 
-    # describe the next switch or flag
+    # describe the next switch or flag just as GLI#desc does.
     def desc(description); @next_desc = description; end
-    # long description of this flag/switch
+    # set the long description of this flag/switch, just as GLI#long_desc does.
     def long_desc(long_desc); @next_long_desc = long_desc; end
-    # describe the argument name of the next flag
+    # describe the argument name of the next flag, just as GLI#arg_name does.
     def arg_name(name); @next_arg_name = name; end
-    # set the default value of the next flag
+    # set the default value of the next flag, just as GLI#default_value does.
     def default_value(val); @next_default_value = val; end
 
+    # Create a command-specific flag, similar to GLI#flag
     def flag(*names)
       names = [names].flatten
       GLI.verify_unused(names,flags,switches,"in command #{name}")
@@ -50,7 +65,7 @@ module GLI
       clear_nexts
     end
 
-    # Create a switch
+    # Create a command-specific switch, similar to GLI#switch
     def switch(*names)
       names = [names].flatten
       GLI.verify_unused(names,flags,switches,"in command #{name}")
@@ -59,22 +74,34 @@ module GLI
       clear_nexts
     end
 
+    # Define the action to take when the user executes this command
+    #
+    # +block+:: A block of code to execute.  The block will be given 3 arguments:
+    #           +global_options+:: A Hash (or Options, see GLI#use_openstruct) of the _global_ options specified
+    #                              by the user, with defaults set and config file values used (if using a config file, see
+    #                              GLI#config_file)
+    #           +options+:: A Hash (or Options, see GLI#use_openstruct) of the command-specific options specified by the 
+    #                       user, with defaults set and config file values used (if using a config file, see GLI#config_file)
+    #           +arguments+:: An Array of Strings representing the unparsed command line arguments
+    #           The block's result value is not used; raise an exception or use GLI#exit_now! if you need an early exit based
+    #           on an error condition
     def action(&block)
       @action = block
     end
 
-    def self.name_as_string(name)
+    def self.name_as_string(name) #:nodoc:
       name.to_s
     end
 
-    def clear_nexts
+    def clear_nexts #:nodoc:
       @next_desc = nil
       @next_arg_name = nil
       @next_default_value = nil
       @next_long_desc = nil
     end
 
-    def execute(global_options,options,arguments)
+    # Executes the command
+    def execute(global_options,options,arguments) #:nodoc:
       @action.call(global_options,options,arguments)
     end
   end

data/lib/gli/command_line_token.rb

@@ -1,22 +1,23 @@
 module GLI
-  # Logical element of a command line, mostly so that subclasses can have similar
+  # 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
-    attr_reader :aliases
-    attr_reader :description
-    attr_reader :long_description
+    attr_reader :name #:ndoc:
+    attr_reader :aliases #:ndoc:
+    attr_reader :description #:ndoc:
+    attr_reader :long_description #:ndoc:
 
-    def initialize(names,description,long_description=nil)
+    def initialize(names,description,long_description=nil) #:ndoc:
       @description = description
       @long_description = long_description
       @name,@aliases,@names = parse_names(names)
     end
 
-    def usage
+    def usage #:nodoc:
       all_forms
     end
 
+    # Sort based on name
     def <=>(other)
       self.name.to_s <=> other.name.to_s
     end

data/lib/gli/exceptions.rb

@@ -1,13 +1,30 @@
 module GLI
   # Indicates that the command line invocation was bad
   class BadCommandLine < Exception
-    def initialize(message)
+    def exit_code; -1; end
+  end
+
+  # Indicates the bad command line was an unknown command
+  class UnknownCommand < BadCommandLine
+  end
+
+  # Indicates the bad command line was an unknown global argument
+  class UnknownGlobalArgument < BadCommandLine
+  end
+
+  # Indicates the bad command line was an unknown command argument
+  class UnknownCommandArgument < BadCommandLine
+    attr_reader :command
+    # +message+:: the error message to show the user
+    # +command+:: the command we were using to parse command-specific options
+    def initialize(message,command)
       super(message)
+      @command = command
     end
   end
 
   # Raise this if you want to use an exit status that isn't the default
-  # provided by GLI.
+  # provided by GLI.  Note that GLI#exit_now! might be a bit more to your liking.
   #
   # Example:
   #
@@ -15,11 +32,11 @@ module GLI
   #     raise CustomExit.new("Bad SQL",-6) unless valid_sql?(args[0])
   #
   class CustomExit < Exception
-    attr_reader :exit_code
+    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, overridding GLI's default
+    # +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

data/lib/gli/flag.rb

@@ -2,7 +2,7 @@ require 'gli/command_line_token.rb'
 
 module GLI
   # Defines a flag, which is to say a switch that takes an argument
-  class Flag < Switch
+  class Flag < Switch # :nodoc:
 
     attr_reader :default_value
 

data/lib/gli/options.rb

@@ -1,12 +1,15 @@
 require 'ostruct'
 
 module GLI
+  # Subclass of OpenStruct that provides hash-like methods for #[] and #[]=.  Note that is is *not* a Hash.
   class Options < OpenStruct
 
+    # Return the value of an attribute
     def[](k)
       @table[k.to_sym]
     end
 
+    # Set the value of an attribute
     def[]=(k, v)
       @table[k.to_sym] = v
     end

data/lib/gli/switch.rb

@@ -2,7 +2,7 @@ require 'gli/command_line_token.rb'
 
 module GLI
   # Defines a command line switch
-  class Switch < CommandLineToken
+  class Switch < CommandLineToken #:nodoc:
 
     def initialize(names,description,long_desc=nil)
       super(names,description,long_desc)
@@ -28,8 +28,8 @@ module GLI
 
     # Finds the switch in the given arg, returning the arg to keep.
     # Returns an array of size 2:
-    # [0] true or false if the arg was found
-    # [1] the remaining arg to keep in the command line or nil to remove it
+    # index 0:: true or false if the arg was found
+    # index 1:: the remaining arg to keep in the command line or nil to remove it
     def find_me(arg)
       if @names[arg]
         return [true,nil]

data/lib/gli/terminal.rb

@@ -1,5 +1,10 @@
 module GLI
-  # Class to encapsulate stuff about the terminal.  This is a singleton, mostly to facilitate testing.
+  # Class to encapsulate stuff about the terminal. This is useful to application developers
+  # as a canonical means to get information about the user's current terminal configuraiton.
+  # GLI uses this to determine the number of columns to use when printing to the screen.
+  #
+  # To access it, use Terminal#instance.  This is a singleton mostly to facilitate testing, but
+  # it seems reasonable enough, since there's only one terminal in effect
   #
   # Example:
   #
@@ -20,29 +25,31 @@ module GLI
 
     # Set the default size of the terminal to use when we can't figure it out
     #
-    # size - array of two int [cols,rows]
+    # +size+:: array of two int [cols,rows]
     def self.default_size=(size)
       @@default_size = size
     end
 
-    # Provide access to the shared instance
+    # Provide access to the shared instance.  
     def self.instance; @@instance ||= Terminal.new; end
 
     # Call this to cause methods to throw exceptions rather than return a sane default.  You
     # probably don't want to call this unless you are writing tests
-    def make_unsafe!;
+    def make_unsafe!
       @unsafe = true
     end
 
     # Returns true if the given command exists on this system
     #
-    # command - The command to check for
+    # +command+:: The command, as a String, to check for, without any path information.
     def command_exists?(command)
       ENV['PATH'].split(File::PATH_SEPARATOR).any? {|d| File.exists? File.join(d, command) }
     end
 
-    # Ripped from hirb https://github.com/cldwalker/hirb/blob/master/lib/hirb/util.rb
-    # Returns an array of size two ints representing the terminal width and height
+    # Get the size of the current terminal.
+    # Ripped from hirb[https://github.com/cldwalker/hirb/blob/master/lib/hirb/util.rb]
+    #
+    # Returns an Array of size two Ints representing the terminal width and height
     def size
       if (ENV['COLUMNS'] =~ /^\d+$/) && (ENV['LINES'] =~ /^\d+$/)
         [ENV['COLUMNS'].to_i, ENV['LINES'].to_i]

data/lib/gli_version.rb

@@ -1,3 +1,3 @@
 module GLI
-  VERSION = '1.2.5'
+  VERSION = '1.2.6'
 end

data/lib/support/help.rb

@@ -3,9 +3,9 @@ require 'gli/command'
 require 'gli/terminal'
 
 module GLI
-  class DefaultHelpCommand < Command
+  class DefaultHelpCommand < Command #:nodoc:
     @@output = $stdout
-    # Exposed for testing :nodoc:
+    # Exposed for testing
     def self.output_device=(o); @@output = o; end
 
     def initialize(version,*omit_from_list)
@@ -47,18 +47,20 @@ module GLI
     private
 
     def list_global_flags
-      usage = "usage: #{GLI.program_name} command"
+      usage = "usage: #{GLI.program_name} "
       all_options = GLI.switches.merge(GLI.flags)
       if !all_options.empty?
-        usage += ' [options]'
+          usage += "[global options] "
       end
+      usage += "command"
+      usage += ' [command options]'
       @@output.puts usage
       @@output.puts
       if @version
         @@output.puts "Version: #{@version}"
         @@output.puts
       end
-      @@output.puts 'Options:' if !all_options.empty?
+      @@output.puts 'Global Options:' if !all_options.empty?
       output_command_tokens_for_help(all_options)
       @@output.puts if !all_options.empty?
     end
@@ -85,7 +87,7 @@ module GLI
         all_options = command.switches.merge(command.flags)
         if !all_options.empty?
           @@output.puts
-          @@output.puts "Options:"
+          @@output.puts "Command Options:"
           output_command_tokens_for_help(all_options)
         end
       else

data/lib/support/initconfig.rb

@@ -3,7 +3,7 @@ require 'gli/command'
 require 'yaml'
 
 module GLI
-  class InitConfig < Command
+  class InitConfig < Command # :nodoc:
     COMMANDS_KEY = 'commands'
 
     def initialize(config_file_name)
@@ -27,8 +27,7 @@ module GLI
           YAML.dump(config,file)
         end
       else
-        puts "Not overwriting existing config file #{@filename}"
-        puts 'Use --force to override'
+        raise "Not overwriting existing config file #{@filename}, use --force to override"
       end
     end
   end

data/lib/support/rdoc.rb

@@ -2,13 +2,50 @@ require 'gli'
 require 'fileutils'
 
 module GLI
-  class RDocCommand < Command
+  class RDocCommand < Command # :nodoc:
 
     def initialize
-      super(:rdoc,'Generates RDoc for your command line interface')
+      super(:rdoc,'Generates RDoc (and other types of documentation) for your command line interface')
+      self.desc 'Create a very basic scaffold for a cheat-style cheatsheet, in addition to rdoc'
+      self.switch 'cheatsheet'
+      self.desc 'Include a manapage suitable for gem man, in addition to rdoc'
+      self.switch 'manpage'
+      self.desc 'Do not create rdoc'
+      self.switch 'no-rdoc'
     end
 
-    def execute(g,o,a)
+    def execute(g,options,a)
+      create_rdoc unless options[:'no-rdoc']
+      create_manpage if options[:manpage]
+      create_cheatsheet if options[:cheatsheet]
+    end
+
+    def create_cheatsheet
+      File.open("#{GLI.program_name}.cheat",'w') do |file|
+        file << GLI.program_name
+        file << "\n"
+        file << GLI.program_name.length.times.inject("") { |a,x| a + "=" }
+        file << "\n"
+        file << "\n"
+        file << "Installation:\n"
+        file << "$ gem install #{GLI.program_name}\n\n"
+        GLI.commands.values.sort.each do |command|
+          next if command == self
+          file << command.description
+          file << "\n"
+          [command.name,command.aliases].flatten.each do |name|
+            next unless name
+            file << "$ #{GLI.program_name} #{name} #{command.arguments_description}\n"
+          end
+          file << "\n"
+        end
+      end
+    end
+
+    def create_manpage
+    end
+
+    def create_rdoc
       File.open("#{GLI.program_name}.rdoc",'w') do |file|
         file << "= <tt>#{GLI.program_name}</tt>\n\n"
         file << "    "

data/lib/support/scaffold.rb

@@ -2,7 +2,7 @@ require 'gli'
 require 'fileutils'
 
 module GLI
-  class Scaffold
+  class Scaffold #:nodoc:
 
     def self.create_scaffold(root_dir,create_test_dir,create_ext_dir,project_name,commands,force=false,dry_run=false)
       dirs = [File.join(root_dir,project_name,'lib')]
@@ -58,6 +58,8 @@ bin/#{project_name}
   s.rdoc_options << '--title' << '#{project_name}' << '--main' << 'README.rdoc' << '-ri'
   s.bindir = 'bin'
   s.executables << '#{project_name}'
+  s.add_development_dependency('rake')
+  s.add_development_dependency('rdoc')
 end
 EOS
       end
@@ -137,8 +139,7 @@ EOS
       puts "Created #{root_dir}/#{project_name}/Rakefile"
       File.open("#{root_dir}/#{project_name}/Gemfile",'w') do |bundler_file|
         bundler_file.puts "source :rubygems"
-        bundler_file.puts "gem: 'rake'"
-        bundler_file.puts "gem: 'rdoc'"
+        bundler_file.puts "gemspec"
       end
       puts "Created #{root_dir}/#{project_name}/Gemfile"
     end
@@ -155,7 +156,7 @@ EOS
 # have this method, so we add it so we get resolved symlinks
 # and compatibility
 unless File.respond_to? :realpath
-  class File
+  class File #:nodoc:
     def self.realpath path
       return realpath(File.readlink(path)) if symlink?(path)
       path
@@ -253,7 +254,7 @@ EOS
       if !force
         dirs.each do |dir|
           if File.exist? dir
-            puts "#{dir} exists; use --force to override"
+            raise "#{dir} exists; use --force to override"
             exists = true
           end
         end
@@ -262,7 +263,7 @@ EOS
         dirs.each do |dir|
           puts "Creating dir #{dir}..."
           if dry_run
-            $stderr.puts "dry-run; #{dir} not created"
+            puts "dry-run; #{dir} not created"
           else
             FileUtils.mkdir_p dir
           end

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: gli
 version: !ruby/object:Gem::Version 
-  hash: 21
   prerelease: false
   segments: 
   - 1
   - 2
-  - 5
-  version: 1.2.5
+  - 6
+  version: 1.2.6
 platform: ruby
 authors: 
 - David Copeland
@@ -15,10 +14,82 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-12 00:00:00 -05:00
+date: 2011-03-06 00:00:00 -05:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 8
+        - 7
+        version: 0.8.7
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 9
+        - 8
+        version: 0.9.8
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 4
+        - 3
+        version: 2.4.3
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: sdoc
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 2
+        - 20
+        version: 0.2.20
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: grancher
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
 description: An application and API for describing command line interfaces that can be used to quickly create a shell for executing command-line tasks.  The command line user interface is similar to Gits, in that it takes global options, a command, command-specific options, and arguments
 email: davidcopeland@naildrivin5.com
 executables: 
@@ -64,7 +135,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -73,7 +143,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"