cliqr 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9250bde8a2cd431432f1d68618d748b5e6ea378f
-  data.tar.gz: 1d2f297559d079b1b1592c5863f3b2ccb4782037
+  metadata.gz: 5305e3f607fd5cbf6d6c55840630671129ec96bf
+  data.tar.gz: 21995e4b7b23b3c3d29011eb9b42a614ca54d38a
 SHA512:
-  metadata.gz: aff0bc4667372517b12b61a84c4c4236179ec1aa37157be2676a71861daf6c639182cb11f06a698eb6b76cb1796f0c1b5c8142a4fde63f50b3d2f39ce9cec180
-  data.tar.gz: 5eee04fc1abd977ae5ff3156b02c4d694b33b30b9ec793dff92edd2d2c5f70605e15316aa67c18e8b1bd3cf04f9d88b304f7e4c8be9ab35bce1564288da8fb12
+  metadata.gz: b2e59b44f6b5656afbd8e75039fbf0cd46fff0421b1923fb8b3cf04f2972ad96359dbbef31f205190476123f80b5b686b3270db6f603329f6ab2194be6771e08
+  data.tar.gz: 3b0b7571dcbf6d460e4b61fbbfee83923e2c784c450311a00060ecd828ec17ba2a70820d4f8302ac9dbd27b2ba2189f2e713a96ba78fcc8bf66b98140ebf52b2

data/CHANGELOG.md

@@ -91,6 +91,101 @@ item in this nested table for further details.
 
 <!-- markdown-toc end -->
 
+2.0.0 / 2015-07-09
+==================
+
+Another big release!
+
+## Features
+
+### Event handling
+
+Added ability to invoke arbitiary events and define handlers to handle certain kind of events.
+
+Here is an example:
+``` ruby
+Cliqr.interface do
+  name 'my-command'
+  on :bar do |event, ch, num|
+    puts 'invoked event in base'
+    puts "option = #{opt}"
+    puts "ch = #{ch}; num = #{num}"
+  end
+
+  action :my_action do
+    on :bar do |event, ch, num|
+      puts 'invoked event in action'
+      puts "option = #{opt}"
+      puts "ch = #{ch}; num = #{num}"
+    end
+
+    handler do
+      invoke :bar, 'a', 10
+    end
+
+    option :opt
+  end
+end
+```
+Upon execution:
+``` bash
+$ my-command my_action --opt qwerty
+invoked event in action
+option = qwerty
+ch = a; num = 10
+invoked event in base
+option = qwerty
+ch = a; num = 10
+```
+
+Events can be chained as above example shows.
+
+#### Default events for shell
+
+When a shell starts a `shell_start` event is invoked. Upon exit, a `shell_exit` event is invoked.
+
+### Colors
+
+Enabled colors in command handlers and usage output. Just call a function with the name of the color you want. Colors can also be disabled.
+
+### Customizable banner and prompt for shell 
+
+The shell action now allows you to configure the banner displayed in the beginning and define a method to build the prompt.
+
+## Backward incompatible changes
+
+The shell action can only be used in the base command config.
+
+## Improvements
+
+### Partial templated
+
+Templates are reused to build help doc by incorporation of partial erb templating.
+
+### Improve default prompt
+
+Count is shown in the default prompt.
+
+### Screen capture in README
+
+A screen capture of the example is added to readme now.
+
+## Minor changes
+
+### Shorten the quickstart example
+
+### Re-organize code and move specs around
+
+### Multi OS testing suprted added to CI
+
+CI now runs all specs for Linux and OSX
+
+## Bugfixes
+
+### Fix examples to follow new breaking shell config change
+
+### Do not put allow arguments in shell config
+
 1.2.0 / 2015-06-18
 ==================
 

data/README.md

@@ -45,7 +45,7 @@ how to use `cliqr`.
 ## Quickstart
 
 To get things started quickly here is an example of a basic `cliqr`
-based CLI application (lets call this script `numbers`):
+based CLI application (lets call this script `greet`):
 
 ``` ruby
 #!/usr/bin/env ruby
@@ -53,90 +53,28 @@ based CLI application (lets call this script `numbers`):
 require 'cliqr'
 
 cli = Cliqr.interface do
-  name 'numbers'
-  description 'A simplistic example for quickly getting started with cliqr.'
+  name 'greet'
+  description 'A "hello world" app to demonstrate 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.'
+    puts "Hi #{name}" if name? # name is command's option defined below
+    puts "Please tell me your name" unless name?
   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)
 ```
 
-Now you can execute this script:
-
-``` bash
-$ ./numbers
-Nothing to do here. Please try the sort action.
-$ ./numbers  --name "Anshul Verma"
-Hi Anshul
-Nothing to do here. Please try the sort action.
-$ ./numbers sort -c 5
-4519
-5612
-6038
-6872
-8259
-$ ./numbers sort -c 5 --order descending
-8742
-7995
-6593
-2730
-806
-```
-
-A shell command is auto generated for you by `cliqr`. Here is how it works:
-
-``` bash
-$ ./numbers shell
-Starting shell for command "numbers"
-numbers > sort -c 5
-1259
-2031
-4864
-8355
-9824
-```
+Here is a screen capture of this script in action:
+![greet script demo]
+(https://raw.githubusercontent.com/anshulverma/cliqr/master/screenshots/greet.gif
+ "Binary tree example")
 
 ## Installation
 

data/examples/numbers

@@ -24,7 +24,6 @@ cli = Cliqr.interface do
 
   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
@@ -41,7 +40,7 @@ cli = Cliqr.interface do
 
     option :order do
       short 'o'
-      description 'Order of sort.'
+      description 'Order of sort (either :ascending or :descending).'
 
       # This is how you can make sure that the input is valid.
       operator do

data/examples/vagrant

@@ -23,10 +23,8 @@ EOS
 
   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'
@@ -57,7 +55,6 @@ EOS
 
   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. ' \

data/lib/cliqr.rb

@@ -1,11 +1,10 @@
 # encoding: utf-8
 
+require 'cliqr/interface'
 require 'cliqr/version'
 require 'cliqr/error'
-
-require 'cliqr/cli/config'
-require 'cliqr/cli/interface'
-require 'cliqr/cli/command'
+require 'cliqr/config/command'
+require 'cliqr/command/shell_prompt_builder'
 
 # Top level namespace for the Cliqr gem
 #
@@ -23,13 +22,13 @@ module Cliqr
     #     option
     #   end
     #
-    # @return [Cliqr::CLI::Interface]
+    # @return [Cliqr::Interface]
     #
     # @api public
     def interface(&block)
-      config = CLI::Config.build(&block)
+      config = Cliqr::Config::Command.build(&block)
       config.setup_defaults
-      CLI::Interface.build(config)
+      Cliqr::Interface.build(config)
     end
 
     # All cliqr commands should extend from this. Here is an example:
@@ -41,12 +40,12 @@ module Cliqr
     #     end
     #   end
     #
-    # @return [Cliqr::CLI::Command]
+    # @return [Cliqr::Command::BaseCommand]
     def command
-      CLI::Command
+      Command::BaseCommand
     end
 
-    # A argument operator must extend from [Cliqr::CLI::ArgumentOperator]
+    # A argument operator must extend from [Cliqr::Command::ArgumentOperator]
     #
     # @example
     #   class MyOperator < Cliqr.operator
@@ -57,7 +56,49 @@ module Cliqr
     #
     # @return [Cliar::CLI::ArgumentOperator]
     def operator
-      CLI::ArgumentOperator
+      Command::ArgumentOperator
+    end
+
+    # A custom shell prompt builder must extend from this
+    #
+    # @example
+    #   class MyCustomPrompt < Cliqr.shell_prompt
+    #     def build(context)
+    #       # build a prompt string
+    #     end
+    #   end
+    #
+    # @return [Cliqr::Command::ShellPromptBuilder]
+    def shell_prompt
+      Command::ShellPromptBuilder
+    end
+
+    # A custom shell banner builder must extend from this
+    #
+    # @example
+    #   class MyCustomBanner < Cliqr.shell_banner
+    #     def build(context)
+    #       # build a banner string
+    #     end
+    #   end
+    #
+    # @return [Cliqr::Command::ShellBannerBuilder]
+    def shell_banner
+      Command::ShellBannerBuilder
+    end
+
+    # A custom event handler must extend from this
+    #
+    # @example
+    #   class MyEventHandler < Cliqr.event_handler
+    #     def handle(context, event)
+    #       # handle event
+    #     end
+    #   end
+    #
+    # @return [Cliqr::Events::Handler]
+    def event_handler
+      Events::Handler
     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 CLI::NUMERIC_ARGUMENT_TYPE
+        when Config::NUMERIC_ARGUMENT_TYPE
           Integer(argument)
-        when CLI::BOOLEAN_ARGUMENT_TYPE
+        when Config::BOOLEAN_ARGUMENT_TYPE
           fail ArgumentError unless argument.class == TrueClass || argument.class == FalseClass
         end
         true

data/lib/cliqr/argument_validation/validator.rb

@@ -25,9 +25,9 @@ module Cliqr
       # @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.to_s)
+        config.options.each do |(name, option)|
+          validate_argument(args.option(name), option, errors) \
+            if args.options.key?(name.to_s)
         end
         fail(Cliqr::Error::IllegalArgumentError, "illegal argument error - #{errors}") \
           unless errors.empty?

data/lib/cliqr/{cli → command}/argument_operator.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 module Cliqr
-  module CLI
+  module Command
     # Operates on the value of a argument after it has been validated
     #
     # @api private
@@ -14,7 +14,7 @@ module Cliqr
       # @return [Cliqr::CLI::ArgumentOperator]
       def self.for_type(type)
         case type
-        when CLI::NUMERIC_ARGUMENT_TYPE
+        when Config::NUMERIC_ARGUMENT_TYPE
           NumericArgumentOperator.new
         else
           DEFAULT_ARGUMENT_OPERATOR

data/lib/cliqr/{cli → command}/argument_operator_context.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 module Cliqr
-  module CLI
+  module Command
     # Context in which a anonymous argument operator runs
     #
     # @api private

data/lib/cliqr/{cli/command.rb → command/base_command.rb}

@@ -1,11 +1,11 @@
 # encoding: utf-8
 
 module Cliqr
-  module CLI
+  module Command
     # Base class for all commands to extend from
     #
     # @api private
-    class Command
+    class BaseCommand
       # Execute the command
       #
       # @return [Integer] Exit status of the command execution

data/lib/cliqr/command/color.rb

@@ -0,0 +1,174 @@
+# encoding: utf-8
+
+module Cliqr
+  module Command
+    # Colors that can be used in a command to colorize strings
+    #
+    # @api private
+    module Color
+      # Create a new color instance
+      #
+      # @return [Cliqr::Command::Color]
+      def initialize(config = nil)
+        # check and disable colors if needed
+        check_color_setting(config) unless config.nil?
+      end
+
+      # Colorize a string with black color
+      #
+      # @return [String]
+      def black(str)
+        colorize(str, 30)
+      end
+
+      # Colorize a string with red color
+      #
+      # @return [String]
+      def red(str)
+        colorize(str, 31)
+      end
+
+      # Colorize a string with green color
+      #
+      # @return [String]
+      def green(str)
+        colorize(str, 32)
+      end
+
+      # Colorize a string with yellow color
+      #
+      # @return [String]
+      def yellow(str)
+        colorize(str, 33)
+      end
+
+      # Colorize a string with blue color
+      #
+      # @return [String]
+      def blue(str)
+        colorize(str, 34)
+      end
+
+      # Colorize a string with magenta color
+      #
+      # @return [String]
+      def magenta(str)
+        colorize(str, 35)
+      end
+
+      # Colorize a string with cyan color
+      #
+      # @return [String]
+      def cyan(str)
+        colorize(str, 36)
+      end
+
+      # Colorize a string with gray color
+      #
+      # @return [String]
+      def gray(str)
+        colorize(str, 37)
+      end
+
+      # Colorize a the background in black
+      #
+      # @return [String]
+      def bg_black(str)
+        colorize(str, 40)
+      end
+
+      # Colorize a the background in red
+      #
+      # @return [String]
+      def bg_red(str)
+        colorize(str, 41)
+      end
+
+      # Colorize a the background in green
+      #
+      # @return [String]
+      def bg_green(str)
+        colorize(str, 42)
+      end
+
+      # Colorize a the background in yellow
+      #
+      # @return [String]
+      def bg_yellow(str)
+        colorize(str, 43)
+      end
+
+      # Colorize a the background in blue
+      #
+      # @return [String]
+      def bg_blue(str)
+        colorize(str, 44)
+      end
+
+      # Colorize a the background in magenta
+      #
+      # @return [String]
+      def bg_magenta(str)
+        colorize(str, 45)
+      end
+
+      # Colorize a the background in cyan
+      #
+      # @return [String]
+      def bg_cyan(str)
+        colorize(str, 46)
+      end
+
+      # Colorize a the background in gray
+      #
+      # @return [String]
+      def bg_gray(str)
+        colorize(str, 47)
+      end
+
+      # Returns the bold representation
+      #
+      # @return [String]
+      def bold(str)
+        colorize(str, 1, 22)
+      end
+
+      # Reverses the color of a string and its background
+      #
+      # @return [String]
+      def reverse_color(str)
+        colorize(str, 7, 27)
+      end
+
+      # Disable colors
+      #
+      # @return [Cliqr::Command::Color]
+      def disable_color
+        instance_eval do
+          def colorize(str, *_args)
+            str
+          end
+        end
+      end
+
+      protected
+
+      # Check if color is disabled
+      #
+      # @return [Cliqr::Command::CommandContext]
+      def check_color_setting(config)
+        return self if config.root.color?
+        disable_color
+      end
+
+      private
+
+      # Wrap a string in a specific color code
+      #
+      # @return [String]
+      def colorize(str, color_code, end_tag = 0)
+        "\033[#{color_code}m#{str}\033[#{end_tag}m"
+      end
+    end
+  end
+end