hanami-cli 0.0.0 → 0.1.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1c45c9953f8cbc9953afeb9bbff4afbeac37688e
-  data.tar.gz: 4dc2067769d30dbd2e67ff0ca9e4336b1b764723
+  metadata.gz: f875978b7f89336681b8bd5a565c983bfb958ff3
+  data.tar.gz: 1c96e142ccf87d61f9832c15df06ae2f1d6e6f2c
 SHA512:
-  metadata.gz: 832324e8c5b63983d3997cd790ff7d0f6a0365cf225d54d26679b4b5b00ad2bd75afe7201d61b367de91015a465d390a8da4f3f9a620a98209a46a2f7f3d20c2
-  data.tar.gz: 58bb256b445a299ce3e51448a507a5a57eb74883f6293861dc69835aa243c2392d40f30724ce1db598b2a7874a761270f35e78f22dbdb29df582f8c5319dbbfa
+  metadata.gz: 998f3111282c4df19b87bbc918e35517c47f680234ae5e2bd4372c8a7280b6a8012a12b11ff17d302e0f7e21ec007f9216d77c4542631eb9910c4ab48636b34e
+  data.tar.gz: a9dc63d4465bfcaa132937f36c7825249ed0dcbe4cd6799f4bde5a567f8d3fc90c23ee9f02e4636ec9f4bd439dbdc910db68eead6dc3e3113cada80a9e150897

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+.byebug_history

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,19 @@
+language: ruby
+sudo: false
+cache: bundler
+before_install:
+  - gem update --system
+  - rvm @global do gem uninstall bundler -a -x
+  - rvm @global do gem install bundler -v 1.14.6
+script: 'bundle exec rake --trace'
+rvm:
+  - 2.3.4
+  - 2.4.1
+  - ruby-head
+  - jruby-9.1.8.0
+  - jruby-head
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Hanami::CLI
+General purpose Command Line Interface (CLI) framework for Ruby
+
+## v0.1.0.beta1 - 2017-08-11
+### Added
+- [Alfonso Uceda, Luca Guidi] Commands banner and usage
+- [Alfonso Uceda] Added support for subcommands
+- [Alfonso Uceda] Validations for arguments and options
+- [Alfonso Uceda] Commands arguments and options
+- [Alfonso Uceda] Commands description
+- [Alfonso Uceda, Oana Sipos] Commands aliases
+- [Luca Guidi] Exit on unknown command
+- [Luca Guidi, Alfonso Uceda, Oana Sipos] Command lookup
+- [Luca Guidi, Tim Riley] Trie based registry to register commands and allow third-parties to override/add commands

data/Gemfile

@@ -1,4 +1,11 @@
 source 'https://rubygems.org'
-
-# Specify your gem's dependencies in hanami-cli.gemspec
 gemspec
+
+unless ENV['TRAVIS']
+  gem 'byebug', require: false, platforms: :mri
+  gem 'yard',   require: false
+end
+
+gem 'hanami-utils', '1.1.0.beta1', require: false, git: 'https://github.com/hanami/utils.git', branch: 'develop'
+
+gem 'rubocop', '0.49.1', require: false

data/README.md

@@ -1,15 +1,189 @@
-# Hanami::Cli
+# Hanami::CLI
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/hanami/cli`. To experiment with that code, run `bin/console` for an interactive prompt.
+General purpose Command Line Interface (CLI) framework for Ruby.
 
-TODO: Delete this and the text above, and describe your gem
+:warning: **This is a general framework for Ruby (aka `thor` gem replacement), NOT the implementation of the `hanami` CLI commands** :warning:
+
+## Features
+
+### Registration
+
+For a given _command name_, you can register a corresponding _command object_ (aka command).
+
+Example: for `foo hi` _command name_ there is the corresponding `Foo::CLI::Hello` _command object_.
+
+```ruby
+#!/usr/bin/env ruby
+require "bundler/setup"
+require "hanami/cli"
+
+module Foo
+  module CLI
+    module Commands
+      extend Hanami::CLI::Registry
+
+      class Hello < Hanami::CLI::Command
+        def call(*)
+        end
+      end
+    end
+  end
+end
+
+class Version < Hanami::CLI::Command
+  def call(*)
+  end
+end
+
+Foo::CLI::Commands.register "hi", Foo::CLI::Commands::Hello
+Foo::CLI::Commands.register "v",  Version
+
+Hanami::CLI.new(Foo::CLI::Commands).call
+```
+
+**Please note:** there is NOT a convention between the _command name_ and the _command object_ class.
+The manual _registration_ assigns a _command object_ to a _command name_.
+
+### Commands as objects
+
+A command is a subclass of `Hanami::CLI::Command` and it MUST respond to `#call(*)`.
+
+### Subcommands
+
+There is nothing special in subcommands: they are just _command objects_ registered under a **nested** _command name_.
+
+```ruby
+#!/usr/bin/env ruby
+require "bundler/setup"
+require "hanami/cli"
+
+module Foo
+  module CLI
+    module Commands
+      extend Hanami::CLI::Registry
+
+      module Generate
+        class Configuration < Hanami::CLI::Command
+          def call(*)
+          end
+        end
+      end
+    end
+  end
+end
+
+Foo::CLI::Commands.register "generate configuration", Foo::CLI::Commands::Generate::Configuration
+
+Hanami::CLI.new(Foo::CLI::Commands).call
+```
+
+### Arguments
+
+An argument is a token passed after the _command name_.
+For instance, given the `foo greet` command, when an user types `foo greet Luca`, then `Luca` is considered an argument.
+A command can accept none or many arguments.
+An argument can be declared as _required_.
+
+```ruby
+#!/usr/bin/env ruby
+require "bundler/setup"
+require "hanami/cli"
+
+module Foo
+  module CLI
+    module Commands
+      extend Hanami::CLI::Registry
+
+      class Greet < Hanami::CLI::Command
+        argument :name, required: true, desc: "The name of the person to greet"
+        argument :age, desc: "The age of the person to greet"
+
+        def call(name:, age: nil, **)
+          result = "Hello, #{name}."
+          result = "#{result} You are #{age} years old." unless age.nil?
+
+          puts result
+        end
+      end
+
+      register "greet", Greet
+    end
+  end
+end
+
+Hanami::CLI.new(Foo::CLI::Commands).call
+```
+
+```shell
+% foo greet Luca
+Hello, Luca.
+```
+
+```shell
+% foo greet Luca 35
+Hello, Luca. You are 35 years old.
+```
+
+```shell
+% foo greet
+ERROR: "foo greet" was called with no arguments
+Usage: "foo greet NAME"
+```
+
+### Option
+
+An option is a named argument that is passed after the _command name_ **and** the arguments.
+
+For instance, given the `foo request` command, when an user types `foo request --mode=http2`, then `--mode=http2` is considered an option.
+A command can accept none or many options.
+
+```ruby
+#!/usr/bin/env ruby
+require "bundler/setup"
+require "hanami/cli"
+
+module Foo
+  module CLI
+    module Commands
+      extend Hanami::CLI::Registry
+
+      class Request < Hanami::CLI::Command
+        option :mode, default: "http", values: %w[http http2], desc: "The request mode"
+
+        def call(**options)
+          puts "Performing a request (mode: #{options.fetch(:mode)})"
+        end
+      end
+
+      register "request", Request
+    end
+  end
+end
+
+Hanami::CLI.new(Foo::CLI::Commands).call
+```
+
+```shell
+% foo request
+Performing a request (mode: http)
+```
+
+```shell
+% foo request --mode=http2
+Performing a request (mode: http2)
+```
+
+```shell
+% foo request --mode=unknown
+Error: Invalid param provided
+```
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'hanami-cli'
+gem "hanami-cli"
 ```
 
 And then execute:
@@ -22,7 +196,232 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Imagine to build a CLI executable `foo` for your Ruby project.
+
+```ruby
+#!/usr/bin/env ruby
+require "bundler/setup"
+require "hanami/cli"
+
+module Foo
+  module CLI
+    module Commands
+      extend Hanami::CLI::Registry
+
+      class Version < Hanami::CLI::Command
+        desc "Print version"
+
+        def call(*)
+          puts "1.0.0"
+        end
+      end
+
+      class Echo < Hanami::CLI::Command
+        desc "Print input"
+
+        argument :input, desc: "Input to print"
+
+        example [
+          "             # Prints 'wuh?'",
+          "hello, folks # Prints 'hello, folks'"
+        ]
+
+        def call(input: nil, **)
+          if input.nil?
+            puts "wuh?"
+          else
+            puts input
+          end
+        end
+      end
+
+      class Start < Hanami::CLI::Command
+        desc "Start Foo machinery"
+
+        argument :root, required: true, desc: "Root directory"
+
+        example [
+          "path/to/root # Start Foo at root directory"
+        ]
+
+        def call(root:, **)
+          puts "started - root: #{root}"
+        end
+      end
+
+      class Stop < Hanami::CLI::Command
+        desc "Stop Foo machinery"
+
+        option :graceful, type: :boolean, default: true, desc: "Graceful stop"
+
+        def call(**options)
+          puts "stopped - graceful: #{options.fetch(:graceful)}"
+        end
+      end
+
+      module Generate
+        class Configuration < Hanami::CLI::Command
+          desc "Generate configuration"
+
+          def call(*)
+            puts "generated configuration"
+          end
+        end
+
+        class Test < Hanami::CLI::Command
+          desc "Generate tests"
+
+          option :framework, default: "minitest", values: %w[minitest rspec]
+
+          def call(framework:, **)
+            puts "generated tests - framework: #{framework}"
+          end
+        end
+      end
+
+      register "version", Version, aliases: ["v", "-v", "--version"]
+      register "echo",    Echo
+      register "start",   Start
+      register "stop",    Stop
+
+      register "generate", aliases: ["g"] do |prefix|
+        prefix.register "config", Generate::Configuration
+        prefix.register "test",   Generate::Test
+      end
+    end
+  end
+end
+
+Hanami::CLI.new(Foo::CLI::Commands).call
+```
+
+Let's have a look at the command line usage.
+
+### Available commands
+
+```shell
+% foo
+Commands:
+  foo echo [INPUT]                       # Print input
+  foo generate [SUBCOMMAND]
+  foo start ROOT                         # Start Foo machinery
+  foo stop                               # Stop Foo machinery
+  foo version                            # Print version
+```
+
+### Help
+
+```shell
+% foo echo --help
+Command:
+  foo echo
+
+Usage:
+  foo echo [INPUT]
+
+Description:
+  Print input
+
+Arguments:
+  INPUT               	# Input to print
+
+Options:
+  --help, -h                      	# Print this help
+
+Examples:
+  foo echo              # Prints 'wuh?'
+  foo echo hello, folks # Prints 'hello, folks'
+```
+
+### Optional arguments
+
+```shell
+% foo echo
+wuh?
+
+% foo echo hello
+hello
+```
+
+### Required arguments
+
+```shell
+% foo start .
+started - root: .
+```
+
+```shell
+% foo start
+ERROR: "foo start" was called with no arguments
+Usage: "foo start ROOT"
+```
+
+### Options
+
+```shell
+% foo generate test
+generated tests - framework: minitest
+```
+
+```shell
+% foo generate test --framework=rspec
+generated tests - framework: rspec
+```
+
+```shell
+% foo generate test --framework=unknown
+Error: Invalid param provided
+```
+
+### Boolean options
+
+```shell
+% foo stop
+stopped - graceful: true
+```
+
+```shell
+% foo stop --no-graceful
+stopped - graceful: false
+```
+
+### Subcommands
+
+```shell
+% foo generate
+Commands:
+  foo generate config           # Generate configuration
+  foo generate test             # Generate tests
+```
+
+### Aliases
+
+```shell
+% foo version
+1.0.0
+```
+
+```shell
+% foo v
+1.0.0
+```
+
+```shell
+% foo -v
+1.0.0
+```
+
+```shell
+% foo --version
+1.0.0
+```
+
+### Subcommand aliases
+
+```shell
+% foo g config
+generated configuration
+```
 
 ## Development
 
@@ -32,5 +431,12 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/jodosha/hanami-cli.
+Bug reports and pull requests are welcome on GitHub at https://github.com/hanami/cli.
+
+## Alternatives
+
+  * [thor](http://whatisthor.com/)
+
+## Copyright
 
+Copyright © 2017 Luca Guidi – Released under MIT License