gli_aziz_light 2.8.1

data/lib/gli/app_support.rb

@@ -0,0 +1,341 @@
+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 = nil
+      @commands_declaration_order = []
+      @flags_declaration_order = []
+      @switches_declaration_order = []
+      @version = nil
+      @config_file = nil
+      @use_openstruct = false
+      @prog_desc = nil
+      @error_block = false
+      @pre_block = false
+      @post_block = false
+      @default_command = :help
+      @around_block = nil
+      @subcommand_option_handling_strategy = :legacy
+      clear_nexts
+    end
+
+    def exe_name
+      File.basename($0)
+    end
+
+    # Get an array of commands, ordered by when they were declared
+    def commands_declaration_order # :nodoc:
+      @commands_declaration_order
+    end
+
+    # Get the version string
+    def version_string #:nodoc:
+      @version
+    end
+
+    # Get the default command for the entire app
+    def get_default_command
+      @default_command
+    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:
+      args = args.dup if @preserve_argv
+      the_command = nil
+      begin
+        override_defaults_based_on_config(parse_config)
+
+        add_help_switch_if_needed(self)
+
+        gli_option_parser = GLIOptionParser.new(commands,
+                                                flags,
+                                                switches,
+                                                accepts,
+                                                @default_command,
+                                                self.subcommand_option_handling_strategy)
+
+        parsing_result = gli_option_parser.parse_options(args)
+
+        self.options = parsing_result.cli_options
+        parsing_result.global_options[:cli]  = self.options[:global]
+        parsing_result.command_options[:cli] = self.options["commands"][parsing_result.command.name]
+
+        parsing_result.convert_to_openstruct! if @use_openstruct
+
+        the_command = parsing_result.command
+
+        if proceed?(parsing_result)
+          call_command(parsing_result) 
+          0
+        else
+          raise PreconditionFailed, "preconditions failed"
+        end
+      rescue Exception => ex
+        if the_command.nil? && ex.respond_to?(:command_in_context)
+          the_command = ex.command_in_context
+        end
+        handle_exception(ex,the_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
+
+    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
+      @skips_around = 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:
+      if !@commands
+        @commands = { :help => GLI::Commands::Help.new(self), :_doc => GLI::Commands::Doc.new(self) }
+        @commands_declaration_order ||= []
+        @commands_declaration_order << @commands[:help]
+        @commands_declaration_order << @commands[:_doc]
+      end
+      @commands
+    end
+
+    def pre_block
+      @pre_block ||= Proc.new do
+        true
+      end
+    end
+
+    def post_block
+      @post_block ||= Proc.new do
+      end
+    end
+
+    def around_blocks
+      @around_blocks || []
+    end
+
+    def help_sort_type
+      @help_sort_type || :alpha
+    end
+
+    def help_text_wrap_type
+      @help_text_wrap_type || :to_terminal
+    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] || {}
+
+        if @subcommand_option_handling_strategy == :legacy
+          override_default(command.topmost_ancestor.flags,command_config)
+          override_default(command.topmost_ancestor.switches,command_config)
+        else
+          override_default(command.flags,command_config)
+          override_default(command.switches,command_config)
+        end
+
+        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
+
+    def subcommand_option_handling_strategy
+      @subcommand_option_handling_strategy || :legacy
+    end
+
+    # Sets the @options instance variable if it doesn't exist
+    # and returns it. The @options instance variable contains
+    # the options passed by the user on the command line.
+    def options #:nodoc:
+      @options ||= { :global => {}, "commands" => {} }
+    end
+
+    # Sets the @options instance variable, which contains the
+    # options passed by the user on the command line.
+    # If the opts parameter doesn't have the correct format,
+    # the instance variable will be set with the correct format
+    # but the command line options will not be added to it.
+    # If the GLI Debug mode is enabled, an ArguementError exception
+    # will be raised.
+    def options=(opts)
+      if valid_options_hash_format_for?(opts)
+        @options = opts
+      else
+        if ENV['GLI_DEBUG'] == 'true'
+          raise ArgumentError, "The options hash is invalid"
+        end
+
+        @options = { :global => {}, "commands" => {} }
+      end
+    end
+
+  private
+
+    def valid_options_hash_format_for?(opts)
+      valid_options_hash  = opts.is_a?(Hash)
+      valid_global_hash   = opts.has_key?(:global) && opts.fetch(:global).is_a?(Hash)
+      valid_commands_hash = opts.has_key?("commands") && opts.fetch("commands").is_a?(Hash)
+
+      valid_options_hash && valid_global_hash && valid_commands_hash
+    end
+
+    def handle_exception(ex,command)
+      if regular_error_handling?(ex)
+        output_error_message(ex)
+        if ex.kind_of?(OptionParser::ParseError) || ex.kind_of?(BadCommandLine)
+          if commands[:help]
+            command_for_help = command.nil? ? [] : command.name_for_help
+            commands[:help].execute({},{},command_for_help)
+          end
+        end
+      elsif ENV['GLI_DEBUG'] == 'true'
+        stderr.puts "Custom error handler exited false, skipping normal error handling"
+      end
+
+      raise ex if ENV['GLI_DEBUG'] == 'true'
+
+      ex.extend(GLI::StandardException)
+      ex.exit_code
+    end
+
+    def output_error_message(ex)
+      stderr.puts error_message(ex) unless no_message_given?(ex)
+      if ex.kind_of?(OptionParser::ParseError) || ex.kind_of?(BadCommandLine)
+        stderr.puts unless no_message_given?(ex)
+      end
+    end
+
+    def no_message_given?(ex)
+      ex.message == ex.class.name
+
+    end
+
+    def add_help_switch_if_needed(target)
+      help_switch_exists = target.switches.values.find { |switch| 
+        switch.names_and_aliases.map(&:to_s).find { |an_alias| an_alias == 'help' } 
+      }
+      unless help_switch_exists
+        target.desc 'Show this message'
+        target.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?(parsing_result) #:nodoc:
+      if parsing_result.command && parsing_result.command.skips_pre
+        true
+      else
+        pre_block.call(*parsing_result)
+      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 
+        return true if (ex.respond_to?(:exit_code) && ex.exit_code == 0)
+        @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(parsing_result)
+      command        = parsing_result.command
+      global_options = parsing_result.global_options
+      options        = parsing_result.command_options
+      arguments      = parsing_result.arguments.map { |arg| arg.dup } # unfreeze
+
+      code = lambda { command.execute(global_options,options,arguments) }
+      nested_arounds = unless command.skips_around
+                         around_blocks.inject do |outer_around, inner_around|
+                           lambda { |go,c,o,a, code1|
+                             inner = lambda { inner_around.call(go,c,o,a, code1) }
+                             outer_around.call(go,c,o,a, inner)
+                           }
+                         end
+                       end
+
+      if nested_arounds
+        nested_arounds.call(global_options,command, options, arguments, code)
+      else
+        code.call
+      end
+
+      unless command.skips_post
+        post_block.call(global_options,command,options,arguments)
+      end
+    end
+
+  end
+end

data/lib/gli/command.rb

@@ -0,0 +1,171 @@
+require 'gli/command_line_token.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::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 DSL
+    include CommandSupport
+
+    # Key in an options hash to find the parent's parsed options
+    PARENT = Object.new 
+
+    # Create a new command.
+    #
+    # 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
+    #           +skips_around+:: if true, this command advertises that it doesn't want the around block called
+    def initialize(options)
+      super(options[:names],options[:description],options[:long_desc])
+      @arguments_description = options[:arguments_name] || ''
+      @arguments_options = Array(options[:arguments_options]).flatten
+      @skips_pre = options[:skips_pre]
+      @skips_post = options[:skips_post]
+      @skips_around = options[:skips_around]
+      @commands_declaration_order = []
+      @flags_declaration_order = []
+      @switches_declaration_order = []
+      clear_nexts
+    end
+
+    # 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.  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 of the _global_ options specified
+    #                              by the user, with defaults set and config file values used (if using a config file, see
+    #                              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
+
+    # 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
+
+    # Returns true if this command has the given option defined
+    def has_option?(option) #:nodoc:
+      option = option.gsub(/^\-+/,'')
+      ((flags.values.map { |_| [_.name,_.aliases] }) + 
+       (switches.values.map { |_| [_.name,_.aliases] })).flatten.map(&:to_s).include?(option)
+    end
+
+    # Returns full name for help command including parents
+    #
+    # Example
+    #
+    #   command :remote do |t|
+    #     t.command :add do |global,options,args|
+    #     end
+    #   end
+    #
+    #   @add_command.name_for_help # => ["remote", "add"]
+    #
+    def name_for_help
+      name_array = [name.to_s]
+      command_parent = parent
+      while(command_parent.is_a?(GLI::Command)) do
+        name_array.unshift(command_parent.name.to_s)
+        command_parent = command_parent.parent
+      end
+      name_array
+    end
+
+    def self.name_as_string(name,negatable=false) #:nodoc:
+      name.to_s
+    end
+  end
+end