gli 1.6.0 → 2.0.0.rc3

data/lib/gli/app.rb

@@ -0,0 +1,184 @@
+require 'etc'
+require 'optparse'
+require 'gli/copy_options_to_aliases'
+require 'gli/dsl'
+
+module GLI
+  # A means to define and parse a command line interface that works as
+  # Git's does, in that you specify global options, a command name, command
+  # specific options, and then command arguments.
+  module App
+    include CopyOptionsToAliases
+    include DSL
+    include AppSupport
+
+    # Loads ruby files in the load path that start with 
+    # +path+, which are presumed to be commands for your executable.
+    # This is a glorified +require+, but could also be used as a plugin mechanism.
+    # You could manipualte the load path at runtime and this call
+    # would find those files
+    #
+    # path:: a path relative to somewhere in the <code>LOAD_PATH</code>, from which all <code>.rb</code> files will be required.
+    def commands_from(path)
+      $LOAD_PATH.each do |load_path|
+        commands_path = File.join(load_path,path)
+        if File.exists? commands_path
+          Dir.entries(commands_path).each do |entry|
+            file = File.join(commands_path,entry)
+            if file =~ /\.rb$/
+              require file
+            end
+          end
+        end
+      end
+    end
+
+    # Describe the overall application/programm.  This should be a one-sentence summary
+    # of what your program does that will appear in the help output.
+    #
+    # +description+:: A String of the short description of your program's purpose
+    def program_desc(description=nil) 
+      if description
+        @program_desc = description
+      end
+      @program_desc
+    end
+
+    # Use this if the following command should not have the pre block executed.
+    # By default, the pre block is executed before each command and can result in
+    # aborting the call.  Using this will avoid that behavior for the following command
+    def skips_pre
+      @skips_pre = true
+    end
+
+    # Use this if the following command should not have the post block executed.
+    # By default, the post block is executed after each command.
+    # Using this will avoid that behavior for the following command
+    def skips_post
+      @skips_post = true
+    end
+
+    # 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>File.expand_path('~')</code>.
+    def config_file(filename)
+      if filename =~ /^\//
+        @config_file = filename
+      else
+        @config_file = File.join(File.expand_path(ENV['HOME']),filename)
+      end
+      commands[:initconfig] = InitConfig.new(@config_file,commands,flags,switches)
+      @config_file
+    end
+
+    # Define a block to run after command line arguments are parsed
+    # but before any command is run.  If this block raises an exception
+    # the command specified will not be executed.
+    # The block will receive the global-options,command,options, and arguments
+    # If this block evaluates to true, the program will proceed; otherwise
+    # the program will end immediately
+    def pre(&a_proc)
+      @pre_block = a_proc
+    end
+
+    # 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
+    end
+
+    # Define a block to run if an error occurs.
+    # The block will receive any Exception that was caught.
+    # 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 +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
+
+    # Configure a type conversion not already provided by the underlying OptionParser.
+    # This works more or less like the OptionParser version.
+    #
+    # object:: the class (or whatever) that triggers the type conversion
+    # block:: the block that will be given the string argument and is expected
+    #         to return the converted value
+    #
+    # Example
+    #
+    #     accept(Hash) do |value|
+    #       result = {}
+    #       value.split(/,/) do |pair|
+    #         k,v = pair.split(/:/)
+    #         result[k] = v
+    #       end
+    #       result
+    #     end
+    #
+    #     flag :properties, :type => Hash
+    def accept(object,&block)
+      accepts[object] = block
+    end
+
+    # Simpler means of exiting with a custom exit code.  This will 
+    # raise a CustomExit with the given message and exit code, which will ultimatley
+    # cause your application to exit with the given exit_code as its exit status
+    # Use #help_now! if you want to show the help in addition to the error message
+    #
+    # message:: message to show the user
+    # exit_code:: exit code to exit as, defaults to 1
+    def exit_now!(message,exit_code=1)
+      raise CustomExit.new(message,exit_code)
+    end
+
+    # Exit now, showing the user help for the command they executed.  Use #exit_now! to just show the error message
+    #
+    # message:: message to indicate how the user has messed up the CLI invocation
+    def help_now!(message)
+      exception = OptionParser::ParseError.new(message)
+      class << exception
+        def exit_code; 64; end
+      end
+      raise exception
+    end
+
+    def program_name(override=nil) #:nodoc:
+      warn "#program_name has been deprecated"
+    end
+
+    # Sets a default command to run when none is specified on the command line.  Note that
+    # if you use this, you won't be able to pass arguments, flags, or switches
+    # to the command when run in default mode.  All flags and switches are treated
+    # as global, and any argument will be interpretted as the command name and likely
+    # fail.
+    #
+    # +command+:: Command as a Symbol to run as default
+    def default_command(command)
+      @default_command = command.to_sym
+    end
+  end
+end

data/lib/gli/app_support.rb

@@ -0,0 +1,226 @@
+module GLI
+  # Internals for make App work
+  module AppSupport
+    # Override the device of stderr; exposed only for testing
+    def error_device=(e) #:nodoc:
+      @stderr = e
+    end
+
+    def context_description
+      "in global context"
+    end
+
+    # Reset the GLI module internal data structures; mostly useful for testing
+    def reset # :nodoc:
+      switches.clear
+      flags.clear
+      commands.clear
+      @version = nil
+      @config_file = nil
+      @use_openstruct = false
+      @prog_desc = nil
+      @error_block = false
+      @pre_block = false
+      @post_block = false
+      @default_command = :help
+      clear_nexts
+    end
+
+    # Get the version string
+    def version_string #:nodoc
+      @version
+    end
+
+    # Runs whatever command is needed based on the arguments. 
+    #
+    # +args+:: the command line ARGV array
+    #
+    # Returns a number that would be a reasonable exit code
+    def run(args) #:nodoc:
+      command = nil
+      begin
+        override_defaults_based_on_config(parse_config)
+
+        add_help_switch_if_needed(switches)
+
+        global_options,command,options,arguments = GLIOptionParser.new(commands,flags,switches,accepts).parse_options(args)
+
+        copy_options_to_aliased_versions(global_options,command,options)
+
+        global_options = convert_to_openstruct_if_needed(global_options)
+        options        = convert_to_openstruct_if_needed(options)
+
+        if proceed?(global_options,command,options,arguments)
+          command ||= commands[:help]
+          call_command(command,global_options,options,arguments)
+        end
+        0
+      rescue Exception => ex
+        handle_exception(ex,command)
+      end
+    end
+
+
+    # Return the name of the config file; mostly useful for generating help docs
+    def config_file_name #:nodoc:
+      @config_file
+    end
+
+    def accepts #:nodoc:
+      @accepts ||= {}
+    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) # :nodoc:
+      copy_options_to_aliases(global_options)
+      command.copy_options_to_aliases(options)
+    end
+
+    def parse_config # :nodoc:
+      config = {
+        'commands' => {},
+      }
+      if @config_file && File.exist?(@config_file)
+        require 'yaml'
+        config.merge!(File.open(@config_file) { |file| YAML::load(file) })
+      end
+      config
+    end
+
+    def clear_nexts # :nodoc:
+      super
+      @skips_post = false
+      @skips_pre = false
+    end
+
+    def stderr
+      @stderr ||= STDERR
+    end
+
+    def self.included(klass)
+      @stderr = $stderr
+    end
+
+    def flags # :nodoc:
+      @flags ||= {}
+    end
+
+    def switches # :nodoc:
+      @switches ||= {}
+    end
+
+    def commands # :nodoc:
+      @commands ||= {:help => GLI::Commands::Help.new(self)}
+    end
+
+    def pre_block
+      @pre_block ||= Proc.new do
+        true
+      end
+    end
+
+    def post_block
+      @post_block ||= Proc.new do
+      end
+    end
+
+    # Sets the default values for flags based on the configuration
+    def override_defaults_based_on_config(config)
+      override_default(flags,config)
+      override_default(switches,config)
+
+      override_command_defaults(commands,config)
+    end
+
+    def override_command_defaults(command_list,config)
+      command_list.each do |command_name,command|
+        next if command_name == :initconfig || command.nil?
+        command_config = (config['commands'] || {})[command_name] || {}
+
+        override_default(command.topmost_ancestor.flags,command_config)
+        override_default(command.topmost_ancestor.switches,command_config)
+
+        override_command_defaults(command.commands,command_config)
+      end
+    end
+
+    def override_default(tokens,config)
+      tokens.each do |name,token|
+        token.default_value=config[name] if config[name]
+      end
+    end
+
+  private
+
+    def handle_exception(ex,command)
+      if regular_error_handling?(ex)
+        stderr.puts error_message(ex) 
+        if ex.kind_of?(OptionParser::ParseError) || ex.kind_of?(BadCommandLine)
+          stderr.puts 
+          commands[:help] and commands[:help].execute([],[],command.nil? ? [] : [command.name.to_s])
+        end
+      end
+
+      raise ex if ENV['GLI_DEBUG'] == 'true'
+
+      ex.extend(GLI::StandardException)
+      ex.exit_code
+    end
+
+    # 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>
+    # in your CLI definition, it will
+    def convert_to_openstruct_if_needed(options) # :nodoc:
+      @use_openstruct ? Options.new(options) : options
+    end
+
+    def add_help_switch_if_needed(switches)
+      help_switch_exists = switches.values.find { |switch| 
+        (Array(switch.aliases) + [switch.name]).find { |an_alias| 
+          an_alias.to_s == 'help' 
+        } 
+      }
+      unless help_switch_exists
+        desc 'Show this message'
+        switch :help, :negatable => false
+      end
+    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 command && command.skips_pre
+        true
+      else
+        pre_block.call(global_options,command,options,arguments) 
+      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:
+      "error: #{ex.message}"
+    end
+
+    def call_command(command,global_options,options,arguments)
+      arguments = arguments.map { |arg| arg.dup } # unfreeze
+      command.execute(global_options,options,arguments)
+      unless command.skips_post
+        post_block.call(global_options,command,options,arguments)
+      end
+    end
+
+  end
+end

data/lib/gli/command.rb

@@ -1,124 +1,136 @@
 require 'gli/command_line_token.rb'
 require 'gli/copy_options_to_aliases.rb'
+require 'gli/dsl.rb'
 
 module GLI
   # 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
+  # to the block you use for GLI::DSL#command.  This class mixes in GLI::DSL so all of those methods are available
+  # to describe the command, in addition to the methods documented here, most importantly
+  # #action.
+  #
+  # Example:
+  #
+  #     command :list do |c| # <- c is an instance of GLI::Command
+  #       c.desc 'use long form'
+  #       c.switch :l
+  #
+  #       c.action do |global,options,args|
+  #         # list things here
+  #       end
+  #
+  #       c.command :tasks do |t| # <- t is an instance of GLI::Command
+  #         # this is a "subcommand" of list
+  #         
+  #         t.action do |global,options,args|
+  #           # do whatever list tasks should do
+  #         end
+  #       end
+  #     end
+  #
   class Command < CommandLineToken
     include CopyOptionsToAliases
+    include DSL
+    include CommandSupport
 
-    # Create a new command
+    # Create a new command.
     #
-    # +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
-    # +skips_pre+:: if true, this command advertises that it doesn't want the pre block called first
-    # +skips_post+:: if true, this command advertises that it doesn't want the post block called after it
-    def initialize(names,description,arguments_name=nil,long_desc=nil,skips_pre=false,skips_post=false) # :nodoc:
-      super(names,description,long_desc)
-      @arguments_description = arguments_name || ''
-      @skips_pre = skips_pre
-      @skips_post = skips_post
+    # options:: Keys should be:
+    #           +names+:: A String, Symbol, or Array of String or Symbol that represents the name(s) of this command (required).
+    #           +description+:: short description of this command as a String
+    #           +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.  A double line-break is treated
+    #                         as a paragraph break.  No other formatting is respected, though inner whitespace is maintained.
+    #           +skips_pre+:: if true, this command advertises that it doesn't want the pre block called first
+    #           +skips_post+:: if true, this command advertises that it doesn't want the post block called after it
+    def initialize(options)
+      super(options[:names],options[:description],options[:long_desc])
+      @arguments_description = options[:arguments_name] || ''
+      @skips_pre = options[:skips_pre]
+      @skips_post = options[:skips_post]
       clear_nexts
     end
 
-    # Return the arguments description
-    def arguments_description #:nodoc:
-      @arguments_description
-    end
-
-    # If true, this command doesn't want the pre block run before it executes
-    def skips_pre #:nodoc:
-      @skips_pre
-    end
-
-    # If true, this command doesn't want the post block run before it executes
-    def skips_post #:nodoc:
-      @skips_post
-    end
-
-    # Return the Array of the command's names
-    def names #:nodoc:
-      all_forms
-    end
-
-    # Get the usage string
-    # CR: This should probably not be here
-    def usage #:nodoc:
-      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 #:nodoc:
-      @flags ||= {}
-    end
-    # Return the switches as a Hash
-    def switches #:nodoc:
-      @switches ||= {}
-    end
-
-    # describe the next switch or flag just as GLI#desc does.
-    def desc(description); @next_desc = description; end
-    # 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, just as GLI#arg_name does.
-    def arg_name(name); @next_arg_name = name; end
-    # 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}")
-      flag = Flag.new(names,@next_desc,@next_arg_name,@next_default_value,@next_long_desc)
-      flags[flag.name] = flag
-      clear_nexts
-    end
-
-    # Create a command-specific switch, similar to GLI#switch
-    def switch(*names)
-      names = [names].flatten
-      GLI.verify_unused(names,flags,switches,"in command #{name}")
-      switch = Switch.new(names,@next_desc,@next_long_desc)
-      switches[switch.name] = switch
-      clear_nexts
+    # Set the default command if this command has subcommands and the user doesn't 
+    # provide a subcommand when invoking THIS command.  When nil, this will show an error and the help
+    # for this command; when set, the command with this name will be executed.
+    #
+    # +command_name+:: The primary name of the subcommand of this command that should be run by default as a String or Symbol.
+    def default_command(command_name)
+      @default_command = command_name
     end
 
-    # Define the action to take when the user executes this command
+    # Define the action to take when the user executes this command.  Every command should either define this 
+    # action block, or have subcommands (or both).
     #
     # +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
+    #           +global_options+:: A Hash 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)
+    #                              GLI::App#config_file)
+    #           +options+:: A Hash of the command-specific options specified by the 
+    #                       user, with defaults set and config file values used (if using a config file, see 
+    #                       GLI::App#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) #:nodoc:
-      name.to_s
-    end
-
-    def clear_nexts #:nodoc:
-      @next_desc = nil
-      @next_arg_name = nil
-      @next_default_value = nil
-      @next_long_desc = nil
+    # Describes this commands action block when it *also* has subcommands.
+    # In this case, the GLI::DSL#desc value is the general description of the commands
+    # that this command groups, and the value for *this* method documents what
+    # will happen if you omit a subcommand.
+    #
+    # Note that if you omit the action block and specify a subcommand, that subcommand's
+    # description will be used to describe what happens by default.
+    #
+    # desc:: the description of what this command's action block does.
+    #
+    # Example
+    #
+    #     desc 'list things'
+    #     command :list do |c|
+    #
+    #       c.desc 'list tasks'
+    #       c.command :tasks do |t|
+    #         t.action do |global,options,args|
+    #         end
+    #       end
+    #
+    #       c.desc 'list contexts'
+    #       c.command :contexts do |t|
+    #         t.action do |global,options,args|
+    #         end
+    #       end
+    #
+    #       c.default_desc 'list both tasks and contexts'
+    #       c.action do |global,options,args|
+    #         # list everything
+    #       end
+    #     end
+    #
+    #
+    #     > todo help list
+    #     NAME
+    #         list - List things
+    #     
+    #     SYNOPSIS
+    #         todo [global options] list [command options] 
+    #         todo [global options] list [command options]  tasks
+    #         todo [global options] list [command options]  contexts
+    #     
+    #     COMMANDS
+    #         <default> - list both tasks and contexts
+    #         tasks     - list tasks
+    #         contexts  - list contexts
+    #
+    def default_desc(desc)
+      @default_desc = desc
     end
 
-    # Executes the command
-    def execute(global_options,options,arguments) #:nodoc:
-      @action.call(global_options,options,arguments)
+    def self.name_as_string(name,negatable=false) #:nodoc:
+      name.to_s
     end
   end
 end