coglius 0.0.1

data/lib/coglius/app_support.rb

@@ -0,0 +1,284 @@
+module Coglius
+  # 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 Coglius 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
+      clear_nexts
+    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
+      command = nil
+      begin
+        override_defaults_based_on_config(parse_config)
+
+        add_help_switch_if_needed(switches)
+
+        global_options,command,options,arguments = CogliusOptionParser.new(commands,flags,switches,accepts,@default_command).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)
+          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
+      @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 => Coglius::Commands::Help.new(self), :_doc => Coglius::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] || {}
+
+        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)
+        output_error_message(ex)
+        if ex.kind_of?(OptionParser::ParseError) || ex.kind_of?(BadCommandLine)
+          commands[:help] and commands[:help].execute({},{},command.nil? ? [] : [command.name.to_s])
+        end
+      end
+
+      raise ex if ENV['Coglius_DEBUG'] == 'true'
+
+      ex.extend(Coglius::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
+
+    # Possibly returns a copy of the passed-in Hash as an instance of Coglius::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 Coglius'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
+      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/coglius/command.rb

@@ -0,0 +1,149 @@
+require 'coglius/command_line_token.rb'
+require 'coglius/copy_options_to_aliases.rb'
+require 'coglius/dsl.rb'
+
+module Coglius
+  # 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 Coglius::DSL#command.  This class mixes in Coglius::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 Coglius::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 Coglius::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.
+    #
+    # 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
+    #                              Coglius::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 
+    #                       Coglius::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 Coglius#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 Coglius::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
+
+    def self.name_as_string(name,negatable=false) #:nodoc:
+      name.to_s
+    end
+  end
+end

data/lib/coglius/command_line_option.rb

@@ -0,0 +1,34 @@
+require 'coglius/command_line_token.rb'
+
+module Coglius
+  # 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