cliqr 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 21be1b361f2ce33096983d813f3a9185018e5ffd
-  data.tar.gz: f6abf3c9cdeddeb784d690b584505f23f350828f
+  metadata.gz: dbf6874d54c340fea81a85d5d9c5d495eaf4bf70
+  data.tar.gz: c3a763238d2cfb47d3cf479d7922a9fa43357656
 SHA512:
-  metadata.gz: b0dfd50fbfeb23536cd14839f249cdc5f857a4562524c0935eb7788750e28c4cb1ec98c105384b77d2fa34ae8de8ec1e3752d39f45350acc9ac195a3d3f7a972
-  data.tar.gz: 7e43a504e6548df5a6525832498715fd96ef291669af4f0b3d5a252bb53a5ffd8d68bfcd35c5c278605345727368d623f48dec4487f9589656313bb5c7be03a8
+  metadata.gz: db2d7b59f422dd286fc244b6ed263ddbef70f9a088b3c95018fda4113daf3525ba53d96b4e6d0d6b970ba1fe52bf4772be34b2acdc60131c08aa3a242a5ddc2b
+  data.tar.gz: e470554fbb6649e3685173b78bd6559f5d104b6215ef8fd7cdc4265679cf1df2d7a29973c46a0ef009cf3278f3e84ea6b82fe04820989985d9af8bda512655b5

data/CHANGELOG.md

@@ -5,6 +5,16 @@ item in this nested table for further details.
 <!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc/generate-toc again -->
 **Table of Contents**
 
+- [1.0.0 / 2015-06-04](#100--2015-06-04)
+    - [Features](#features)
+        - [Support for option types](#support-for-option-types)
+    - [Improvements](#improvements)
+        - [Generic CLI config validator implementation](#generic-cli-config-validator-implementation)
+    - [Minor Improvements](#minor-improvements)
+        - [Reduce the number of error types](#reduce-the-number-of-error-types)
+        - [Maintain example in readme](#maintain-example-in-readme)
+    - [Bug-fixes](#bug-fixes)
+        - [It should be optional to include options in a command](#it-should-be-optional-to-include-options-in-a-command)
 - [0.1.0 / 2015-05-29](#010--2015-05-29)
     - [Features](#features)
         - [First pass at building ability to parse command line arguments](#first-pass-at-building-ability-to-parse-command-line-arguments)
@@ -51,6 +61,51 @@ item in this nested table for further details.
 
 <!-- markdown-toc end -->
 
+1.0.0 / 2015-06-04
+==================
+
+Aaaaand here it is ladies and gentlemen! A major release version of
+`cliqr`
+
+The main feature that was added in this release is support for option
+types. Namely: `:boolean` and `:numeric`. Along with this, a major
+refactoring was done for the config validator framework to make it more
+generic and easy to manage in the long run.
+
+## Features
+
+### Support for option types
+
+We can now restrict option values to either a number or define a option
+which is either present or not. This also requires a new and improved
+option parser and validator.
+
+## Improvements
+
+### Generic CLI config validator implementation
+
+The idea for this came from [https://github.com/lotus/validations/]. By
+doing this we can make sure that it will be fairly easy to maintain the
+validation logic and extend it in future.
+
+## Minor Improvements
+
+### Reduce the number of error types
+
+This was made possible by using a generic validator. So, along with all
+the custom validation code we were able to get rid of the custom error
+types.
+
+### Maintain example in readme
+
+The example in the readme file was updated to reflect the latest changes.
+
+## Bug-fixes
+
+### It should be optional to include options in a command
+
+We will be adding a restriction to allow users to mark certain options
+as required in future versions.
 
 0.1.0 / 2015-05-29
 ==================

data/README.md

@@ -49,7 +49,12 @@ require 'cliqr'
 class MyCommandHandler < Cliqr.command
   def execute(context)
     puts 'executing my awesome command'
-    puts "value for option 'test' is '#{context.option('test').value}'"
+    puts "value for option 'an-option' is '#{context.option('an-option').value}'"
+    puts "value for option 'count' is '#{context.option('count').value}'"
+    puts "value for option 'single' is '#{context.option('single').value}'"
+    puts "value for option 'test-1' is '#{context.option('test-1').value}'"
+    puts "has count argument" if context.option?('count')
+    puts "does not have test argument" unless context.option?('test-2')
   end
 end
 
@@ -62,25 +67,49 @@ cli = Cliqr.interface do
     short 'a'
     description 'this is a option'
   end
-  
-  option 'test'
+
+  option 'count' do
+    short 'c'
+    description 'count of something'
+    type :numeric
+  end
+
+  option 'single' do
+    short 's'
+    description 'a boolean option'
+    type :boolean
+  end
+
+  option 'test-1'
+  option 'test-2'
 end
 
 puts cli.usage
-#> my-command -- this is an awesome command...try it out
-#>
-#> USAGE:
-#>     my-command
-#>
-#> Available options:
-#>
-#>     --an-option, -a  :  this is a option
-#>
-#>     --test
-
-cli.execute %w(--test some-value)
-#> executing my awesome command
-#> value for option 'test' is 'some-value'
+# my-command -- this is an awesome command...try it out
+#
+# USAGE:
+#     my-command [options]
+#
+# Available options:
+#
+#     --an-option, -a  :  this is a option
+#
+#     --count, -c  :  <numeric> count of something
+#
+#     --[no-]single, -s  :  <boolean> a boolean option
+#
+#     --test-1
+#
+#     --test-2
+
+cli.execute %w(--an-option qwerty -c 86 --no-single --test-1 some-value)
+# executing my awesome command
+# value for option 'an-option' is 'qwerty'
+# value for option 'count' is '86'
+# value for option 'single' is 'false'
+# value for option 'test-1' is 'some-value'
+# has count argument
+# does not have test argument
 ```
 
 ## Installation

data/lib/cliqr/argument_validation/argument_type_validator.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+module Cliqr
+  module ArgumentValidation
+    # Validates type of a argument
+    class ArgumentTypeValidator
+      # Run the validation on a argument based on the option's configuration
+      #
+      # @return [Cliqr:ValidationErrors]
+      def validate(argument, option, errors)
+        errors.add("only values of type '#{option.type}' allowed for option '#{option.name}'") \
+          unless type_of?(argument, option.type)
+        errors
+      end
+
+      private
+
+      # Check if a type of a argument matches a required type
+      def type_of?(argument, required_type)
+        case required_type
+        when :numeric
+          Integer(argument)
+        when :boolean
+          fail ArgumentError unless argument.class == TrueClass || argument.class == FalseClass
+        end
+        true
+      rescue ArgumentError
+        false
+      end
+    end
+  end
+end

data/lib/cliqr/argument_validation/option_validator.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+module Cliqr
+  module ArgumentValidation
+    # Runs all validators configured for an option
+    class OptionValidator
+      # Create a new option validator
+      def initialize
+        @validators = Set.new []
+      end
+
+      # Add a validator for this option
+      #
+      # @return [Set] All validators configured so far
+      def add(validator)
+        @validators.add(validator)
+      end
+
+      # Run all the validators for a option
+      #
+      # @return [Cliqr::ValidationErrors]
+      def validate(argument, option, errors)
+        @validators.each { |validator| validator.validate(argument, option, errors) }
+        errors
+      end
+    end
+  end
+end

data/lib/cliqr/argument_validation/validator.rb

@@ -0,0 +1,67 @@
+# encoding: utf-8
+
+require 'cliqr/error'
+require 'cliqr/argument_validation/option_validator'
+require 'cliqr/argument_validation/argument_type_validator'
+
+module Cliqr
+  # Validate command arguments based on pre-configured settings
+  #
+  # @api private
+  module ArgumentValidation
+    # Utiity class to validate input to a command
+    #
+    # @api private
+    class Validator
+      # Initialize a new Validator instance
+      def initialize
+        @option_validators = {}
+      end
+
+      # Validate parsed command line arguments
+      #
+      # @param [Cliqr::Parser::ParsedInput] args Parsed input instance
+      #
+      # @return [Cliqr::Parser::ParsedInput] Validated parsed input
+      def validate(args, config)
+        errors = ValidationErrors.new
+        config.options.each do |option|
+          validate_argument(args.option(option.name), option, errors) \
+            if args.options.key?(option.name)
+        end
+        fail(Cliqr::Error::IllegalArgumentError, "illegal argument error - #{errors}") \
+          unless errors.empty?
+        args
+      end
+
+      private
+
+      # Validate a argument for an option and return errors
+      #
+      # @return [Cliqr::ValidationErrors]
+      def validate_argument(argument, option, errors)
+        option_validator = get_option_validator(option)
+        option_validator.validate(argument, option, errors)
+        errors
+      end
+
+      # Get or create validator for a option
+      #
+      # @return [Hash] A hash of all option mapped to its validator
+      def get_option_validator(option)
+        @option_validators[option] = build_option_validator(option) \
+          unless @option_validators.key?(option)
+        @option_validators[option]
+      end
+
+      # Create a new option validator
+      #
+      # @return [Cliqr::ArgumentValidation::OptionValidator]
+      def build_option_validator(option)
+        option_validator = OptionValidator.new
+        option_validator.add(ArgumentTypeValidator.new) if option.type?
+        option_validator
+      end
+    end
+  end
+end

data/lib/cliqr/cli/command_context.rb

@@ -14,11 +14,11 @@ module Cliqr
 
       # Build a instance of command context based on the parsed set of arguments
       #
-      # @param [Hash] parsed_args A hash of parsed command line arguments
+      # @param [Cliqr::Parser::ParsedInput] parsed_input Parsed input object
       #
       # @return [Cliqr::CLI::CommandContext]
-      def self.build(parsed_args)
-        CommandContextBuilder.new(parsed_args).build
+      def self.build(parsed_input)
+        CommandContextBuilder.new(parsed_input).build
       end
 
       # Initialize the command context (called by the CommandContextBuilder)
@@ -46,6 +46,15 @@ module Cliqr
         @options[name]
       end
 
+      # Check if a option with a specified name has been passed
+      #
+      # @param [String] name Name of the option
+      #
+      # @return [Boolean] <tt>true</tt> if the option has a argument value
+      def option?(name)
+        @options.key?(name)
+      end
+
       private :initialize
     end
 
@@ -57,19 +66,19 @@ module Cliqr
     class CommandContextBuilder
       # Initialize builder for CommandContext
       #
-      # @param [Hash] parsed_args Parsed and validated command line arguments
+      # @param [Cliqr::Parser::ParsedInput] parsed_input Parsed and validated command line arguments
       #
       # @return [Cliqr::CLI::CommandContextBuilder]
-      def initialize(parsed_args)
-        @parsed_args = parsed_args
+      def initialize(parsed_input)
+        @parsed_input = parsed_input
       end
 
       # Build a new instance of CommandContext
       #
       # @return [Cliqr::CLI::CommandContext] A newly created CommandContext instance
       def build
-        CommandContext.new @parsed_args[:command],
-                           @parsed_args[:options].map { |args| CommandOption.new(args) }
+        CommandContext.new @parsed_input.command,
+                           @parsed_input.options.map { |option| CommandOption.new(option) }
       end
     end
 
@@ -89,12 +98,12 @@ module Cliqr
 
       # Create a new command line option instance
       #
-      # @param [Hash] args Arguments for creating a command line option
+      # @param [Array] option Parsed arguments for creating a command line option
       #
       # @return [Cliqr::CLI::CommandContext] A new CommandOption object
-      def initialize(args)
-        @name = args[:name]
-        @value = args[:value]
+      def initialize(option)
+        @value = option.pop
+        @name = option.pop
       end
     end
   end

data/lib/cliqr/cli/config.rb

@@ -1,6 +1,8 @@
 # encoding: utf-8
 
 require 'cliqr/dsl'
+require 'cliqr/validation/verifiable'
+require 'cliqr/cli/command'
 
 module Cliqr
   # A extension for CLI module to group all config classes
@@ -13,11 +15,14 @@ module Cliqr
     # @api private
     class Config
       extend Cliqr::DSL
+      include Cliqr::Validation
 
       # Base name of the command
       #
       # @return [String]
       attr_accessor :basename
+      validates :basename,
+                non_empty_format: /^[a-zA-Z0-9_\-]+$/
 
       # Description for the base command
       #
@@ -26,13 +31,17 @@ module Cliqr
 
       # Command handler for the base command
       #
-      # @return [Class]
+      # @return [Class<Cliqr::CLI::Command>]
       attr_accessor :handler
+      validates :handler,
+                extend: Cliqr::CLI::Command
 
       # Array of options applied to the base command
       #
       # @return [Array<OptionConfig>]
       attr_accessor :options
+      validates :options,
+                collection: true
 
       # New config instance with all attributes set as UNSET
       def initialize
@@ -123,7 +132,7 @@ module Cliqr
         option_config = OptionConfig.build(&block)
         option_config.name = name
 
-        OptionConfigValidator.validate(option_config, self)
+        validate_option_name(option_config)
 
         @options.push option_config
 
@@ -132,6 +141,23 @@ module Cliqr
 
         option_config
       end
+
+      # Make sure that the option's name is unique
+      #
+      # @param [Cliqr::CLI::OptionConfig] option_config Config for this particular option
+      #
+      # @return [Cliqr::CLI::OptionConfig] Validated OptionConfig instance
+      def validate_option_name(option_config)
+        fail Cliqr::Error::DuplicateOptions,
+             "multiple options with long name \"#{option_config.name}\"" \
+             if option?(option_config.name)
+
+        fail Cliqr::Error::DuplicateOptions,
+             "multiple options with short name \"#{option_config.short}\"" \
+              if option?(option_config.short)
+
+        option_config
+      end
     end
 
     # Config attributes for a command's option
@@ -139,22 +165,35 @@ module Cliqr
     # @api private
     class OptionConfig
       extend Cliqr::DSL
+      include Cliqr::Validation
 
       # Long option name
       #
       # @return [String]
       attr_accessor :name
+      validates :name,
+                non_empty: true,
+                format: /^[a-zA-Z0-9_\-]*$/
 
       # Optional short name for the option
       #
       # @return [String]
       attr_accessor :short
+      validates :short,
+                non_empty_nil_ok_format: /^[a-z0-9A-Z]$/
 
       # A description string for the option
       #
       # @return [String]
       attr_accessor :description
 
+      # Optional field that restricts values of this option to a certain type
+      #
+      # @return [Symbol] Type of the option
+      attr_accessor :type
+      validates :type,
+                inclusion: [:any, :numeric, :boolean]
+
       # Set value for command option's attribute
       #
       # @param [Symbol] name Name of the attribute
@@ -171,6 +210,7 @@ module Cliqr
         @name = UNSET
         @short = UNSET
         @description = UNSET
+        @type = UNSET
       end
 
       # Finalize option's config by adding default values for unset values
@@ -180,17 +220,11 @@ module Cliqr
         @name = nil if @name == UNSET
         @short = nil if @short == UNSET
         @description = nil if @description == UNSET
+        @type = :any if @type == UNSET
 
         self
       end
 
-      # Check if a option's name is defined
-      #
-      # @return [Boolean] <tt>true</tt> if options' name is not null neither empty
-      def name?
-        !(@name.nil? || @name.empty?)
-      end
-
       # Check if a option's short name is defined
       #
       # @return [Boolean] <tt>true</tt> if options' short name is not null neither empty
@@ -205,6 +239,20 @@ module Cliqr
         !(@description.nil? || @description.empty?)
       end
 
+      # Check if a option's type is defined
+      #
+      # @return [Boolean] <tt>true</tt> if options' type is not nil and not equal to <tt>:any</tt>
+      def type?
+        !@type.nil? && @type != :any
+      end
+
+      # Check if a option is of boolean type
+      #
+      # @return [Boolean] <tt>true</tt> is the option is of type <tt>:boolean</tt>
+      def boolean?
+        @type == :boolean
+      end
+
       private
 
       # Set value for config option without evaluating a block