cliqr 1.2.0 → 2.0.0

data/lib/cliqr/config/base.rb

@@ -0,0 +1,84 @@
+# encoding: utf-8
+
+require 'cliqr/config/dsl'
+require 'cliqr/config/validation/verifiable'
+
+module Cliqr
+  # A extension for CLI module to group all config classes
+  #
+  # @api private
+  module Config
+    # A value to initialize configuration attributes with
+    UNSET = Object.new
+
+    # Configuration option to enable arguments for a command (default)
+    ENABLE_CONFIG = :enable
+
+    # Configuration option to disable arguments for a command
+    DISABLE_CONFIG = :disable
+
+    # Option type for regular options
+    ANY_ARGUMENT_TYPE = :any
+
+    # Option type for numeric arguments
+    NUMERIC_ARGUMENT_TYPE = :numeric
+
+    # Option type for boolean arguments
+    BOOLEAN_ARGUMENT_TYPE = :boolean
+
+    # Default values based on argument type
+    ARGUMENT_DEFAULTS = {
+        NUMERIC_ARGUMENT_TYPE => 0,
+        BOOLEAN_ARGUMENT_TYPE => false,
+        ANY_ARGUMENT_TYPE => nil
+    }
+
+    # Get the passed param value if current attribute is unset
+    #
+    # @return [Object]
+    def self.get_if_unset(attribute_value, default_value)
+      return attribute_value unless attribute_value == UNSET
+      if default_value.is_a?(Proc)
+        default_value.call
+      else
+        default_value
+      end
+    end
+
+    # The base configuration setting to build a cli application with its own dsl
+    class Base
+      include Cliqr::Config::DSL
+      include Cliqr::Config::Validation
+
+      # Set value for an attribute
+      #
+      # @param [Symbol] name Name of the config parameter
+      # @param [Object] value Value for the config parameter
+      # @param [Proc] block Function which populates configuration for a sub-attribute
+      #
+      # @return [Object] new attribute's value
+      def set_config(name, value, *_args, &block)
+        value = block if block_given?
+        handle_config(name, value)
+      end
+
+      # Skip validation if this is <tt>true</tt>
+      def skip_validation?
+        false
+      end
+
+      private
+
+      # Set value for an attribute by evaluating a block
+      #
+      # @param [Symbol] name Name of the config option
+      # @param [Object] value Value for the config option
+      #
+      # @return [Object]
+      def handle_config(name, value)
+        public_send("#{name}=", value)
+        value
+      end
+    end
+  end
+end

data/lib/cliqr/config/command.rb

@@ -0,0 +1,137 @@
+# encoding: utf-8
+
+require 'cliqr/command/base_command'
+require 'cliqr/config/action'
+require 'cliqr/config/shell'
+
+module Cliqr
+  module Config
+    # Configuration setting for a command
+    #
+    # @api private
+    class Command < Cliqr::Config::Action
+      # Configuration for the shell for this command
+      #
+      # @return [Cliqr::Command::ShellConfig]
+      attr_accessor :shell
+      validates :shell,
+                child: true
+
+      # Version tag for this configuration
+      #
+      # @return [Stirng]
+      attr_accessor :version
+
+      # Enable or disable colors in a command handler (default enabled)
+      #
+      # @return [Symbol]
+      attr_accessor :color
+      validates :color,
+                inclusion: [Cliqr::Config::ENABLE_CONFIG, Cliqr::Config::DISABLE_CONFIG]
+
+      # New config instance with all attributes set as UNSET
+      def initialize
+        super
+
+        @shell = UNSET
+        @version = UNSET
+        @color = UNSET
+      end
+
+      # Finalize config by adding default values for unset values
+      #
+      # @return [Cliqr::Config::Command]
+      def finalize
+        super
+
+        @color = Config.get_if_unset(@color, Cliqr::Config::ENABLE_CONFIG)
+        @shell = Config.get_if_unset(@shell, proc { Cliqr::Util.build_shell_config(self) })
+        @version = Config.get_if_unset(@version, nil)
+
+        # disable colors in shell if colors are disabled here
+        @shell.disable_color unless color?
+
+        self
+      end
+
+      # Set value for a config option
+      #
+      # @param [Symbol] name Name of the config parameter
+      # @param [Object] value Value for the config parameter
+      # @param [Proc] block Function which populates configuration for a sub-attribute
+      #
+      # @return [Object] attribute's value
+      def set_config(name, value, *args, &block)
+        case name
+        when :shell
+          handle_shell(value, &block)
+        else
+          super
+        end
+      end
+
+      # Set up default attributes for this configuration
+      #
+      # @return [Cliqr::Config::Command] Update config
+      def setup_defaults
+        super
+
+        add_shell
+        add_version
+      end
+
+      # Check if this configuration has shell action enabled
+      #
+      # @return [Boolean]
+      def shell?
+        @shell.enabled?
+      end
+
+      # Check if version is enabled for this command
+      #
+      # @return [Boolean] <tt>true</tt> if help is enabled
+      def version?
+        !@version.nil?
+      end
+
+      # Check if colors are enabled for this setting
+      def color?
+        @color == Cliqr::Config::ENABLE_CONFIG
+      end
+
+      private
+
+      # Handle configuration for shell config
+      #
+      # @param [Symbol] setting Enabled shell if the setting is <tt>BaseConfig::ENABLE_CONFIG</tt>
+      # @param [Proc] block Populate the shell's config in this block
+      #
+      # @return [Cliqr::Config::Shell] Newly created shell config
+      def handle_shell(setting, &block)
+        @shell = Shell.build(&block).tap do |shell_config|
+          unless setting.nil?
+            shell_config.enabled = setting
+            shell_config.finalize
+          end
+        end
+      end
+
+      # Add version command and option to this config
+      #
+      # @return [Cliqr::Config::Command] Updated config
+      def add_version
+        return self unless version?
+        add_action(Cliqr::Util.build_version_action(self)) unless action?('version')
+        add_option(Cliqr::Util.build_version_option(self)) unless option?('version')
+      end
+
+      # Add shell command
+      #
+      # @return [Cliqr::Config::Command] Updated config
+      def add_shell
+        return self unless shell?
+        add_action(Cliqr::Util.build_shell_action(self, @shell)) unless action?('shell')
+      end
+    end
+  end
+end

data/lib/cliqr/config/dsl.rb

@@ -0,0 +1,81 @@
+# encoding: utf-8
+
+require 'delegate'
+
+module Cliqr
+  module Config
+    # Used to separate all dsl methods in a separate block, thus allowing
+    # separation of concerns between non-dsl methods with dsl methods which
+    # improves maintainability.
+    #
+    # @api private
+    module DSL
+      # 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
+          def self.inherited(base)
+            transfer_validations(base)
+            DSL.included(base)
+          end
+
+          def self.transfer_validations(base)
+            base.validations.merge(validations)
+          end
+
+          # Entry point for invoking dsl methods
+          #
+          # @param [Hash] args Arguments to be used to build the DSL instance
+          #
+          # @param [Function] block The block to evaluate the DSL
+          #
+          # @return [Cliqr::DSL]
+          def self.build(*args, &block)
+            base = new(*args)
+            if block_given?
+              delegator = DSLDelegator.new(base)
+              delegator.instance_eval(&block)
+            end
+            base.finalize
+            base
+          end
+        end
+      end
+
+      # Delegates all DSL methods to the base class. Can be used to keep DSL
+      # methods separate from non-dsl methods. All implementing subclasses will
+      # have to implement a set_config method as described below
+      #
+      #     class MyDSLClass
+      #       include Cliqr::Config::DSL
+      #
+      #       attr_accessor :attribute
+      #
+      #       def set_config(name, value, &block)
+      #         # handle config value for attribute "name"
+      #       end
+      #     end
+      #
+      # This will be invoked as:
+      #
+      #     MyDSLClass.build do
+      #       attribute 'some-value'
+      #     end
+      class DSLDelegator < SimpleDelegator
+        # All dsl methods are handled dynamically by proxying through #set_config
+        #
+        # @param [Symbol] name Name of the method
+        # @param [Array] args Method arguments
+        # @param [Function] block A function to evaluate in the context of the method's arguments
+        #
+        # @return [Object] The return value of the proxied method
+        def method_missing(name, *args, &block)
+          __getobj__.set_config(name, args[0], *args[1..-1], &block)
+        end
+      end
+    end
+  end
+end

data/lib/cliqr/config/event.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+
+require 'cliqr/events/handler'
+
+module Cliqr
+  module Config
+    # The configuration setting which defines a event
+    class Event < Cliqr::Config::Base
+      # Name of the event
+      #
+      # @return [String]
+      attr_accessor :name
+      validates :name,
+                non_empty_format: /^[a-zA-Z0-9_\-]+$/
+
+      # Event handler
+      #
+      # @return [Cliqr::Events::Handler]
+      attr_accessor :handler
+      validates :handler,
+                one_of: [
+                  { type_of: Cliqr::Events::Handler },
+                  { type_of: Proc }
+                ]
+
+      # New config instance with all attributes set as UNSET
+      def initialize
+        @name = UNSET
+        @handler = UNSET
+      end
+
+      # Finalize config by adding default values for unset values
+      #
+      # @return [Cliqr::Config::Base]
+      def finalize
+        @name = Config.get_if_unset(@name, '')
+        @handler = Config.get_if_unset(@handler, nil)
+
+        self
+      end
+    end
+  end
+end

data/lib/cliqr/config/event_based.rb

@@ -0,0 +1,78 @@
+# encoding: utf-8
+
+require 'cliqr/config/event'
+
+module Cliqr
+  module Config
+    # The configuration that enabled events for another configuration
+    class EventBased < Cliqr::Config::Base
+      # Events to listen for
+      #
+      # @return [Hash] A hash of <tt>String => Cliqr::Config::Event</tt>
+      attr_accessor :events
+      validates :events,
+                hash: true
+
+      # New instance of event based config
+      def initialize
+        @events = {}
+      end
+
+      # Add a event
+      #
+      # @param [Symbol] name Name of the attribute
+      # @param [String] event_name Event's name
+      # @param [Array] args Event handler
+      # @param [Proc] block Event handler function
+      #
+      # @return [Cliqr::Config::Event] Newly added event
+      def set_config(name, event_name, *args, &block)
+        case name
+        when :on
+          # if defined, args[0] will be the custom event handler class
+          handle_event(event_name, args[0], &block)
+        else
+          super
+        end
+      end
+
+      # Check if a event can be handled in this context
+      def handle?(name)
+        @events.key?(name.to_s)
+      end
+
+      # Get a event handler config by name
+      #
+      # @return [Cliqr::Config::Event]
+      def event(name)
+        @events[name.to_s]
+      end
+
+      private
+
+      # Handle the case when a event is added to the config
+      #
+      # @return [Cliqr::Events::Event]
+      def handle_event(event_name, event_class, &event_block)
+        fail Cliqr::Error::ValidationError, 'only one of event_class or event_block are allowed' \
+          if !event_class.nil? && block_given?
+
+        event_handler = event_class
+        event_handler = event_block if event_class.nil?
+        event = build_event(event_name, event_handler)
+        @events[event.name.to_s] = event
+      end
+
+      # Builds a event invocation handler wrapper
+      #
+      # @return [Cliqr::Events::Event]
+      def build_event(event_name, event_handler)
+        Cliqr::Config::Event.new.tap do |event|
+          event.name = event_name if event_name.is_a?(String) || event_name.is_a?(Symbol)
+          event.handler = event_handler
+          event.finalize
+        end
+      end
+    end
+  end
+end

data/lib/cliqr/config/named.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+require 'cliqr/config/event_based'
+
+module Cliqr
+  # A extension for CLI module to group all config classes
+  #
+  # @api private
+  module Config
+    # The configuration setting to build a named configuration instance
+    class Named < Cliqr::Config::EventBased
+      # Name of the config instance
+      #
+      # @return [String]
+      attr_accessor :name
+      validates :name,
+                non_empty_format: /^[a-zA-Z0-9_\-]+$/
+
+      # Description for the config instance
+      #
+      # @return [String]
+      attr_accessor :description
+
+      # New config instance with all attributes set as UNSET
+      def initialize
+        super
+
+        @name = UNSET
+        @description = UNSET
+      end
+
+      # Finalize config by adding default values for unset values
+      #
+      # @return [Cliqr::Config::Named]
+      def finalize
+        @name = Config.get_if_unset(@name, '')
+        @description = Config.get_if_unset(@description, '')
+
+        self
+      end
+
+      # Check if a option's description is defined
+      #
+      # @return [Boolean] <tt>true</tt> if options' description is not null neither empty
+      def description?
+        !(@description.nil? || @description.empty?)
+      end
+
+      # Check if this config has a valid name
+      def name?
+        @name.is_a?(String) && !@name.empty?
+      end
+    end
+  end
+end