cliqr 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 779fd42a32e0ec2a3d11d5db83bc65c66926d56b
-  data.tar.gz: a2c085fa4815bdcd88d04d1c52e6d7e1e2e4e4d2
+  metadata.gz: 9250bde8a2cd431432f1d68618d748b5e6ea378f
+  data.tar.gz: 1d2f297559d079b1b1592c5863f3b2ccb4782037
 SHA512:
-  metadata.gz: f91257c83d83705c218151e96b5c0e68f183ab714df0b661d65287d819ef83b0099c152780e46a25c1aab151a4cb21439252c787f1a6ae99bab3d7f6b4fb68ac
-  data.tar.gz: 609e715827bfe3cb93fb6dd9271856c0a9c7c256aa7ba89d070aa0906181452b5a3b34020dd3d4850b26d75483721931f1339fedb9f230f16dd60e841bf3394c
+  metadata.gz: aff0bc4667372517b12b61a84c4c4236179ec1aa37157be2676a71861daf6c639182cb11f06a698eb6b76cb1796f0c1b5c8142a4fde63f50b3d2f39ce9cec180
+  data.tar.gz: 5eee04fc1abd977ae5ff3156b02c4d694b33b30b9ec793dff92edd2d2c5f70605e15316aa67c18e8b1bd3cf04f9d88b304f7e4c8be9ab35bce1564288da8fb12

data/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.2.0 / 2015-06-18](#120--2015-06-18)
+    - [Features](#features)
+        - [Nested actions](#nested-actions)
+        - [Ability to operate on arguments](#ability-to-operate-on-arguments)
+        - [Anonymous Proc for command handling and argument operation](#anonymous-proc-for-command-handling-and-argument-operation)
+        - [Default value for options](#default-value-for-options)
+        - [Default command actions](#default-command-actions)
+            - [Help](#help)
+            - [Version](#version)
+            - [Shell](#shell)
+        - [Forward command from one handler to another](#forward-command-from-one-handler-to-another)
+    - [Improvements](#improvements)
+        - [Use name instead of basename](#use-name-instead-of-basename)
+        - [Reorganize tests](#reorganize-tests)
+        - [Can get value in operator by calling `value`](#can-get-value-in-operator-by-calling-value)
+        - [Run anonymous command handler in the the context of `CommandContext`](#run-anonymous-command-handler-in-the-the-context-of-commandcontext)
+        - [Call `help` action by default](#call-help-action-by-default)
+        - [Add Examples for using `Cliqr`](#add-examples-for-using-cliqr)
+        - [Update `README` to make it more relevant](#update-readme-to-make-it-more-relevant)
+    - [Bug-fixes](#bug-fixes)
+        - [Fix option parsing for option with symbolic name](#fix-option-parsing-for-option-with-symbolic-name)
+        - [Handle errors gracefully](#handle-errors-gracefully)
+        - [Include template in gem](#include-template-in-gem)
+        - [Fix shell in shell issue](#fix-shell-in-shell-issue)
 - [1.1.0 / 2015-06-05](#110--2015-06-05)
     - [Features](#features)
         - [Support for arbitrary arguments in a command](#support-for-arbitrary-arguments-in-a-command)
@@ -67,6 +91,109 @@ item in this nested table for further details.
 
 <!-- markdown-toc end -->
 
+1.2.0 / 2015-06-18
+==================
+
+This is a pretty loaded release in terms of features, improvements and
+bug-fixes. Here is a detailed list.
+
+## Features
+
+### Nested actions
+
+Every command is a action and in this release, we add support for
+building nested command structure.
+
+For example:
+
+``` bash
+$ vagrant up --provision
+```
+
+This command has:
+
+- Base-command: vagrant
+  - Sub action: up
+    - Option: provision
+
+### Ability to operate on arguments
+
+You can now specify a operator that can pre-process the option arguments
+and, if needed, do validation as well.
+
+### Anonymous Proc for command handling and argument operation
+
+No need to define a separate class to handle a command or operate on
+arguments.
+
+### Default value for options
+
+Options can now have a default value. In some cases this is derived from
+option type attribute.
+
+### Default command actions
+
+Several default actions were added to a command.
+
+#### Help
+
+Help is added by default to every action. This includes a help action
+and option.
+
+#### Version
+
+If specified, a version action and boolean option is added to the action.
+
+#### Shell
+
+Shell is enabled by default if there are any sub-actions for a command.
+
+### Forward command from one handler to another
+
+A new method `forward` can be called with arguments that are parsed and
+executed again.
+
+## Improvements
+
+### Use name instead of basename
+
+The only reason for this was to make things simple and consistent.
+
+### Reorganize tests
+
+Divide tests by functionality. In some cases group them together.
+
+### Can get value in operator by calling `value`
+
+### Run anonymous command handler in the the context of `CommandContext`
+
+### Call `help` action by default
+
+If you call a command without specifying any arguments, its help action
+will be invoked (assuming it is enabled).
+
+### Add Examples for using `Cliqr`
+
+Examples for some popular commands like `vagrant` and `hbase` along with
+some custom commands were added.
+
+### Update `README` to make it more relevant
+
+## Bug-fixes
+
+### Fix option parsing for option with symbolic name
+
+### Handle errors gracefully
+
+Errors do not kill the running script anymore and they do not show stack
+trace.
+
+### Include template in gem
+
+### Fix shell in shell issue
+
+It should be not allowed to run a shell within another shell.
+
 1.1.0 / 2015-06-05
 ==================
 
@@ -77,7 +204,7 @@ for arbitrary arguments.
 
 ### Support for arbitrary arguments in a command
 
-For the first time you can invoke a command with a non-option arguments.
+For the first time you can invoke a command with non-option arguments.
 
 ## Minor Improvements
 

data/README.md

@@ -1,12 +1,10 @@
-# cliqr
+# cliqr [![Version](http://img.shields.io/gem/v/cliqr.svg?style=flat-square)](https://rubygems.org/gems/cliqr)
 
 [![Build](http://img.shields.io/travis-ci/anshulverma/cliqr.svg?style=flat-square)](https://travis-ci.org/anshulverma/cliqr)
 [![Coverage](http://img.shields.io/codeclimate/coverage/github/anshulverma/cliqr.svg?style=flat-square)](https://codeclimate.com/github/anshulverma/cliqr)
 [![Quality](http://img.shields.io/codeclimate/github/anshulverma/cliqr.svg?style=flat-square)](https://codeclimate.com/github/anshulverma/cliqr)
 [![Dependencies](http://img.shields.io/gemnasium/anshulverma/cliqr.svg?style=flat-square)](https://gemnasium.com/anshulverma/cliqr)
-[![Inline docs](http://inch-ci.org/github/anshulverma/cliqr.svg)](http://inch-ci.org/github/anshulverma/cliqr)
-
-[![Version](http://img.shields.io/gem/v/cliqr.svg?style=flat-square)](https://rubygems.org/gems/cliqr)
+[![Inline docs](http://inch-ci.org/github/anshulverma/cliqr.svg?style=flat-square)](http://inch-ci.org/github/anshulverma/cliqr)
 [![Downloads](http://img.shields.io/gem/dt/cliqr.svg?style=flat-square)](https://rubygems.org/gems/cliqr)
 
 <!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc/generate-toc again -->
@@ -15,7 +13,7 @@
 - [cliqr](#cliqr)
     - [Summary](#summary)
     - [Examples](#examples)
-        - [Simple CLI app example](#simple-cli-app-example)
+    - [Quickstart](#quickstart)
     - [Installation](#installation)
     - [Building](#building)
     - [Contributing](#contributing)
@@ -25,91 +23,119 @@
 
 ## Summary
 
-`cliqr` is a lightweight framework and DSL to easily build a command
-line application. Features include:
+`cliqr` is a lightweight yet feature rich framework which can be used to
+build a powerful command line application. It provides a easy to use DSL
+to define the interface of a application. Some of the features included:
 
-- Command Routing
-- DSL for simple interface definition
-- Usage info generation
-- Error handling
+- Quick and easy method for defining CLI interface
+- Command usage generation based on interface definition
+- Argument parsing
+- Argument validation
+- Nested command actions
+- Multiple command handler based on arguments
+- Command routing to appropriate handler
+- Inbuilt shell extension for your command
 
 ## Examples
 
 The DSL provides several helper methods to build interfaces of different
-styles. Here are some examples.
+styles. Please refer to the examples folder to find some useful tips on
+how to use `cliqr`.
 
-### Simple CLI app example
+## Quickstart
 
-Here is a simple hello-world example for using Cliqr.
+To get things started quickly here is an example of a basic `cliqr`
+based CLI application (lets call this script `numbers`):
 
 ``` ruby
-require 'cliqr'
+#!/usr/bin/env ruby
 
-# a custom command handler
-class MyCommandHandler < Cliqr.command
-  def execute(context)
-    puts 'executing my awesome command'
-    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-2' argument" unless context.option?('test-2')
-  end
-end
+require 'cliqr'
 
 cli = Cliqr.interface do
-  basename 'my-command'
-  description 'this is an awesome command...try it out'
-  handler MyCommandHandler
-
-  option 'an-option' do
-    short 'a'
-    description 'this is a option'
+  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 'count' do
-    short 'c'
-    description 'count of something'
-    type :numeric
+  option :name do
+    description 'Your name.'
+    operator do
+      value.split(' ').first # only get the first name
+    end
   end
 
-  option 'single' do
-    short 's'
-    description 'a boolean option'
-    type :boolean
+  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
-
-  option 'test-1'
-  option 'test-2'
 end
 
-puts cli.usage
-# my-command -- this is an awesome command...try it out
-#
-# USAGE:
-#     my-command [options] [arguments]
-#
-# 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-2' argument
+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
 ```
 
 ## Installation

data/examples/README.md

@@ -0,0 +1,12 @@
+# examples
+
+Here are some usage examples for `cliqr`. More can be added if needed.
+
+Please go through the comment at the top of each script. It pretty much
+explains what the script is.
+
+To fire off the script and start using it (for `vagrant` example):
+
+``` bash
+$ ./vagrant help
+```

data/examples/hbase

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+
+# A fake hbase shell example
+#
+# This script mainly features how to build a custom shell
+
+require 'cliqr'
+
+cli = Cliqr.interface do
+  name 'hbase'
+  version '0.98.13RC2'
+  arguments :disable
+
+  # from hbase git repository https://github.com/apache/hbase
+  description <<-EOS
+Apache HBase is an open-source, distributed, versioned, column-oriented
+store modeled after Google' Bigtable: A Distributed Storage System for
+Structured Data by Chang et al. Just as Bigtable leverages the distributed
+data storage provided by the Google File System, HBase provides Bigtable-like
+capabilities on top of Apache Hadoop.
+  EOS
+
+  option :server do
+    description 'to select the "server" VM'
+    default 'server'
+  end
+
+  TABLES = %w(people address phone_number)
+  action :list do
+    description 'List all tables in hbase.'
+
+    handler do
+      puts 'TABLE'
+      TABLES.each { |item| puts item }
+      puts '3 row(s) in 1.3310 seconds'
+    end
+    arguments :disable
+  end
+
+  action :scan do
+    description 'Scan a table.'
+
+    handler do
+      fail StandardError, 'please specify table name' unless arguments.length > 0
+      fail StandardError, 'too many arguments' if arguments.length > 1
+      table_name = arguments.first
+      fail StandardError, "unknown table \"#{table_name}\"" unless TABLES.include?(table_name)
+      puts <<-EOS
+ROW                                                 COLUMN+CELL
+ my-test:1                        column=c1, timestamp=1432748503634, value=0.5
+ my-test:2                        column=c1, timestamp=1432748503781, value=1.5
+2 row(s) in 0.4250 seconds
+      EOS
+    end
+  end
+end
+
+cli.execute(ARGV)

data/examples/my-command

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+
+# Here is an example on how to use a custom command handler
+#
+# This example also shows :boolean and :numeric option types
+# with their default value settings
+
+require 'cliqr'
+
+# a custom command handler for base command
+class MyCommandHandler < Cliqr.command
+  def execute(context)
+    puts 'executing my awesome command'
+    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-2' argument" unless context.option?('test-2')
+  end
+end
+
+# another custom command handler for a action
+class MyActionHandler < Cliqr.command
+  def execute(context)
+    puts "command executed : #{context.command}"
+  end
+end
+
+cli = Cliqr.interface do
+  name 'my-command'
+  description 'this is an awesome command...try it out'
+  handler MyCommandHandler
+
+  option 'an-option' do
+    short 'a'
+    description 'this is a option'
+    default :tag => 'qwerty'
+  end
+
+  option 'count' do
+    short 'c'
+    description 'count of something'
+    type :numeric
+    default 10
+  end
+
+  option 'single' do
+    short 's'
+    description 'a boolean option'
+    type :boolean
+  end
+
+  option 'test-1'
+  option 'test-2'
+
+  action 'my-action' do
+    handler MyActionHandler
+    description 'a simple action handler'
+  end
+end
+
+cli.execute(ARGV)