cliqr 1.1.0 → 1.2.0

data/lib/cliqr/cli/command_runner_factory.rb

@@ -49,8 +49,8 @@ module Cliqr
       def run
         old_stdout = $stdout
         old_stderr = $stderr
-        $stdout = StringIO.new('', 'w')
-        $stderr = StringIO.new('', 'w')
+        $stdout = old_stdout.is_a?(StringIO) ? old_stdout : StringIO.new('', 'w')
+        $stderr = old_stderr.is_a?(StringIO) ? old_stderr : StringIO.new('', 'w')
         yield
         {
             :stdout => $stdout.string,

data/lib/cliqr/cli/config.rb

@@ -1,8 +1,10 @@
 # encoding: utf-8
 
 require 'cliqr/dsl'
+require 'cliqr/util'
 require 'cliqr/config_validation/verifiable'
 require 'cliqr/cli/command'
+require 'cliqr/cli/argument_operator'
 
 module Cliqr
   # A extension for CLI module to group all config classes
@@ -10,6 +12,28 @@ module Cliqr
     # 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
+    }
+
     # The configuration setting to build a cli application with its own dsl
     #
     # @api private
@@ -17,11 +41,11 @@ module Cliqr
       extend Cliqr::DSL
       include Cliqr::ConfigValidation
 
-      # Base name of the command
+      # Name of the command
       #
       # @return [String]
-      attr_accessor :basename
-      validates :basename,
+      attr_accessor :name
+      validates :name,
                 non_empty_format: /^[a-zA-Z0-9_\-]+$/
 
       # Description for the base command
@@ -34,14 +58,17 @@ module Cliqr
       # @return [Class<Cliqr::CLI::Command>]
       attr_accessor :handler
       validates :handler,
-                extend: Cliqr::CLI::Command
+                one_of: {
+                    extend: Cliqr::CLI::Command,
+                    type_of: Proc
+                }
 
-      # Optional attribute that dictates whether this command can take arbitrary arguments
+      #  Dictates whether this command can take arbitrary arguments (optional)
       #
-      # @return [Symbol] Either <tt>:enabled</tt> or <tt>:disabled</tt>
+      # @return [Symbol] Either <tt>#ENABLE_CONFIG</tt> or <tt>#DISABLE_CONFIG</tt>
       attr_accessor :arguments
       validates :arguments,
-                inclusion: [:enable, :disable]
+                inclusion: [ENABLE_CONFIG, DISABLE_CONFIG]
 
       # Array of options applied to the base command
       #
@@ -50,44 +77,103 @@ module Cliqr
       validates :options,
                 collection: true
 
+      # Array of children action configs for this action
+      #
+      # @return [Array<Cliqr::CLI::Config>]
+      attr_accessor :actions
+      validates :actions,
+                collection: true
+
+      # Enable or disable help command and option
+      #
+      # @return [Symbol] Either <tt>#ENABLE_CONFIG</tt> or <tt>#DISABLE_CONFIG</tt>
+      attr_accessor :help
+      validates :help,
+                inclusion: [ENABLE_CONFIG, DISABLE_CONFIG]
+
+      # Enable or disable the shell action for base config
+      #
+      # @return [Symbol] Either <tt>#ENABLE_CONFIG</tt> or <tt>#DISABLE_CONFIG</tt>
+      attr_accessor :shell
+      validates :shell,
+                inclusion: [ENABLE_CONFIG, DISABLE_CONFIG]
+
+      # Version tag for this configuration
+      #
+      # @return [Stirng]
+      attr_accessor :version
+
+      # Parent configuration
+      #
+      # @return [Cliqr::CLI::Config]
+      attr_accessor :parent
+
+      # Root config
+      #
+      # @return [Cliqr::CLI::Config]
+      attr_accessor :root
+
       # New config instance with all attributes set as UNSET
       def initialize
-        @basename = UNSET
+        @name = UNSET
         @description = UNSET
         @handler = UNSET
         @arguments = UNSET
+        @help = UNSET
+        @shell = UNSET
+        @version = UNSET
 
         @options = []
         @option_index = {}
+
+        @actions = []
+        @action_index = {}
       end
 
       # Finalize config by adding default values for unset values
       #
       # @return [Cliqr::CLI::Config]
       def finalize
-        @basename = '' if @basename == UNSET
-        @description = '' if @description == UNSET
-        @handler = nil if @handler == UNSET
-        @arguments = :enable if @arguments == UNSET
+        @name = Config.get_if_unset(@name, '')
+        @description = Config.get_if_unset(@description, '')
+        @handler = Util.ensure_instance(Config.get_if_unset(@handler, nil))
+        @arguments = Config.get_if_unset(@arguments, ENABLE_CONFIG)
+        @help = Config.get_if_unset(@help, ENABLE_CONFIG)
+        @root = self
+        @shell = Config.get_if_unset(@shell, shell_default)
+        @version = Config.get_if_unset(@version, nil)
 
         self
       end
 
+      # Set up default attributes for this configuration
+      #
+      # @return [Cliqr::CLI::Config] Update config
+      def setup_defaults
+        add_shell
+        add_version
+        add_help
+        @handler = Cliqr::Util.forward_to_help_handler if @handler.nil? && help? && actions?
+        @actions.each(&:setup_defaults)
+      end
+
       # Set value for a config option
       #
       # @param [Symbol] name Name of the config parameter
-      #
       # @param [Object] value Value for the config parameter
-      #
-      # @param [Function] block Function which populates configuration for a sub-attribute
+      # @param [Proc] block Function which populates configuration for a sub-attribute
       #
       # @return [Object] if setting a attribute's value
       # @return [Cliqr::CLI::OptionConfig] if adding a new option
+      # @return [Cliqr::CLI::Config] if adding a new action
       def set_config(name, value, &block)
         case name
         when :option
           handle_option value, &block # value is the long name for the option
+        when :action
+          handle_action value, &block # value is action's name
         else
+          value = block if block_given?
           handle_config name, value
         end
       end
@@ -103,9 +189,9 @@ module Cliqr
       #
       # @param [String] name Name of the option to check
       #
-      # @return [Boolean] <tt>true</tt> if the a CLI config's option is set
+      # @return [Boolean] <tt>true</tt> if the CLI config's option is set
       def option?(name)
-        @option_index.key?(name)
+        @option_index.key?(name.to_s)
       end
 
       # Get value of a option
@@ -114,14 +200,83 @@ module Cliqr
       #
       # @return [String] value for the option
       def option(name)
-        @option_index[name]
+        @option_index[name.to_s]
+      end
+
+      # Check if particular action exists
+      #
+      # @param [String] name Name of the action to check
+      #
+      # @return [Boolean] <tt>true</tt> if the action exists in the configuration
+      def action?(name)
+        return false if name.nil?
+        @action_index.key?(name.to_sym)
+      end
+
+      # Check if this config has sub actions
+      #
+      # @return [Array<Cliqr::CLI::Config]>
+      def actions?
+        !@actions.empty?
+      end
+
+      # Get action config by name
+      #
+      # @param [String] name Name of the action
+      #
+      # @return [Cliqr::CLI::Config] Configuration of the action
+      def action(name)
+        @action_index[name.to_sym]
       end
 
       # Check if arguments are enabled for this configuration
       #
       # @return [Boolean] <tt>true</tt> if arguments are enabled
       def arguments?
-        @arguments == :enable
+        @arguments == ENABLE_CONFIG
+      end
+
+      # Get name of the command along with the action upto this config
+      #
+      # @return [String] Serialized command name
+      def command
+        return name unless parent?
+        "#{@parent.command} #{name}"
+      end
+
+      # Check if this config has a parent config
+      #
+      # @return [Boolean] <tt>true</tt> if there exists a parent action for this action
+      def parent?
+        !@parent.nil?
+      end
+
+      # Check if help is enabled for this command
+      #
+      # @return [Boolean] <tt>true</tt> if help is enabled
+      def help?
+        @help == ENABLE_CONFIG
+      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 this is the root config
+      #
+      # @return [Boolean]
+      def root?
+        self == @root
+      end
+
+      # Check if this configuration has shell action enabled
+      #
+      # @return [Boolean]
+      def shell?
+        @shell == ENABLE_CONFIG
       end
 
       private
@@ -137,27 +292,59 @@ module Cliqr
         value
       end
 
-      # Add a new option for the command
+      # Handle configuration for a new option
       #
       # @param [Symbol] name Long name of the option
-      #
-      # @param [Function] block Populate the option's config in this funciton block
+      # @param [Proc] block Populate the option's config in this funciton block
       #
       # @return [Cliqr::CLI::OptionConfig] Newly created option's config
       def handle_option(name, &block)
         option_config = OptionConfig.build(&block)
         option_config.name = name
+        add_option(option_config)
+      end
 
+      # Add a new option for the command
+      #
+      # @return [Cliqr::CLI::OptionConfig] Newly added option's config
+      def add_option(option_config)
         validate_option_name(option_config)
 
-        @options.push option_config
-
-        @option_index[option_config.name] = option_config
-        @option_index[option_config.short] = option_config if option_config.short?
+        @options.push(option_config)
+        @option_index[option_config.name.to_s] = option_config
+        @option_index[option_config.short.to_s] = option_config if option_config.short?
 
         option_config
       end
 
+      # Handle configuration for a new action
+      #
+      # @param [String] name Name of the action
+      # @param [Function] block The block which configures this action
+      #
+      # @return [Cliqr::CLI::Config] The newly configured action
+      def handle_action(name, &block)
+        action_config = Config.build(&block)
+        action_config.name = name
+        add_action(action_config)
+      end
+
+      # Add a new action
+      #
+      # @return [Cliqr::CLI::Config] The newly added action
+      def add_action(action_config)
+        action_config.parent = self
+        action_config.root = root
+
+        validate_action_name(action_config)
+
+        @actions.push(action_config)
+        @action_index[action_config.name.to_sym] = action_config \
+          unless action_config.name.nil?
+
+        action_config
+      end
+
       # Make sure that the option's name is unique
       #
       # @param [Cliqr::CLI::OptionConfig] option_config Config for this particular option
@@ -174,6 +361,59 @@ module Cliqr
 
         option_config
       end
+
+      # Make sure that the action's name is unique
+      #
+      # @param [Cliqr::CLI::Config] action_config Config for this particular action
+      #
+      # @return [Cliqr::CLI::Config] Validated action's Config instance
+      def validate_action_name(action_config)
+        fail Cliqr::Error::DuplicateActions,
+             "multiple actions named \"#{action_config.name}\"" \
+             if action?(action_config.name)
+
+        action_config
+      end
+
+      # Add help command and option to this config
+      #
+      # @return [Cliqr::CLI::Config] Updated config
+      def add_help
+        return self unless help?
+        add_action(Cliqr::Util.build_help_action(self)) unless action?('help')
+        add_option(Cliqr::Util.build_help_option(self)) unless option?('help')
+      end
+
+      # Add version command and option to this config
+      #
+      # @return [Cliqr::CLI::Config] 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::CLI::Config] Updated config
+      def add_shell
+        return self unless shell?
+        add_action(Cliqr::Util.build_shell_action(self)) unless action?('shell')
+      end
+
+      # Get default setting for shell attribute
+      #
+      # @return [Symbol]
+      def shell_default
+        root? && actions? ? ENABLE_CONFIG : DISABLE_CONFIG
+      end
+
+      # Get the passed param value if current attribute is unset
+      #
+      # @return [Object]
+      def self.get_if_unset(attribute_value, default_value)
+        attribute_value == UNSET ? default_value : attribute_value
+      end
     end
 
     # Config attributes for a command's option
@@ -208,16 +448,32 @@ module Cliqr
       # @return [Symbol] Type of the option
       attr_accessor :type
       validates :type,
-                inclusion: [:any, :numeric, :boolean]
+                inclusion: [:any, NUMERIC_ARGUMENT_TYPE, BOOLEAN_ARGUMENT_TYPE]
+
+      # Operation to be applied to the option value after validation
+      #
+      # @return [Class<Cliqr::CLI::ArgumentOperator>]
+      attr_accessor :operator
+      validates :operator,
+                one_of: {
+                    extend: Cliqr::CLI::ArgumentOperator,
+                    type_of: Proc
+                }
+
+      # Default value for this option
+      #
+      # @return [Object]
+      attr_accessor :default
 
       # Set value for command option's attribute
       #
       # @param [Symbol] name Name of the attribute
-      #
       # @param [Object] value Value for the attribute
+      # @param [Proc] block A anonymous block to initialize the config value
       #
       # @return [Object] Value that was set for the attribute
-      def set_config(name, value)
+      def set_config(name, value, &block)
+        value = block if block_given?
         handle_option_config name, value
       end
 
@@ -227,16 +483,21 @@ module Cliqr
         @short = UNSET
         @description = UNSET
         @type = UNSET
+        @operator = UNSET
+        @default = UNSET
       end
 
       # Finalize option's config by adding default values for unset values
       #
       # @return [Cliqr::CLI::OptionConfig]
       def finalize
-        @name = nil if @name == UNSET
-        @short = nil if @short == UNSET
-        @description = nil if @description == UNSET
-        @type = :any if @type == UNSET
+        @name = Config.get_if_unset(@name, nil)
+        @short = Config.get_if_unset(@short, nil)
+        @description = Config.get_if_unset(@description, nil)
+        @type = Config.get_if_unset(@type, ANY_ARGUMENT_TYPE)
+        @operator = Util.ensure_instance(Config.get_if_unset(@operator,
+                                                             ArgumentOperator.for_type(@type)))
+        @default = Config.get_if_unset(@default, ARGUMENT_DEFAULTS[@type])
 
         self
       end
@@ -269,6 +530,13 @@ module Cliqr
         @type == :boolean
       end
 
+      # Check if a default value setting is defined
+      #
+      # @return [Boolean]
+      def default?
+        !@default.nil?
+      end
+
       private
 
       # Set value for config option without evaluating a block