cliqr 1.1.0 → 1.2.0

data/lib/cliqr/error.rb

@@ -55,7 +55,7 @@ module Cliqr
     class ValidationError < CliqrError; end
 
     # Encapsulates the error that gets thrown during a command execution
-    class CommandRuntimeException < CliqrError; end
+    class CommandRuntimeError < CliqrError; end
 
     # Error to signify that a command's runner is not available
     class UnknownCommandRunnerException < CliqrError; end
@@ -69,16 +69,22 @@ module Cliqr
     # Indicates that a option has multiple values in the command line
     class MultipleOptionValues < CliqrError; end
 
-    # Raised if two options are defined with same long or short name
+    # Raised if more than one option is defined with same long or short name
     class DuplicateOptions < CliqrError; end
 
-    # Raised if an option is not defined properly
-    class InvalidArgumentError < CliqrError; end
+    # Raised if multiple actions are defined with same name at the same nesting level
+    class DuplicateActions < CliqrError; end
 
     # Raised if an argument does not conform to the option's type
     class IllegalArgumentError < CliqrError; end
 
     # Indicates that a unknown validator type is being used in a class
     class UnknownValidatorType < CliqrError; end
+
+    # Indicates that a unknown action was invoked
+    class UnknownActionError < CliqrError; end
+
+    # Raised when a command is executed that is not supposed to run
+    class IllegalCommandError < CliqrError; end
   end
 end

data/lib/cliqr/parser/action_token.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+module Cliqr
+  module Parser
+    # Token handler for parsing action commands
+    #
+    # @api private
+    class ActionToken < Token
+      # Create a new action token
+      def initialize(_name)
+        super(arg)
+      end
+
+      # This token is valid if argument is non-empty
+      #
+      # @return [Boolean] <tt>true</tt> if token's argument is non-empty
+      def valid?
+        return false if arg.nil?
+        !arg.empty?
+      end
+    end
+  end
+end

data/lib/cliqr/parser/argument_parser.rb

@@ -12,7 +12,7 @@ module Cliqr
     # @param [Cliqr::CLI::Config] config Command line configuration
     # @param [Array<String>] args An array of arguments from command line
     #
-    # @return [Hash] Parsed hash of command linet arguments
+    # @return [Hash] Parsed action config and hash of command line arguments
     def self.parse(config, args)
       tree_walker = ArgumentTreeWalker.new(config)
       tree_walker.walk(args)

data/lib/cliqr/parser/argument_token.rb

@@ -16,10 +16,7 @@ module Cliqr
       # @return [Boolean] <tt>true</tt> if token's argument is non-empty
       def valid?
         return false if arg.nil?
-
-        return !arg.empty? if @arg.respond_to?(:empty?)
-
-        true
+        !arg.empty?
       end
     end
   end

data/lib/cliqr/parser/argument_tree_walker.rb

@@ -20,19 +20,38 @@ module Cliqr
 
       # Parse the arguments and generate tokens by iterating over command line arguments
       #
-      # @param [Array<String>] args List of arguments that needs to parsed
+      # @param [Array<String>] raw_args List of arguments that needs to parsed
       #
-      # @return [Hash] Parsed hash of command line arguments
-      def walk(args)
-        input_builder = ParsedInputBuilder.new(@config)
-        token_factory = TokenFactory.new(@config)
+      # @return [Array] Action config and parsed hash of command line arguments
+      def walk(raw_args)
+        action_config, args = parse_action(raw_args)
+        input_builder = ParsedInputBuilder.new(@config, action_config)
+        token_factory = TokenFactory.new(action_config)
         token = token_factory.get_token
         args.each do |arg|
           token = handle_argument(arg, token, token_factory, input_builder)
         end
-        fail Cliqr::Error::OptionValueMissing, "a value must be defined for argument \"#{token.arg}\"" \
-          if token.active?
-        input_builder.build
+        fail Cliqr::Error::OptionValueMissing, \
+             "a value must be defined for argument \"#{token.arg}\"" if token.active?
+        ensure_default_action(action_config, input_builder)
+      end
+
+      private
+
+      # Parse the action from the list of arguments
+      #
+      # @return [Cliqr::CLI::Config] Configuration of the command invoked and remaining arguments
+      def parse_action(raw_args)
+        args = []
+        action_config = @config
+        raw_args.each do |arg|
+          if action_config.action?(arg)
+            action_config = action_config.action(arg)
+          else
+            args.push(arg)
+          end
+        end
+        [action_config, args]
       end
 
       # Handle the next argument in the context of the current token
@@ -50,6 +69,19 @@ module Cliqr
 
         token
       end
+
+      # Make sure default options are processed by overriding action
+      #
+      # @return [Array] Action config and parsed hash of command line arguments
+      def ensure_default_action(action_config, input_builder)
+        parsed_input = input_builder.build
+        default_action_name = parsed_input.default_action(action_config)
+        unless default_action_name.nil?
+          action_config = action_config.action(default_action_name)
+          parsed_input.remove_option(default_action_name)
+        end
+        [action_config, parsed_input]
+      end
     end
   end
 end

data/lib/cliqr/parser/option_token.rb

@@ -46,7 +46,8 @@ module Cliqr
 
       # Collect this token's name and value into a input builder
       #
-      # @param [Cliqr::Parser::ParsedInputBuilder] input_builder A builder to prepare parsed arguments
+      # @param [Cliqr::Parser::ParsedInputBuilder] input_builder A builder to prepare parsed
+      # arguments
       #
       # @return [Cliqr::Parser::ParsedInputBuilder] The updated input builder instance
       def collect(input_builder)

data/lib/cliqr/parser/parsed_input.rb

@@ -25,7 +25,7 @@ module Cliqr
         @command = parsed_arguments[:command]
 
         @options = Hash[parsed_arguments[:options].collect \
-            { |option| [option[:name], option[:value]] }]\
+            { |option| [option[:name].to_s, option[:value]] }]\
             if parsed_arguments.key?(:options)
 
         @arguments = parsed_arguments[:arguments]
@@ -37,7 +37,14 @@ module Cliqr
       #
       # @return [String]
       def option(name)
-        @options[name]
+        @options[name.to_s]
+      end
+
+      # Remove a option
+      #
+      # @return [Object] Option's original value
+      def remove_option(name)
+        @options.delete(name.to_s)
       end
 
       # Test equality with another object
@@ -55,6 +62,18 @@ module Cliqr
       def ==(other)
         eql?(other)
       end
+
+      # Get name of default action if present as option
+      #
+      # @return [Symbol] Name of the default action or <tt>nil</tt> if not present
+      def default_action(action_config)
+        if option('help') && action_config.help?
+          return :help
+        elsif option('version') && action_config.version?
+          return :version
+        end
+        nil
+      end
     end
   end
 end

data/lib/cliqr/parser/parsed_input_builder.rb

@@ -14,8 +14,10 @@ module Cliqr
       # @param [Cliqr::CLI::Config] config Configuration settings for the command line interface
       #
       # @return [Cliqr::CLI::Parser::ParsedInputBuilder]
-      def initialize(config)
+      def initialize(config, action_config)
         @config = config
+        @action_config = action_config
+        @actions = []
         @options = []
         @option_names = Set.new
         @arguments = []
@@ -23,7 +25,8 @@ module Cliqr
 
       # Add a new parsed option token from the list of options
       #
-      # @param [Cliqr::CLI::Parser::OptionToken] token A parsed option token from command line arguments
+      # @param [Cliqr::CLI::Parser::OptionToken] token A parsed option token from command line
+      # arguments
       #
       # @return [Cliqr::Parser::ParsedInputBuilder] Updated input builder
       def add_option_token(token)
@@ -37,11 +40,11 @@ module Cliqr
 
       # Add a argument to the list of parsed arguments
       #
-      # @param [String] arg Argument value
+      # @param [Cliqr::CLI::Parser::ArgumentToken] token Argument token
       #
       # @return [Cliqr::Parser::ParsedInputBuilder] Updated input builder
-      def add_argument(arg)
-        @arguments.push(arg)
+      def add_argument_token(token)
+        @arguments.push(token.arg) if token.valid?
         self
       end
 
@@ -49,7 +52,8 @@ module Cliqr
       #
       # @return [Cliqr::Parser::ParsedInput] Parsed arguments wrapper
       def build
-        ParsedInput.new(:command => @config.basename,
+        ParsedInput.new(:command => @config.name,
+                        :actions => @actions,
                         :options => @options,
                         :arguments => @arguments)
       end
@@ -62,7 +66,7 @@ module Cliqr
       #
       # @return [Set<String>] Current list of option names
       def add_option_name(token)
-        option_config = @config.option(token.name)
+        option_config = @action_config.option(token.name)
         old_config = @option_names.add?(option_config.name)
         fail Cliqr::Error::MultipleOptionValues,
              "multiple values for option \"#{token.arg}\"" if old_config.nil?

data/lib/cliqr/parser/token.rb

@@ -27,20 +27,14 @@ module Cliqr
         @active
       end
 
-      # This token is never valid
-      #
-      # @return [Boolean] Always <tt>false</tt>
-      def valid?
-        false
-      end
-
       # Collect this token's argument into a input builder
       #
-      # @param [Cliqr::Parser::ParsedInputBuilder] input_builder A builder to prepare parsed arguments
+      # @param [Cliqr::Parser::ParsedInputBuilder] input_builder A builder to prepare parsed
+      # arguments
       #
       # @return [Cliqr::Parser::ParsedInputBuilder] The updated input builder instance
       def collect(input_builder)
-        input_builder.add_argument(@arg)
+        input_builder.add_argument_token(self)
       end
 
       protected

data/lib/cliqr/parser/token_factory.rb

@@ -35,7 +35,7 @@ module Cliqr
             option_config = get_option_config(Regexp.last_match(2), arg)
             build_token(option_config, arg)
           else
-            fail Cliqr::Error::InvalidArgumentError, "invalid command argument \"#{arg}\"" \
+            fail Cliqr::Error::IllegalArgumentError, "invalid command argument \"#{arg}\"" \
               unless @config.arguments?
             ArgumentToken.new(arg)
           end

data/lib/cliqr/util.rb

@@ -0,0 +1,135 @@
+# encoding: utf-8
+
+require 'cliqr/cli/shell_command'
+
+module Cliqr
+  # Utility methods
+  #
+  # @api private
+  class Util
+    # Ensure that a variable is a instance object not a class type
+    #
+    # @return [Object]
+    def self.ensure_instance(obj)
+      return obj.new if obj.class == Class
+      obj
+    end
+
+    # Build a help action for a parent config
+    #
+    # @return [Cliqr::CLI::Config] New action config
+    def self.build_help_action(config)
+      cli = Cliqr.interface do
+        name 'help'
+        description "The help action for command \"#{config.command}\" which provides details " \
+                    'and usage information on how to use the command.'
+        handler Util.help_action_handler(config)
+        help :disable if config.help?
+        shell :disable
+      end
+      cli.config
+    end
+
+    # Build a help option for a parent config
+    #
+    # @return [Cliqr::CLI::OptionConfig] New option config
+    def self.build_help_option(config)
+      Cliqr::CLI::OptionConfig.new.tap do |option_config|
+        option_config.name = 'help'
+        option_config.short = 'h'
+        option_config.description = "Get helpful information for action \"#{config.command}\" " \
+                                    'along with its usage information.'
+        option_config.type = Cliqr::CLI::BOOLEAN_ARGUMENT_TYPE
+        option_config.operator = Cliqr::CLI::ArgumentOperator::DEFAULT_ARGUMENT_OPERATOR
+        option_config.finalize
+      end
+    end
+
+    # Build a version action for a parent config
+    #
+    # @return [Cliqr::CLI::Config] New action config
+    def self.build_version_action(config)
+      cli = Cliqr.interface do
+        name 'version'
+        description "Get version information for command \"#{config.command}\"."
+        handler do
+          puts config.version
+        end
+        shell :disable
+      end
+      cli.config
+    end
+
+    # Build a version option for a parent config
+    #
+    # @return [Cliqr::CLI::OptionConfig] New option config
+    def self.build_version_option(config)
+      Cliqr::CLI::OptionConfig.new.tap do |option_config|
+        option_config.name = 'version'
+        option_config.short = 'v'
+        option_config.description = "Get version information for command \"#{config.command}\"."
+        option_config.type = Cliqr::CLI::BOOLEAN_ARGUMENT_TYPE
+        option_config.operator = Cliqr::CLI::ArgumentOperator::DEFAULT_ARGUMENT_OPERATOR
+        option_config.finalize
+      end
+    end
+
+    # Action handler for help action
+    #
+    # @return [Proc]
+    def self.help_action_handler(config)
+      proc do
+        fail Cliqr::Error::IllegalArgumentError,
+             "too many arguments for \"#{command}\" command" if arguments.length > 1
+        action_config = arguments.length == 0 ? config : config.action(arguments.first)
+        puts Cliqr::CLI::UsageBuilder.build(action_config)
+      end
+    end
+
+    # Build a shell action for a parent config
+    #
+    # @return [Cliqr::CLI::Config] New action config
+    def self.build_shell_action(config)
+      cli = Cliqr.interface do
+        name 'shell'
+        description "Execute a shell in the context of \"#{config.command}\" command."
+        handler Cliqr::CLI::ShellCommand
+        shell :disable
+      end
+      cli.config
+    end
+
+    # Sanitize raw command line arguments
+    #
+    # @return [Array<String>]
+    def self.sanitize_args(args, config = nil)
+      sanitized = []
+      if args.is_a?(Array)
+        args.each { |arg| sanitized.concat(sanitize_args(arg)) }
+      elsif args.is_a?(String)
+        sanitized = args.split(' ')
+      end
+      remove_base_command(sanitized, config)
+    end
+
+    # Remove base command form sanitized list of arguments
+    #
+    # @return [Array<String>]
+    def self.remove_base_command(sanitized, config)
+      if !config.nil? && sanitized[0] == config.root.name.to_s
+        sanitized.drop(1)
+      else
+        sanitized
+      end
+    end
+
+    # Get handler that forwards command to the help action
+    #
+    # @return [Proc]
+    def self.forward_to_help_handler
+      proc do
+        forward "#{command} help"
+      end
+    end
+  end
+end

data/lib/cliqr/version.rb

@@ -2,5 +2,5 @@
 
 # Versioned gem
 module Cliqr
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

data/spec/argument_parser_spec_helper.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+require 'cliqr/parser/argument_parser'
+require 'cliqr/parser/parsed_input'
+
+require 'fixtures/test_command'
+
+def assert_results(config, args, expected_result, expected_config = nil)
+  expected_config ||= config
+  action_config, actual_parsed_input = Cliqr::Parser.parse(config, args)
+  expect(actual_parsed_input).to eq(expected_result)
+  expect(action_config).to eq(expected_config)
+end