coglius 0.0.1

data/lib/coglius/copy_options_to_aliases.rb

@@ -0,0 +1,33 @@
+module Coglius
+
+  # Mixin that both Coglius and Command can use to copy command-line options to the aliased versions
+  # of flags and switches
+  #
+  # includers must provide the methods +flags+ and +switches+ that return an Array of Flag or Switch, 
+  # respectively
+  module CopyOptionsToAliases # :nodoc:
+    # For each option in options, copies its value to keys for the aliases of the flags or
+    # switches in gli_like
+    #
+    # options - Hash of options parsed from command line; this is an I/O param
+    def copy_options_to_aliases(options) # :nodoc:
+      new_options = {}
+      options.each do |key,value|
+        if flags[key] && flags[key].aliases
+          copy_aliases(flags[key].aliases,new_options,value)
+        elsif switches[key] && switches[key].aliases
+          copy_aliases(switches[key].aliases,new_options,value)
+        end
+      end
+      options.merge!(new_options)
+    end
+
+    private 
+
+    def copy_aliases(aliases,new_options,value)
+      aliases.each do |alias_name|
+        new_options[alias_name] = value
+      end
+    end
+  end
+end

data/lib/coglius/dsl.rb

@@ -0,0 +1,221 @@
+module Coglius
+  # The primary DSL for Coglius.  This represents the methods shared between your top-level app and
+  # the commands.  See Coglius::Command for additional methods that apply only to command objects.
+  module DSL
+    # 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
+    alias :d :desc
+
+    # Provide a longer, more detailed description.  This
+    # 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.  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.
+    # +options+:: Symbol or array of symbols to annotate this argument.  This doesn't affect parsing, just
+    #             the help output.  Values recognized are:
+    #             +:optional+:: indicates this argument is optional; will format it with square brackets
+    #             +:multiple+:: indicates multiple values are accepted; will format appropriately
+    #
+    # Example:
+    #     desc 'Set the filename'
+    #     arg_name 'file_name'
+    #     flag [:f,:filename]
+    #
+    # Produces:
+    #     -f, --filename=file_name      Set the filename
+    def arg_name(name,options=[])
+      @next_arg_name = name
+      @next_arg_options = options
+    end
+
+    # set the default value of the next flag or switch
+    #
+    # +val+:: 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.  For a switch, this is
+    #         the value to be used if the switch isn't specified on the command-line.  Note that if you
+    #         set a switch to have a default of true, using the switch on the command-line has no effect.
+    #         To disable a switch where the default is true, use the <tt>--no-</tt> form.
+    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.  The last element can be a hash of options:
+    #           +:desc+:: the description, instead of using #desc
+    #           +:long_desc+:: the long_description, instead of using #long_desc
+    #           +:default_value+:: the default value, instead of using #default_value
+    #           +:arg_name+:: the arg name, instead of using #arg_name
+    #           +:must_match+:: A regexp that the flag's value must match
+    #           +:type+:: A Class (or object you passed to Coglius::App#accept) to trigger type coversion
+    #
+    # Example:
+    #
+    #     desc 'Set the filename'
+    #     flag [:f,:filename,'file-name']
+    #
+    #     flag :ipaddress, :desc => "IP Address", :must_match => /\d+\.\d+\.\d+\.\d+/
+    #
+    #     flag :names, :desc => "list of names", :type => Array
+    #
+    # Produces:
+    #
+    #     -f, --filename, --file-name=arg     Set the filename
+    def flag(*names)
+      options = extract_options(names)
+      names = [names].flatten
+
+      verify_unused(names)
+      flag = Flag.new(names,options)
+      flags[flag.name] = flag
+
+      clear_nexts
+      flags_declaration_order << flag
+      flag
+    end
+    alias :f :flag
+
+    # 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.  The last element can be a hash of options:
+    #           +:desc+:: the description, instead of using #desc
+    #           +:long_desc+:: the long_description, instead of using #long_desc
+    #           +:default_value+:: if the switch is omitted, use this as the default value.  By default,  switches default to off, or +false+
+    #           +:negatable+:: if true, this switch will get a negatable form (e.g. <tt>--[no-]switch</tt>, false it will not.  Default is true
+    def switch(*names)
+      options = extract_options(names)
+      names = [names].flatten
+
+      verify_unused(names)
+      switch = Switch.new(names,options)
+      switches[switch.name] = switch
+
+      clear_nexts
+      switches_declaration_order << switch
+      switch
+    end
+    alias :s :switch
+
+    def clear_nexts # :nodoc:
+      @next_desc = nil
+      @next_arg_name = nil
+      @next_arg_options = nil
+      @next_default_value = nil
+      @next_long_desc = nil
+    end
+
+    # Define a new command.  This can be done in a few ways, but the most common method is
+    # to pass a symbol (or Array of symbols) representing the command name (or names) and a block.  
+    # The block 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.
+    #
+    # Alternatively, you can call this with a one element Hash, where the key is the symbol representing the name
+    # of the command, and the value being an Array of symbols representing the commands to call in order, as a 
+    # chained or compound command.  Note that these commands must exist already, and that only those command-specific
+    # options defined in *this* command will be parsed and passed to the chained commands.  This might not be what you expect
+    #
+    # +names+:: a String or Symbol, or an Array of String or Symbol that represent all the different names and aliases 
+    #           for this command *or* a Hash, as described above.
+    #
+    # ==Examples
+    #
+    #     # Make a command named list
+    #     command :list do |c|
+    #       c.action do |global_options,options,args|
+    #         # your command code
+    #       end
+    #     end
+    #
+    #     # Make a command named list, callable by ls as well
+    #     command [:list,:ls] do |c|
+    #       c.action do |global_options,options,args|
+    #         # your command code
+    #       end
+    #     end
+    #
+    #     # Make a command named all, that calls list and list_contexts
+    #     command :all => [ :list, :list_contexts ]
+    #
+    #     # Make a command named all, aliased as :a:, that calls list and list_contexts
+    #     command [:all,:a] => [ :list, :list_contexts ]
+    #
+    def command(*names)
+      command_options = {
+        :description => @next_desc,
+        :arguments_name => @next_arg_name,
+        :arguments_options => @next_arg_options,
+        :long_desc => @next_long_desc,
+        :skips_pre => @skips_pre,
+        :skips_post => @skips_post,
+        :skips_around => @skips_around,
+      }
+      if names.first.kind_of? Hash
+        command = Coglius::Commands::CompoundCommand.new(self,
+                                                     names.first,
+                                                     command_options)
+        command.parent = self
+        commands[command.name] = command
+      else
+        command = Command.new(command_options.merge(:names => [names].flatten))
+        command.parent = self
+        commands[command.name] = command
+        yield command
+      end
+      @commands_declaration_order ||= []
+      @commands_declaration_order << command
+      clear_nexts
+    end
+    alias :c :command
+
+    def flags_declaration_order # :nodoc:
+      @flags_declaration_order ||= []
+    end
+
+    def switches_declaration_order # :nodoc:
+      @switches_declaration_order ||= []
+    end
+
+
+    private
+    # Checks that the names passed in have not been used in another flag or option
+    def verify_unused(names) # :nodoc:
+      names.each do |name|
+        verify_unused_in_option(name,flags,"flag")
+        verify_unused_in_option(name,switches,"switch")
+      end
+    end
+
+    def verify_unused_in_option(name,option_like,type) # :nodoc:
+      return if name.to_s == 'help'
+      raise ArgumentError.new("#{name} has already been specified as a #{type} #{context_description}") if option_like[name]
+      option_like.each do |one_option_name,one_option|
+        if one_option.aliases
+          if one_option.aliases.include? name
+            raise ArgumentError.new("#{name} has already been specified as an alias of #{type} #{one_option_name} #{context_description}") 
+          end
+        end
+      end
+    end
+
+    # Extract the options hash out of the argument to flag/switch and
+    # set the values if using classic style
+    def extract_options(names)
+      options = {}
+      options = names.pop if names.last.kind_of? Hash
+      options = { :desc => @next_desc, 
+                  :long_desc => @next_long_desc,
+                  :default_value => @next_default_value,
+                  :arg_name => @next_arg_name}.merge(options)
+    end
+
+
+  end
+end

data/lib/coglius/exceptions.rb

@@ -0,0 +1,54 @@
+module Coglius
+  # Mixed into all exceptions that Coglius handles; you can use this to catch
+  # anything that came from Coglius intentionally.  You can also mix this into non-Coglius
+  # exceptions to get Coglius's exit behavior.
+  module StandardException
+    def exit_code; 1; end
+  end
+  # Indicates that the command line invocation was bad
+  class BadCommandLine < StandardError
+    include StandardException
+    def exit_code; 64; 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
+    # The command for which the argument was unknown
+    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 Coglius.  Note that Coglius::App#exit_now! might be a bit more to your liking.
+  #
+  # Example:
+  #
+  #     raise CustomExit.new("Not connected to DB",-5) unless connected?
+  #     raise CustomExit.new("Bad SQL",-6) unless valid_sql?(args[0])
+  #
+  class CustomExit < StandardError
+    include StandardException
+    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 (as an Int), overridding Coglius's default
+    def initialize(message,exit_code)
+      super(message)
+      @exit_code = exit_code
+    end
+  end
+end

data/lib/coglius/flag.rb

@@ -0,0 +1,68 @@
+require 'coglius/command_line_option.rb'
+
+module Coglius
+  # Defines a flag, which is to say a switch that takes an argument
+  class Flag < CommandLineOption # :nodoc:
+
+    # Regexp that is used to see if the flag's argument matches
+    attr_reader :must_match
+
+    # Type to which we want to cast the values
+    attr_reader :type
+
+    # Name of the argument that user configured
+    attr_reader :argument_name
+
+    # 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
+    #           :arg_name:: the name of the flag's argument, default is "arg"
+    #           :must_match:: a regexp that the flag's value must match
+    #           :type:: a class to convert the value to
+    #           :mask:: if true, the default value of this flag will not be output in the help.
+    #                   This is useful for password flags where you might not want to show it
+    #                   on the command-line.
+    def initialize(names,options)
+      super(names,options)
+      @argument_name = options[:arg_name] || "arg"
+      @default_value = options[:default_value]
+      @must_match = options[:must_match]
+      @type = options[:type]
+      @mask = options[:mask]
+    end
+
+    def safe_default_value
+      if @mask
+        "********"
+      else
+        default_value
+      end
+    end
+
+    def arguments_for_option_parser
+      args = all_forms_a.map { |name| "#{name} VAL" }
+      args << @must_match if @must_match
+      args << @type if @type
+      args
+    end
+
+    # Returns a string of all possible forms
+    # of this flag.  Mostly intended for printing
+    # to the user.
+    def all_forms(joiner=', ')
+      forms = all_forms_a
+      string = forms.join(joiner)
+      if forms[-1] =~ /^\-\-/
+        string += '='
+      else
+        string += ' '
+      end
+      string += @argument_name
+      return string
+    end
+  end
+end

data/lib/coglius/gli_option_parser.rb

@@ -0,0 +1,124 @@
+module Coglius
+  # Parses the command-line options using an actual +OptionParser+
+  class CogliusOptionParser
+    def initialize(commands,flags,switches,accepts,default_command = nil)
+      @commands = commands
+      @flags = flags
+      @switches = switches
+      @accepts = accepts
+      @default_command = default_command
+    end
+
+    # Given the command-line argument array, returns and array of size 4:
+    #
+    # 0:: global options
+    # 1:: command, as a Command
+    # 2:: command-specific options
+    # 3:: unparsed arguments
+    def parse_options(args) # :nodoc:
+      args_clone = args.clone
+      global_options = {}
+      command = nil
+      command_options = {}
+      remaining_args = nil
+
+      global_options,command_name,args = parse_global_options(OptionParserFactory.new(@flags,@switches,@accepts), args)
+      @flags.each do |name,flag|
+        global_options[name] = flag.default_value unless global_options[name]
+      end
+      @switches.each do |name,switch|
+        global_options[name] = switch.default_value if global_options[name].nil?
+      end
+
+      command_name ||= @default_command || :help
+      command = find_command(command_name)
+      if Array(command).empty?
+        raise UnknownCommand.new("Unknown command '#{command_name}'")
+      elsif command.kind_of? Array
+        raise UnknownCommand.new("Ambiguous command '#{command_name}'. It matches #{command.sort.join(',')}")
+      end
+
+      command_options,args = parse_command_options(OptionParserFactory.new(command.flags,command.switches,@accepts),
+                                                   command,
+                                                   args)
+
+      command.flags.each do |name,flag|
+        command_options[name] = flag.default_value unless command_options[name]
+      end
+      command.switches.each do |name,switch|
+        command_options[name] = switch.default_value if command_options[name].nil?
+      end
+
+      [global_options,command,command_options,args]
+    end
+
+  private
+
+    def parse_command_options(option_parser_factory,command,args)
+      option_parser,command_options = option_parser_factory.option_parser
+      help_args = %w(-h --help).reject { |_| command.has_option?(_) }
+
+      unless help_args.empty?
+        option_parser.on(*help_args) do
+          # We need to raise the help exception later in the process, after
+          # the command-line has been parsed, so we know what command
+          # to show help for.  Unfortunately, we can't just call #action
+          # on the command to override what to do, so...metaprogramming.
+          class << command
+            def execute(*help_args)
+              exception = BadCommandLine.new(nil)
+              class << exception
+                def exit_code; 0; end
+              end
+              raise exception
+            end
+          end
+        end
+      end
+      option_parser.parse!(args)
+      [command_options,args]
+    rescue OptionParser::InvalidOption => ex
+      raise UnknownCommandArgument.new("Unknown option #{ex.args.join(' ')}",command)
+    rescue OptionParser::InvalidArgument => ex
+      raise UnknownCommandArgument.new("#{ex.reason}: #{ex.args.join(' ')}",command)
+    end
+
+    def parse_global_options(option_parser_factory,args,&error_handler)
+      if error_handler.nil?
+        error_handler = lambda { |message|
+          raise UnknownGlobalArgument.new(message)
+        }
+      end
+      option_parser,global_options = option_parser_factory.option_parser
+      command = nil
+      option_parser.order!(args) do |non_option|
+        command = non_option
+        break
+      end
+      [global_options,command,args]
+    rescue OptionParser::InvalidOption => ex
+      error_handler.call("Unknown option #{ex.args.join(' ')}")
+    rescue OptionParser::InvalidArgument => ex
+      error_handler.call("#{ex.reason}: #{ex.args.join(' ')}")
+    end
+
+    def find_command(name) # :nodoc:
+      names_to_commands = {}
+      @commands.each do |command_name,command|
+        names_to_commands[command_name.to_s] = command
+        Array(command.aliases).each do |command_alias|
+          names_to_commands[command_alias.to_s] = command
+        end
+      end
+      names_to_commands.fetch(name.to_s) do |command_to_match|
+        find_command_by_partial_name(names_to_commands, command_to_match)
+      end
+    end
+
+    def find_command_by_partial_name(names_to_commands, command_to_match)
+      partial_matches = names_to_commands.keys.select { |command_name| command_name =~ /^#{command_to_match}/ }
+      return names_to_commands[partial_matches[0]] if partial_matches.size == 1
+      partial_matches
+    end
+  end
+end