cliqr 1.1.0 → 1.2.0

data/examples/numbers

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+# The simple sort script from root README
+
+require 'cliqr'
+
+cli = Cliqr.interface do
+  name 'numbers'
+  description 'A simplistic example for quickly getting started with cliqr.'
+  version '0.0.1' # optional; adds a version action to our simple command
+
+  # main command handler
+  handler do
+    puts "Hi #{name}" if name?
+    puts 'Nothing to do here. Please try the sort action.'
+  end
+
+  option :name do
+    description 'Your name.'
+    operator do
+      value.split(' ').first # only get the first name
+    end
+  end
+
+  action :sort do
+    description 'Sort a set of random numbers'
+    shell :disable
+
+    handler do
+      fail StandardError, 'count should be a non-zero positive number' unless count > 0
+      result = [].tap { |numbers| count.times { numbers << rand(9999) } }.sort
+      result = result.reverse if order? && order == :descending
+      puts result
+    end
+
+    option :count do
+      short 'c' # optional, but usually a good idea to have it
+      description 'Count of something.'
+      type :numeric # restricts values for this option to numbers
+    end
+
+    option :order do
+      short 'o'
+      description 'Order of sort.'
+
+      # This is how you can make sure that the input is valid.
+      operator do
+        fail StandardError, "Unknown order #{value}" unless [:ascending, :descending].include?(value.to_sym)
+        value.to_sym
+      end
+    end
+  end
+end
+
+cli.execute(ARGV)

data/examples/vagrant

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+
+# A fake vagrant command example.
+#
+# In this example you can find:
+# - A Command wih action and sub-actions
+# - Command handler returning non-zero exit code
+# - Command options and their types
+# - Overriding default option argument values
+# - Enable/Disable command arguments
+
+require 'cliqr'
+
+cli = Cliqr.interface do
+  name 'vagrant'
+  description <<-EOS
+Vagrant is a tool for building and distributing development environments.
+
+http://www.vagrantup.com
+EOS
+  version '1.7.2'
+  shell :disable
+
+  action :box do
+    description 'manages boxes: installation, removal, etc.'
+    shell :disable
+
+    action :add do
+      shell :disable
+      handler do
+        puts 'This command was not invoked properly. The help for this command is available below.'
+        forward 'vagrant box add help'
+        1 # non-zero exit code
+      end
+
+      option :clean do
+        short 'c'
+        description 'Clean any temporary download files'
+        type :boolean
+      end
+
+      option :force do
+        short 'f'
+        description 'Overwrite an existing box if it exists'
+        type :boolean
+      end
+
+      option :insecure do
+        description 'Do not validate SSL certificates'
+      end
+
+      option :cacert do
+        description 'CA certificate for SSL download'
+      end
+    end
+  end
+
+  action :up do
+    description 'starts and provisions the vagrant environment'
+    shell :disable
+    arguments :disable
+    handler do
+      puts 'A Vagrant environment or target machine is required to run this command. ' \
+           'Then there is also that fact that this is a fake demo :)'
+      1 # non-zero exit code
+    end
+
+    option :provision do
+      description 'Enable or disable provisioning'
+      type :boolean
+    end
+
+    option 'destroy-on-error' do
+      description 'Destroy machine if any fatal error happens'
+      type :boolean
+      default true
+    end
+
+    option :parallel do
+      description 'Enable or disable parallelism if provider supports it'
+      type :boolean
+    end
+
+    option :provider do
+      description 'Back the machine with a specific provider'
+    end
+  end
+end
+
+cli.execute(ARGV)

data/lib/cliqr.rb

@@ -16,7 +16,7 @@ module Cliqr
     #
     # @example
     #   Cliqr.interface do
-    #     basename 'my-command' # name of the command
+    #     name 'my-command' # name of the command
     #     description 'command description in a few words' # long description
     #     handler MyCommandHandler # command's handler class
     #
@@ -28,6 +28,7 @@ module Cliqr
     # @api public
     def interface(&block)
       config = CLI::Config.build(&block)
+      config.setup_defaults
       CLI::Interface.build(config)
     end
 
@@ -40,9 +41,23 @@ module Cliqr
     #     end
     #   end
     #
-    # @return [CLI::Command]
+    # @return [Cliqr::CLI::Command]
     def command
       CLI::Command
     end
+
+    # A argument operator must extend from [Cliqr::CLI::ArgumentOperator]
+    #
+    # @example
+    #   class MyOperator < Cliqr.operator
+    #     def operate(value)
+    #       # return the operated value
+    #     end
+    #   end
+    #
+    # @return [Cliar::CLI::ArgumentOperator]
+    def operator
+      CLI::ArgumentOperator
+    end
   end
 end

data/lib/cliqr/argument_validation/argument_type_validator.rb

@@ -17,9 +17,9 @@ module Cliqr
       # Check if a type of a argument matches a required type
       def type_of?(argument, required_type)
         case required_type
-        when :numeric
+        when CLI::NUMERIC_ARGUMENT_TYPE
           Integer(argument)
-        when :boolean
+        when CLI::BOOLEAN_ARGUMENT_TYPE
           fail ArgumentError unless argument.class == TrueClass || argument.class == FalseClass
         end
         true

data/lib/cliqr/argument_validation/validator.rb

@@ -27,7 +27,7 @@ module Cliqr
         errors = ValidationErrors.new
         config.options.each do |option|
           validate_argument(args.option(option.name), option, errors) \
-            if args.options.key?(option.name)
+            if args.options.key?(option.name.to_s)
         end
         fail(Cliqr::Error::IllegalArgumentError, "illegal argument error - #{errors}") \
           unless errors.empty?

data/lib/cliqr/cli/argument_operator.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+
+module Cliqr
+  module CLI
+    # Operates on the value of a argument after it has been validated
+    #
+    # @api private
+    class ArgumentOperator
+      # Default pass through argument operator
+      DEFAULT_ARGUMENT_OPERATOR = ArgumentOperator.new
+
+      # Get a new ArgumentOperator for a argument type
+      #
+      # @return [Cliqr::CLI::ArgumentOperator]
+      def self.for_type(type)
+        case type
+        when CLI::NUMERIC_ARGUMENT_TYPE
+          NumericArgumentOperator.new
+        else
+          DEFAULT_ARGUMENT_OPERATOR
+        end
+      end
+
+      # Return the same value back without any change
+      #
+      # @return [String]
+      def operate(value)
+        value
+      end
+    end
+
+    # Handle numerical arguments
+    #
+    # @api private
+    class NumericArgumentOperator < ArgumentOperator
+      # Convert the argument to a integer value
+      #
+      # @return [Integer]
+      def operate(value)
+        value.to_i
+      end
+    end
+  end
+end

data/lib/cliqr/cli/argument_operator_context.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+module Cliqr
+  module CLI
+    # Context in which a anonymous argument operator runs
+    #
+    # @api private
+    class ArgumentOperatorContext
+      # Value to operator on
+      #
+      # @return [Object]
+      attr_accessor :value
+
+      # Create a argument operator context for a value
+      def initialize(value)
+        @value = value
+      end
+    end
+  end
+end

data/lib/cliqr/cli/command.rb

@@ -9,7 +9,7 @@ module Cliqr
       # Execute the command
       #
       # @return [Integer] Exit status of the command execution
-      def execute
+      def execute(_context)
         0
       end
     end

data/lib/cliqr/cli/command_context.rb

@@ -1,5 +1,7 @@
 # encoding: utf-8
 
+require 'cliqr/cli/argument_operator_context'
+
 module Cliqr
   # Definition and builder for command context
   module CLI
@@ -17,21 +19,34 @@ module Cliqr
       # @return [Array<String>] List of arguments
       attr_accessor :arguments
 
+      # Name of the current action
+      #
+      # @return [String]
+      attr_accessor :action_name
+
       # Build a instance of command context based on the parsed set of arguments
       #
+      # @param [Cliqr::CLI::Config] config The configuration settings for command's action config
       # @param [Cliqr::Parser::ParsedInput] parsed_input Parsed input object
+      # @param [Hash] options Options for command execution
+      # @param [Proc] executor Executes forwarded commands
       #
       # @return [Cliqr::CLI::CommandContext]
-      def self.build(parsed_input)
-        CommandContextBuilder.new(parsed_input).build
+      def self.build(config, parsed_input, options, &executor)
+        CommandContextBuilder.new(config, parsed_input, options, executor).build
       end
 
       # Initialize the command context (called by the CommandContextBuilder)
       #
       # @return [Cliqr::CLI::CommandContext]
-      def initialize(command, options, arguments)
-        @command = command
+      def initialize(config, options, arguments, environment, executor)
+        @config = config
+        @command = config.command
         @arguments = arguments
+        @action_name = config.name
+        @context = self
+        @environment = environment
+        @executor = executor
 
         # make option map from array
         @options = Hash[*options.collect { |option| [option.name, option] }.flatten]
@@ -50,7 +65,8 @@ module Cliqr
       #
       # @return [Cliqr::CLI::CommandOption] Instance of CommandOption for option
       def option(name)
-        @options[name]
+        return @options[name] if option?(name)
+        default(name)
       end
 
       # Check if a option with a specified name has been passed
@@ -62,7 +78,46 @@ module Cliqr
         @options.key?(name)
       end
 
-      private :initialize
+      # Check whether the current context is based off of a sub-action
+      #
+      # @return [Boolean] <tt>true</tt> if this context is based off a sub-action
+      def action?
+        @config.parent?
+      end
+
+      # Forward a command to the executor
+      #
+      # @return [Integer] Exit code
+      def forward(args, options = {})
+        @executor.call(args, options)
+      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)
+        option_name = name.to_s.chomp('?')
+        existence_check = name.to_s.end_with?('?')
+        existence_check ? option?(option_name) : option(option_name).value \
+          if @config.option?(option_name)
+      end
+
+      # Get default value for a option
+      #
+      # @return [Object]
+      def default(name)
+        option_config = @config.option(name)
+        CommandOption.new([name, option_config.default], option_config)
+      end
+
+      # Check if running in a bash environment
+      #
+      # @return [Boolean]
+      def bash?
+        @environment == :bash
+      end
+
+      private :initialize, :default
     end
 
     private
@@ -73,20 +128,32 @@ module Cliqr
     class CommandContextBuilder
       # Initialize builder for CommandContext
       #
+      # @param [Cliqr::CLI::Config] config The configuration settings for command's action config
       # @param [Cliqr::Parser::ParsedInput] parsed_input Parsed and validated command line arguments
+      # @param [Hash] options Options for command execution
+      # @param [Proc] executor Executes forwarded commands
       #
       # @return [Cliqr::CLI::CommandContextBuilder]
-      def initialize(parsed_input)
+      def initialize(config, parsed_input, options, executor)
+        @config = config
         @parsed_input = parsed_input
+        @options = options
+        @executor = executor
       end
 
       # Build a new instance of CommandContext
       #
       # @return [Cliqr::CLI::CommandContext] A newly created CommandContext instance
       def build
-        CommandContext.new @parsed_input.command,
-                           @parsed_input.options.map { |option| CommandOption.new(option) },
-                           @parsed_input.arguments
+        option_contexts = @parsed_input.options.map do |option|
+          CommandOption.new(option, @config.option(option.first))
+        end
+
+        CommandContext.new @config,
+                           option_contexts,
+                           @parsed_input.arguments,
+                           @options[:environment],
+                           @executor
       end
     end
 
@@ -107,12 +174,26 @@ module Cliqr
       # Create a new command line option instance
       #
       # @param [Array] option Parsed arguments for creating a command line option
+      # @param [Cliqr::CLI::OptionConfig] option_config Option's config settings
       #
       # @return [Cliqr::CLI::CommandContext] A new CommandOption object
-      def initialize(option)
-        @value = option.pop
+      def initialize(option, option_config)
+        @value = run_value_operator(option.pop, option_config.operator)
         @name = option.pop
       end
+
+      private
+
+      # Run the operator for a named attribute for a value
+      #
+      # @return [Nothing]
+      def run_value_operator(value, operator)
+        if operator.is_a?(Proc)
+          ArgumentOperatorContext.new(value).instance_eval(&operator)
+        else
+          operator.operate(value)
+        end
+      end
     end
   end
 end