cliqr 1.2.0 → 2.0.0

data/lib/cliqr/config/validation/verifiable.rb

@@ -0,0 +1,91 @@
+# encoding: utf-8
+
+require 'cliqr/validation_errors'
+require 'cliqr/config/validation/validator_factory'
+require 'cliqr/config/validation/validation_set'
+
+module Cliqr
+  module Config
+    # Validation framework for the command line interface config definition adopted from
+    # lotus/validations by @jodosha
+    #
+    # @api private
+    #
+    # @see https://github.com/lotus/validations
+    module Validation
+      # If a class includes this module, we add a few useful methods to that class
+      #
+      # @see http://www.ruby-doc.org/core/Module.html#method-i-included
+      #
+      # @return [Object]
+      def self.included(base)
+        base.class_eval do
+          extend Verifiable
+        end
+      end
+
+      # Check if the class is valid based on the configured attribute validations
+      #
+      # @return [Boolean] <tt>true</tt> if there are no validation errors
+      def valid?
+        validate
+
+        errors.empty?
+      end
+
+      # Run the validation against all attribute values
+      #
+      # @return [Hash] All validated attributed attributes and their values
+      def validate
+        read_attributes.each do |name, value|
+          validations.validate(name, value, errors)
+        end
+      end
+
+      # Get the list of validations to be performed
+      #
+      # @return [Hash] A hash of attribute name to its validator
+      def validations
+        self.class.__send__(:validations)
+      end
+
+      # Read current values for all attributes that must be validated
+      #
+      # @return [Hash] All attributes that must be validated along with their current values
+      def read_attributes
+        {}.tap do |attributes|
+          validations.each_key do |attribute|
+            attributes[attribute] = public_send(attribute)
+          end
+        end
+      end
+
+      # Get a list of errors after validation finishes
+      #
+      # @return [Cliqr::ValidationErrors] A wrapper of all errors
+      def errors
+        @errors ||= ValidationErrors.new
+      end
+
+      # Validations DSL
+      module Verifiable
+        # Add a new validation for a attribute
+        #
+        # @param [Symbol] name Name of the attribute to validate
+        # @param [Object] options Configuration to initialize a attribute validator with
+        #
+        # @return [Cliqr::Config::Validation::ValidationSet]
+        def validates(name, options)
+          validations.add(name, options)
+        end
+
+        # Get or create a new <tt>Cliqr::Config::Validation::ValidationSet</tt>
+        #
+        # @return [Cliqr::Config::Validation::ValidationSet]
+        def validations
+          @validations ||= ValidationSet.new
+        end
+      end
+    end
+  end
+end

data/lib/cliqr/error.rb

@@ -6,6 +6,15 @@ module Cliqr
     #
     # @api private
     class CliqrError < StandardError
+      class << self
+        # The error code based on the error condition
+        #
+        # @return [Integer]
+        attr_accessor :error_code
+      end
+
+      @error_code = 100
+
       # Set up the error to wrap another error's trace
       #
       # @param [String] error_message A short error description
@@ -55,7 +64,14 @@ module Cliqr
     class ValidationError < CliqrError; end
 
     # Encapsulates the error that gets thrown during a command execution
-    class CommandRuntimeError < CliqrError; end
+    class CommandRuntimeError < CliqrError
+      @error_code = 101
+    end
+
+    # Raised if an argument does not conform to the option's type
+    class IllegalArgumentError < CliqrError
+      @error_code = 102
+    end
 
     # Error to signify that a command's runner is not available
     class UnknownCommandRunnerException < CliqrError; end
@@ -75,9 +91,6 @@ module Cliqr
     # 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
 
@@ -86,5 +99,8 @@ module Cliqr
 
     # Raised when a command is executed that is not supposed to run
     class IllegalCommandError < CliqrError; end
+
+    # Raised if event invocation is in invalid state
+    class InvocationError < CliqrError; end
   end
 end

data/lib/cliqr/events/event.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+
+module Cliqr
+  module Events
+    # Defines a event and its properties
+    #
+    # @api private
+    class Event
+      # Event's name
+      #
+      # @return [String]
+      attr_reader :name
+
+      # Command that was first invoked which resulted in this event
+      #
+      # @return [String]
+      attr_reader :command
+
+      # Time when the event was invoked
+      #
+      # @return [Time]
+      attr_reader :timestamp
+
+      # If this event was invoked from another event handler, this will ne non-nil
+      #
+      # @return [Cliqr::Events::Event]
+      attr_reader :parent
+
+      # Create a new event
+      def initialize(name, command, parent)
+        @name = name
+        @command = command
+        @parent = parent
+        @timestamp = Time.now
+        @propagate = true
+      end
+
+      # Check if this event has a parent event
+      def parent?
+        !parent.nil?
+      end
+
+      # Control event propagation
+      def propagate?
+        @propagate
+      end
+
+      # Unset propagation bit
+      #
+      # @return [Boolean]
+      def stop_propagation
+        @propagate = false
+      end
+    end
+  end
+end

data/lib/cliqr/events/event_context.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+module Cliqr
+  module Events
+    # The context in which event handlers are invoked
+    #
+    # @api private
+    class EventContext
+      # Create a new event context to execute events
+      def initialize(invoker, context, event)
+        @invoker = invoker
+        @context = context
+        @event = event
+      end
+
+      # Invoke a event handler chain by name
+      #
+      # @return [Boolean]
+      def invoke(event_name, *args)
+        @invoker.invoke(event_name, @event, *args)
+      end
+
+      # Handle the case when a method is invoked to get an option value
+      #
+      # @return [Object] Option's value
+      def method_missing(name, *_args, &_block)
+        @context.get_or_check_option(name)
+      end
+    end
+  end
+end

data/lib/cliqr/events/handler.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+
+module Cliqr
+  # Set of classes to manage and facilitate event handling
+  #
+  # @api private
+  module Events
+    # Event handler that all event handlers come from
+    class Handler
+      # Create a instance of event handler
+      def initialize(context)
+        @context = context
+      end
+
+      # Handle a incoming event needs to be implemented in a subclass
+      #
+      # @throws [Cliqr::Error::InvocationError]
+      #
+      # @return [Nothing]
+      def handle(*_args)
+        fail Cliqr::Error::InvocationError, 'handle method not implemented by handler class'
+      end
+
+      # Invoker another event
+      #
+      # @return [Boolean]
+      def invoke(*args)
+        @context.invoke(*args)
+      end
+    end
+  end
+end

data/lib/cliqr/events/invoker.rb

@@ -0,0 +1,70 @@
+# encoding: utf-8
+
+require 'cliqr/events/event'
+require 'cliqr/events/event_context'
+
+module Cliqr
+  module Events
+    # Invokes a event and associated event-chain by propagating the event
+    #
+    # @api private
+    class Invoker
+      # Create a new event invoker instance
+      #
+      # @param [Cliqr::Config::Action] config
+      def initialize(config, context)
+        @config = config
+        @context = context
+      end
+
+      # Invoke a event in the context of the configuration set in this invoker
+      #
+      # @return [Boolean] <tt>true</tt> if the event was handled by an associated handler
+      def invoke(event_name, parent_event, *args)
+        handled = false
+        current_config = @config
+        event = build_event(event_name, parent_event)
+        loop do
+          if current_config.handle?(event_name)
+            handle(event, current_config.event(event_name), *args)
+            handled = true
+            break unless event.propagate?
+          end
+          break if current_config.root?
+          current_config = current_config.parent
+        end
+        handled
+      end
+
+      private
+
+      # Build a event by name
+      #
+      # @return [Cliqr::Events::Event]
+      def build_event(name, parent_event)
+        Events::Event.new(name, @config.command, parent_event)
+      end
+
+      # Handle invocation of a event
+      #
+      # @return [Nothing]
+      def handle(event, event_config, *args)
+        context = Events::EventContext.new(self, @context, event)
+        context.instance_exec(event, *args, &wrap(event_config.handler, context))
+      rescue StandardError => e
+        raise Cliqr::Error::InvocationError.new("failed invocation for #{event.name}", e)
+      end
+
+      # Wrap the event invocation handler in a proc
+      #
+      # @return [Proc]
+      def wrap(event_handler, context)
+        return event_handler if event_handler.is_a?(Proc)
+        handler = event_handler.new(context)
+        proc do |*args|
+          handler.handle(*args)
+        end
+      end
+    end
+  end
+end

data/lib/cliqr/{cli → executor}/command_runner_factory.rb

@@ -3,7 +3,7 @@
 require 'stringio'
 
 module Cliqr
-  module CLI
+  module Executor
     # Factory class to get instance of CommandRunner based on input options
     #
     # @api private
@@ -12,8 +12,8 @@ module Cliqr
       #
       # @param [Hash] options Used to build a command runner instance
       #
-      # @return [Cliqr::CLI::StandardCommandRunner] If default output is require from command
-      # @return [Cliqr::CLI::BufferedCommandRunner] If command's output needs to be buffered
+      # @return [Cliqr::Executor::StandardCommandRunner] If default output is require from command
+      # @return [Cliqr::Executor::BufferedCommandRunner] If command's output needs to be buffered
       def self.get(**options)
         case options[:output]
         when :default

data/lib/cliqr/{cli → executor}/router.rb

@@ -1,18 +1,18 @@
 # encoding: utf-8
 
-require 'cliqr/cli/command_runner_factory'
+require 'cliqr/executor/command_runner_factory'
 
 module Cliqr
-  module CLI
+  module Executor
     # Used for routing the command to the appropriate command handler based on the interface config
     #
     # @api private
     class Router
       # Create a new Router instance
       #
-      # @param [Cliqr::CLI::Config] config Command line configuration
+      # @param [Cliqr::Config::Command] config Command line configuration
       #
-      # @return [Cliqr::CLI::Router]
+      # @return [Cliqr::Interface::Router]
       def initialize(config)
         @config = config
       end

data/lib/cliqr/{cli/executor.rb → executor/runner.rb}

@@ -1,17 +1,18 @@
 # encoding: utf-8
 
-require 'cliqr/cli/router'
-require 'cliqr/cli/command_context'
 require 'cliqr/argument_validation/validator'
 require 'cliqr/parser/argument_parser'
+require 'cliqr/command/command_context'
+require 'cliqr/executor/router'
 
 module Cliqr
-  module CLI
-    # Handles command execution with error handling
-    #
-    # @api private
-    class Executor
-      # Create a new command executor
+  # Handles command execution with error handling
+  #
+  # @api private
+  module Executor
+    # The command runner that handles errors as well
+    class Runner
+      # Create a new command runner
       def initialize(config)
         @config = config
         @validator = Cliqr::ArgumentValidation::Validator.new
@@ -27,11 +28,11 @@ module Cliqr
         args = Cliqr::Util.sanitize_args(args, @config)
         action_config, parsed_input = parse(args)
         begin
-          command_context = CommandContext.build(action_config, parsed_input, options) \
+          command_context = Command::CommandContext.build(action_config, parsed_input, options) \
             do |forwarded_args, forwarded_options|
               execute(forwarded_args, options.merge(forwarded_options))
             end
-          Router.new(action_config).handle(command_context, **options)
+          Executor::Router.new(action_config).handle(command_context, **options)
         rescue StandardError => e
           raise Cliqr::Error::CommandRuntimeError.new(
             "command '#{action_config.command}' failed", e)
@@ -55,5 +56,19 @@ module Cliqr
         [action_config, parsed_input]
       end
     end
+
+    # Exit code mapper based on error type
+    #
+    # @api private
+    class ExitCode
+      # Get exit code based on type
+      #
+      # @return [Integer]
+      def self.code(type)
+        return 0 if type == :success
+        return type.class.error_code if type.class.respond_to?(:error_code)
+        99
+      end
+    end
   end
 end

data/lib/cliqr/interface.rb

@@ -0,0 +1,98 @@
+# encoding: utf-8
+
+require 'cliqr/error'
+require 'cliqr/executor/runner'
+require 'cliqr/usage/usage_builder'
+
+# The top level module
+module Cliqr
+  # The execution interface to a command line application built using Cliqr
+  #
+  # @api private
+  class Interface
+    # Command line interface configuration
+    #
+    # @return [Cliqr::CLI::Config]
+    attr_accessor :config
+
+    # Create a new interface instance with a config
+    #
+    # @param [Cliqr::Config::Command] config Config used to create this interface
+    def initialize(config)
+      @config = config
+      @runner = Executor::Runner.new(config)
+    end
+
+    # Get usage information of this command line interface instance
+    #
+    # @return [String] Defines usage of this interface
+    def usage
+      Usage::UsageBuilder.new(:cli).build(config)
+    end
+
+    # Execute a command
+    #
+    # @param [Array<String>] args Arguments that will be used to execute the command
+    # @param [Hash] options Options for command execution
+    #
+    # @return [Integer] Exit code of the command execution
+    def execute(args = [], **options)
+      execute_internal(args, options)
+      Executor::ExitCode.code(:success)
+    rescue Cliqr::Error::CliqrError => e
+      puts e.message
+      Executor::ExitCode.code(e)
+    end
+
+    # Executes a command without handling error conditions
+    #
+    # @return [Integer] Exit code
+    def execute_internal(args = [], **options)
+      options = {
+          :output => :default,
+          :environment => :cli
+      }.merge(options)
+      @runner.execute(args, options)
+    end
+
+    # Invoke the builder method for [Cliqr::CLI::Interface]
+    #
+    # @param [Cliqr::CLI::Config] config Instance of the command line config
+    #
+    # @return [Cliqr::CLI::Interface]
+    def self.build(config)
+      InterfaceBuilder.new(config).build
+    end
+  end
+
+  private
+
+  # Builder for [Cliqr::CLI::Interface]
+  #
+  # @api private
+  class InterfaceBuilder
+    # Start building a command line interface
+    #
+    # @param [Cliqr::CLI::Config] config the configuration options for the
+    # interface (validated using CLI::Validator)
+    #
+    # @return [Cliqr::CLI::ConfigBuilder]
+    def initialize(config)
+      @config = config
+    end
+
+    # Validate and build a cli interface based on the configuration options
+    #
+    # @return [Cliqr::CLI::Interface]
+    #
+    # @throws [Cliqr::Error::ConfigNotFound] if a config is <tt>nil</tt>
+    # @throws [Cliqr::Error::ValidationError] if the validation for config fails
+    def build
+      fail Cliqr::Error::ConfigNotFound, 'a valid config should be defined' if @config.nil?
+      fail Cliqr::Error::ValidationError, \
+           "invalid Cliqr interface configuration - [#{@config.errors}]" unless @config.valid?
+
+      Interface.new(@config)
+    end
+  end
+end