cli-template 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 042da28b0ec9d9d406c3204bb08210c996c98022f2b75a2bfc454d7b79916c1e
-  data.tar.gz: 8ce3733852b7f5790a466699572323f82862a2ed18f92a42a7247a815d050879
+  metadata.gz: 5cec11731996364ad6e192824c457ce0800423eb72ac4782bdf72bfb8fd32155
+  data.tar.gz: 8a5748d23604d64f35a5ecc98d6fbf1610cde7ac848c8480be36629d4dd3d5b3
 SHA512:
-  metadata.gz: cfe099ee8efae48d4752a570652361ae6e147fd7be9716dcd9bfb35f58fcd61ce0d24a53749c24817abdb57f0f3dc0c8f3f9ed3ea28de537e6a38960e6b7f3a2
-  data.tar.gz: ad5c81b830fe057937dd74419bbac0e19de6e41f84b967572babb61ea2c8631a84f7c1899fdec6f3a4356d00d7e6aca51305adfdaa4364aa27fcb7c239d76336
+  metadata.gz: 1ad85e072ea3ca0c17b63c568034d0d962b3d12baa8c848efa585c6d21aa3bd8c49c2f6305ca73fd63002fbafd1a7c600037e0952419336ffcf2420562ffcc36
+  data.tar.gz: 33a433e8b3b050a39f9fd11563d6c12843e7979d18a0f0401a5d1b61813e6dd419cb6b0f6fd57a1d18ed1328c045f2ded87968a061915787940211d6e9fdcaa4

data/CHANGELOG.md

@@ -3,6 +3,11 @@
 All notable changes to this project will be documented in this file.
 This project *tries* to adhere to [Semantic Versioning](http://semver.org/), even before v1.0.
 
+## [3.1.0]
+- Merge pull request #1 from tongueroo/completions: support for TAB auto-completion
+- add completions command to starter project
+- add completions:script command
+
 ## [3.0.0]
 - tool is now called cli-template
 - namespaced commands support

data/README.md

@@ -3,7 +3,7 @@
 [![CircleCI](https://circleci.com/gh/tongueroo/cli-template.svg?style=svg)](https://circleci.com/gh/tongueroo/cli-template)
 [![Maintainability](https://api.codeclimate.com/v1/badges/c6c4f26aaafccab10baf/maintainability)](https://codeclimate.com/github/tongueroo/cli-template/maintainability)
 
-`cli-template` is a generator tool that builds a starter CLI project based on [Thor](http://whatisthor.com/). It is the successor tool to [thor_template](https://github.com/tongueroo/thor_template), which is also a tool that generates CLI projects.  The main difference is `cli-template` allows for namespace commands.  The usage section demonstrates a namespace command below.
+`cli-template` is a generator tool that builds a starter CLI project based on [Thor](http://whatisthor.com/). It is the successor tool to [thor_template](https://github.com/tongueroo/thor_template), which is also a tool that generates CLI projects.  The main difference is `cli-template` uses colons for namespaced commands.  The usage section demonstrates a namespaced command below.
 
 The predecessor tool is covered in this original blog post, [Build Thor CLI Project in Under a Second](https://blog.boltops.com/2017/09/14/build-thor-cli-project-in-under-a-second). It covers usage and also contains a video demo.  An updated blog post will eventually be made, for now, refer to the original blog post.
 
@@ -43,6 +43,16 @@ And run:
 rake release
 ```
 
+When installed as a gem, you no longer have to prepend exe in front of the command.  For example, `exe/mycli` becomes the `mycli` command.
+
+## Auto Completion
+
+The generated CLI tool supports TAB auto-completion.  To enable auto, you can add this to your `~/.bashrc` or `~/.profile`:
+
+  eval $(mycli completions:script)
+
+Remember to re-load your shell. Note, the auto completion will only work once you tool is installed and it's binary is avaialble in your PATH.
+
 ## Installation
 
 ```sh

data/lib/cli-template/sequence.rb

@@ -9,7 +9,7 @@ class CliTemplate::Sequence < Thor::Group
   include CliTemplate::Helpers
 
   def self.source_root
-    File.expand_path("../../templates/skeleton", __FILE__)
+    File.expand_path("../../templates/default", __FILE__)
   end
 
 private

data/lib/cli-template/version.rb

@@ -1,3 +1,3 @@
 module CliTemplate
-  VERSION = "3.0.0"
+  VERSION = "3.1.0"
 end

data/lib/templates/{skeleton → default}/lib/%project_name%.rb.tt

@@ -7,4 +7,6 @@ module <%= project_class_name %>
   autoload :RakeCommand, "<%= underscored_name %>/rake_command"
   autoload :CLI, "<%= underscored_name %>/cli"
   autoload :Sub, "<%= underscored_name %>/sub"
+  autoload :Completions, "<%= underscored_name %>/completions"
+  autoload :Completer, "<%= underscored_name %>/completer"
 end

data/lib/templates/{skeleton → default}/lib/%underscored_name%/cli.rb.tt

@@ -33,8 +33,8 @@ class <%= project_class_name %>::CLI
 
   # thor_args normalized the args Array to work with our Thor command
   # subclasses.
-  # 1. The namespace is stripe
-  # 2. Help is shifted in front if a help flag is detected
+  # 1. The namespace is stripped
+  # 2. The help is shifted in front if a help flag is detected
   def thor_args
     args = @given_args.clone
 
@@ -69,8 +69,12 @@ class <%= project_class_name %>::CLI
   end
 
   # 1. look up Thor tasks
-  # 2. look up Rake tasks
+  # 2. look up Rake tasks - currently disabled
   # 3. help menu with all commands when both Thor and Rake tasks are not found
+  #
+  # Example:
+  #
+  #   lookup("sub:hello") => Sub
   def lookup(full_command)
     thor_task_found = <%= project_class_name %>::Command.namespaced_commands.include?(full_command)
     if thor_task_found
@@ -131,10 +135,12 @@ class <%= project_class_name %>::CLI
     shell.say "Commands:"
     shell.print_table(thor_list, :indent => 2, :truncate => true)
 
-    unless rake_list.empty?
-      shell.say "\nCommands via rake:"
-      shell.print_table(rake_list, :indent => 2, :truncate => true)
-    end
+    # TODO: commenting out for now, feels weird to show the rake tasks
+    # automatically also by default. Maybe add an option for this.
+    # unless rake_list.empty?
+    #   shell.say "\nCommands via rake:"
+    #   shell.print_table(rake_list, :indent => 2, :truncate => true)
+    # end
 
     shell.say "\n"
     shell.say main_help_body

data/lib/templates/{skeleton → default}/lib/%underscored_name%/command.rb.tt

@@ -22,10 +22,8 @@ module <%= project_class_name %>
       #   ["help"]
       #   ["dynamodb:migrate"]
       #
-      # Same signature as RakeCommand.perform.  Not using full_command.
-      #
-      # To call a thor task via ruby.
-      # Signature is a little weird with the repetition, examples:
+      # Same signature as RakeCommand.perform.  Signature is a little weird
+      # with some repetition.  Examples:
       #
       #   <%= project_class_name %>::Main.perform("hello", ["hello"])
       #   <%= project_class_name %>::Main.perform("dynamodb:migrate", ["migrate"])
@@ -66,22 +64,33 @@ module <%= project_class_name %>
             next
           end
 
-          # special mapping cases
-          special_cases = {
-            "<%= project_class_name %>::Cli" => "<%= project_class_name %>::CLI",
-            "<%= project_class_name %>::Version" => "<%= project_class_name %>::VERSION",
-          }
-          class_name = special_cases[class_name] || class_name
+          class_name = class_map[class_name] || class_name
 
           puts "eager_load! loading path: #{path} class_name: #{class_name}" if debug?
           class_name.constantize # dont have to worry about order.
         end
       end
 
+      # Special class mapping cases. This is because ActiveSupport's autoloading
+      # forces a specific naming convention.
+      def class_map
+        map = {
+          "<%= project_class_name %>::Cli" => "<%= project_class_name %>::CLI",
+          "<%= project_class_name %>::Version" => "<%= project_class_name %>::VERSION",
+          "<%= project_class_name %>::Completion" => "<%= project_class_name %>::Completions",
+        }
+        map.merge(additional_class_map)
+        map
+      end
+
+      # Override this if you need add addtional class mappings.
+      def additional_class_map
+        {}
+      end
+
       # Fully qualifed task names. Examples:
-      #   build
-      #   process:controller
-      #   dynamodb:migrate:down
+      #   hello
+      #   sub:goodbye
       def namespaced_commands
         eager_load!
         subclasses.map do |klass|
@@ -124,12 +133,16 @@ module <%= project_class_name %>
         list.sort_by! { |array| array[0] }
       end
 
+      # Example:
+      #    klass_from_namespace(nil) => Main
+      #    klass_from_namespace("sub") => Sub
       def klass_from_namespace(namespace)
         if namespace.nil?
           <%= project_class_name %>::Main
         else
           class_name = namespace.gsub(':','/')
           class_name = "<%= project_class_name %>::#{class_name.classify}"
+          class_name = class_map[class_name] || class_name
           class_name.constantize
         end
       end

data/lib/templates/default/lib/%underscored_name%/completer.rb.tt

@@ -0,0 +1,138 @@
+# Code Explanation.  This is mainly focused on the run method.
+#
+# There are 3 main branches of logic for completions:
+#
+#   1. top-level commands - when there are zero completed words
+#   2. params completions - when a command has some required params
+#   3. options completions - when we have finished auto-completing the top-level command and required params, the rest of the completion words will be options
+#
+# Terms:
+#
+#   params - these are params in the command itself. Example: for the method `scale(service, count)` the params would be `service, count`.
+#   options - these are cli options flags.  Examples: --noop, --verbose
+#
+# When we are done processing method params, the completions will be only options. When the detected params size is greater than the arity we are have finished auto-completing the parameters in the method declaration.  For example, say you had a method for a CLI command with the following form:
+#
+#   scale(service, count) = arity of 2
+#
+#   <%= project_name %> scale service count [TAB] # there are 3 params including the "scale" command
+#
+# So the completions will be something like:
+#
+#   --noop --verbose etc
+#
+# A note about artity values:
+#
+# We are using the arity of the command method to determine if we have finish auto-completing the params completions. When the ruby method has a splat param, it's arity will be negative.  Here are some example methods and their arities.
+#
+#    ship(service) = 1
+#    scale(service, count) = 2
+#    ships(*services) = -1
+#    foo(example, *rest) = -2
+#
+# Fortunately, negative and positive arity values are processed the same way. So we take simply take the abs of the arity.
+#
+# To test:
+#
+#   <%= project_name %> completions
+#   <%= project_name %> completions hello
+#   <%= project_name %> completions hello name
+#   <%= project_name %> completions hello name --
+#   <%= project_name %> completions hello name --noop
+#
+#   <%= project_name %> completions
+#   <%= project_name %> completions sub:goodbye
+#   <%= project_name %> completions sub:goodbye name
+#
+# Note when testing, the first top-level word must be an exact match
+#
+#   <%= project_name %> completions hello # works fine
+#   <%= project_name %> completions he # incomplete, this will just break
+#
+# The completions assumes that the top-level word that is being passed in
+# from completor/scripts.sh will always match exactly.  This must be the
+# case.  For parameters, the word does not have to match exactly.
+#
+module <%= project_class_name %>
+  class Completer
+    autoload :Script, '<%= underscored_name %>/completer/script'
+
+    def initialize(*params)
+      @params = params
+    end
+
+    def current_command
+      @params[0]
+    end
+
+    # Example: sub:goodbye => "sub"
+    def namespace
+      return nil unless current_command
+
+      if current_command.include?(':')
+        words = current_command.split(':')
+        words.pop
+        words.join(':')
+      end
+    end
+
+    # Example: sub:goodbye => "goodbye"
+    def trailing_command
+      current_command.split(':').last
+    end
+
+    def run
+      if @params.size == 0
+        puts all_commands
+        return
+      end
+
+      # will only get to here if the top-level command has been fully auto-completed.
+      arity = command_class.instance_method(trailing_command).arity.abs
+      if @params.size <= arity
+        puts params_completions(current_command)
+      else
+        puts options_completions(current_command)
+      end
+    end
+
+    # all top-level commands
+    def all_commands
+      # Interesing, extra :help commands show up here but no whne using
+      # <%= project_class_name %>::Command.help_list in main_help -> thor_list
+      # We'll filter out :help for auto-completion.
+      commands = <%= project_class_name %>::Command.namespaced_commands
+      commands.reject { |c| c =~ /:help$/ }
+    end
+
+    def params_completions(current_command)
+      method_params = command_class.instance_method(trailing_command).parameters
+      # Example:
+      # >> Sub.instance_method(:goodbye).parameters
+      # => [[:req, :name]]
+      # >>
+      method_params.map!(&:last)
+
+      offset = @params.size - 1
+      offset_params = method_params[offset..-1]
+      method_params[offset..-1].first
+    end
+
+    def options_completions(current_command)
+      used = ARGV.select { |a| a.include?('--') } # so we can remove used options
+
+      method_options = command_class.all_commands[trailing_command].options.keys
+      class_options = command_class.class_options.keys
+
+      all_options = method_options + class_options
+
+      all_options.map! { |o| "--#{o.to_s.dasherize}" }
+      filtered_options = all_options - used
+      filtered_options
+    end
+
+    def command_class
+      @command_class ||= <%= project_class_name %>::Command.klass_from_namespace(namespace)
+    end
+  end
+end

data/lib/templates/default/lib/%underscored_name%/completer/script.rb.tt

@@ -0,0 +1,6 @@
+class <%= project_class_name %>::Completer::Script
+  def self.generate
+    bash_script = File.expand_path("script.sh", File.dirname(__FILE__))
+    puts "source #{bash_script}"
+  end
+end

data/lib/templates/default/lib/%underscored_name%/completer/script.sh.tt

@@ -0,0 +1,16 @@
+_<%= project_name %>() {
+  COMPREPLY=()
+  local word="${COMP_WORDS[COMP_CWORD]}"
+
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    local completions=$(<%= project_name %> completions)
+    COMPREPLY=( $(compgen -W "$completions" -- "$word") )
+  else
+    local words=("${COMP_WORDS[@]}")
+    unset words[0]
+    local completions=$(<%= project_name %> completions ${words[@]})
+    COMPREPLY=( $(compgen -W "$completions" -- "$word") )
+  fi
+}
+
+complete -F _<%= project_name %> <%= project_name %>

data/lib/templates/default/lib/%underscored_name%/completions.rb.tt

@@ -0,0 +1,9 @@
+module <%= project_class_name %>
+  class Completions < Command
+    desc "script", "generates script that can be eval to setup auto-completion"
+    long_desc Help.text("completions:script")
+    def script
+      Completer::Script.generate
+    end
+  end
+end

data/lib/templates/default/lib/%underscored_name%/help/completions.md.tt

@@ -0,0 +1,18 @@
+Prints words for TAB auto-completion.
+
+Examples:
+
+  <%= project_name %> completions
+  <%= project_name %> completions hello
+  <%= project_name %> completions hello name
+
+To enable, TAB auto-completion add the following to your profile:
+
+  eval $(<%= project_name %> completions:script)
+
+Auto-completion example usage:
+
+  <%= project_name %> [TAB]
+  <%= project_name %> hello [TAB]
+  <%= project_name %> hello name [TAB]
+  <%= project_name %> hello name --[TAB]

data/lib/templates/default/lib/%underscored_name%/help/completions/script.md.tt

@@ -0,0 +1,3 @@
+To use, add the following to your ~/.bashrc or ~/.profile
+
+  eval $(<%= project_name %> completions:script)

data/lib/templates/default/lib/%underscored_name%/help/hello.md.tt

@@ -0,0 +1,5 @@
+Examples:
+
+  <%= project_name %> hello
+  <%= project_name %> hello NAME
+  <%= project_name %> hello NAME --from me

data/lib/templates/default/lib/%underscored_name%/help/sub/goodbye.md.tt

@@ -0,0 +1,5 @@
+Examples:
+
+  <%= project_name %> sub:goodbye
+  <%= project_name %> sub:goodbye NAME
+  <%= project_name %> sub:goodbye NAME --from me

data/lib/templates/{skeleton → default}/lib/%underscored_name%/main.rb.tt

@@ -13,6 +13,12 @@ module <%= project_class_name %>
       puts "Hello #{name}"
     end
 
+    desc "completions *PARAMS", "prints words for auto-completion"
+    long_desc Help.text(:completions)
+    def completions(*params)
+      Completer.new(*params).run
+    end
+
     desc "version", "prints version"
     def version
       puts VERSION

data/lib/templates/default/spec/lib/cli_spec.rb.tt

@@ -0,0 +1,37 @@
+require "spec_helper"
+
+describe <%= project_class_name %>::CLI do
+  before(:all) do
+    @args = "--from Tung"
+  end
+
+  describe "<%= project_name %>" do
+    it "hello" do
+      out = execute("exe/<%= project_name %> hello world #{@args}")
+      expect(out).to include("from: Tung\nHello world")
+    end
+
+    it "goodbye" do
+      out = execute("exe/<%= project_name %> sub:goodbye world #{@args}")
+      expect(out).to include("from: Tung\nGoodbye world")
+    end
+
+    it "completions" do
+      out = execute("exe/<%= project_name %> completions")
+      expect(out).to include("hello")
+      expect(out).to include("sub:goodbye")
+
+      out = execute("exe/<%= project_name %> completions hello")
+      expect(out).to include("name")
+
+      out = execute("exe/<%= project_name %> completions hello name")
+      expect(out).to include("--from")
+
+      out = execute("exe/<%= project_name %> completions sub:goodbye")
+      expect(out).to include("name")
+
+      out = execute("exe/<%= project_name %> completions sub:goodbye name")
+      expect(out).to include("--from")
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cli-template
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Tung Nguyen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-09 00:00:00.000000000 Z
+date: 2018-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -164,28 +164,34 @@ files:
 - lib/cli-template/new.rb
 - lib/cli-template/sequence.rb
 - lib/cli-template/version.rb
-- lib/templates/skeleton/%project_name%.gemspec.tt
-- lib/templates/skeleton/.gitignore
-- lib/templates/skeleton/.rspec
-- lib/templates/skeleton/CHANGELOG.md
-- lib/templates/skeleton/Gemfile.tt
-- lib/templates/skeleton/Guardfile
-- lib/templates/skeleton/LICENSE.txt
-- lib/templates/skeleton/README.md.tt
-- lib/templates/skeleton/Rakefile
-- lib/templates/skeleton/exe/%project_name%.tt
-- lib/templates/skeleton/lib/%project_name%.rb.tt
-- lib/templates/skeleton/lib/%underscored_name%/cli.rb.tt
-- lib/templates/skeleton/lib/%underscored_name%/command.rb.tt
-- lib/templates/skeleton/lib/%underscored_name%/help.rb.tt
-- lib/templates/skeleton/lib/%underscored_name%/help/hello.md.tt
-- lib/templates/skeleton/lib/%underscored_name%/help/sub/goodbye.md.tt
-- lib/templates/skeleton/lib/%underscored_name%/main.rb.tt
-- lib/templates/skeleton/lib/%underscored_name%/rake_command.rb.tt
-- lib/templates/skeleton/lib/%underscored_name%/sub.rb.tt
-- lib/templates/skeleton/lib/%underscored_name%/version.rb.tt
-- lib/templates/skeleton/spec/lib/cli_spec.rb.tt
-- lib/templates/skeleton/spec/spec_helper.rb.tt
+- lib/templates/default/%project_name%.gemspec.tt
+- lib/templates/default/.gitignore
+- lib/templates/default/.rspec
+- lib/templates/default/CHANGELOG.md
+- lib/templates/default/Gemfile.tt
+- lib/templates/default/Guardfile
+- lib/templates/default/LICENSE.txt
+- lib/templates/default/README.md.tt
+- lib/templates/default/Rakefile
+- lib/templates/default/exe/%project_name%.tt
+- lib/templates/default/lib/%project_name%.rb.tt
+- lib/templates/default/lib/%underscored_name%/cli.rb.tt
+- lib/templates/default/lib/%underscored_name%/command.rb.tt
+- lib/templates/default/lib/%underscored_name%/completer.rb.tt
+- lib/templates/default/lib/%underscored_name%/completer/script.rb.tt
+- lib/templates/default/lib/%underscored_name%/completer/script.sh.tt
+- lib/templates/default/lib/%underscored_name%/completions.rb.tt
+- lib/templates/default/lib/%underscored_name%/help.rb.tt
+- lib/templates/default/lib/%underscored_name%/help/completions.md.tt
+- lib/templates/default/lib/%underscored_name%/help/completions/script.md.tt
+- lib/templates/default/lib/%underscored_name%/help/hello.md.tt
+- lib/templates/default/lib/%underscored_name%/help/sub/goodbye.md.tt
+- lib/templates/default/lib/%underscored_name%/main.rb.tt
+- lib/templates/default/lib/%underscored_name%/rake_command.rb.tt
+- lib/templates/default/lib/%underscored_name%/sub.rb.tt
+- lib/templates/default/lib/%underscored_name%/version.rb.tt
+- lib/templates/default/spec/lib/cli_spec.rb.tt
+- lib/templates/default/spec/spec_helper.rb.tt
 - spec/lib/cli_spec.rb
 - spec/spec_helper.rb
 homepage: https://gitub.com/tongueroo/cli-template

data/lib/templates/skeleton/lib/%underscored_name%/help/hello.md.tt

@@ -1,3 +0,0 @@
-Examples:
-
-  <%= project_name %> hello

data/lib/templates/skeleton/lib/%underscored_name%/help/sub/goodbye.md.tt

@@ -1,3 +0,0 @@
-Examples:
-
-  <%= project_name %> sub:goodbye

data/lib/templates/skeleton/spec/lib/cli_spec.rb.tt

@@ -1,24 +0,0 @@
-require "spec_helper"
-
-# to run specs with what"s remembered from vcr
-#   $ rake
-#
-# to run specs with new fresh data from aws api calls
-#   $ rake clean:vcr ; time rake
-describe <%= project_class_name %>::CLI do
-  before(:all) do
-    @args = "--from Tung"
-  end
-
-  describe "<%= project_name %>" do
-    it "should hello world" do
-      out = execute("exe/<%= project_name %> hello world #{@args}")
-      expect(out).to include("from: Tung\nHello world")
-    end
-
-    it "should goodbye world" do
-      out = execute("exe/<%= project_name %> sub:goodbye world #{@args}")
-      expect(out).to include("from: Tung\nGoodbye world")
-    end
-  end
-end