clamp-completer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 801dce4fae329b01ac6efe2a99e47a0bd6e7d1be310347c8abccfef53b7be900
+  data.tar.gz: 67f5db2a8d3d7bda3939523c2543435333a38811e93fcf679e20d0d9dfe66093
+SHA512:
+  metadata.gz: 875e58f9bb107cfb1f66696a9e70cde324a5deabfed64494be63c71658eb0893df6ea1ec63d92bba0fd5d22277fda3cc9c00dbf58a0ed5f1581793ab1a9e2d9e
+  data.tar.gz: 07750b2fe30a8136eeb06cb6d19088e9848aa56915f34e5db2abaaadcfa2aa5ce76827dd5d91dcd4db2ec54c8145dab16f02e3d7245511bcc959f9988374c6da

data/README.md

@@ -0,0 +1,98 @@
+[![Build Status](https://travis-ci.org/kontena/clamp-completer.svg?branch=master)](https://travis-ci.org/kontena/clamp-completer)
+[![Gem Version](https://badge.fury.io/rb/clamp-completer)](https://badge.fury.io/rb/clamp-completer)
+
+# Clamp::Completer
+
+Automatically generate shell auto-completion scripts for Ruby command-line tools built using the [clamp](https://github.com/mdub/clamp) gem.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'clamp-completer'
+```
+
+Or install it yourself as:
+
+```
+$ gem install clamp-completer
+```
+
+## Usage
+
+Require the `clamp/completer` and in your application's root command, add a subcommand:
+
+```ruby
+require 'clamp/completer'
+
+Clamp do
+  subcommand "complete", "shell autocompletions", Clamp::Completer.new(self)
+end
+```
+
+This will add a `complete` subcommand:
+
+```
+$ your_app complete zsh
+$ your_app complete bash
+```
+
+You can redirect the output to a static file or load the output directly into the running environment:
+
+```
+# zsh / bash:
+$ source <(your_app complete)
+# or for the macOs preinstalled bash version:
+$ source /dev/stdin <<<"$(your_app complete bash)"
+```
+
+### Customizing completions
+
+Currently, subcommand completions and flag-type options defined through `option '--debug', :flag, 'enable debug'` should work correctly out-of-the-box. For options that take parameters,
+such as file paths or a predefined set of words, you can define methods on your command classes that will be used to determine how the values should be completed:
+
+```ruby
+Clamp do
+  option '--config', 'YAML_FILE', "configuration YAML file path"
+
+  def complete_yaml_file # name derived from the YAML_FILE argument description
+    { glob: '*.yml' }
+  end
+end
+```
+
+```ruby
+Clamp do
+  option '--role', 'ROLE_NAME', "node role"
+
+  def complete_role # name derived from the attribute name
+    "master worker" # will add "master" and "worker" as completion responses when you do: your_app --role <tab>
+  end
+end
+```
+
+#### Completion method response types
+
+##### String
+
+A space separated string of possible values for the option
+
+##### Symbol
+
+Currently known symbols:
+
+* `:dirs` will complete directory names
+* `:files` will complete file names
+* `:hosts` will complete known host names
+
+##### Hash
+
+Much like the Symbols, but returned in Hash format to enable passing options:
+
+* `{ glob: '*.yml' }` will complete files endinging with `.yml`
+* `{ command: 'cut -d':' -f1 /etc/passwd' }` will run a command to get completion candidates, in this case the usernames from `/etc/password`
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/clamp-completer.

data/clamp-completer.gemspec

@@ -0,0 +1,24 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "clamp/completer/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "clamp-completer"
+  spec.version       = Clamp::Completer::VERSION
+  spec.authors       = ["Kontena, Inc"]
+  spec.email         = ["info@kontena.io"]
+
+  spec.summary       = %q{Automatically generate shell auto-completion scripts for clamp based cli tools}
+  spec.homepage      = "https://github.com/kontena/clamp-completer"
+
+  spec.files         = Dir["lib/**/*.{rb,erb}", "README.md", "LICENSE", "clamp-completer.gemspec"]
+
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "clamp"
+
+  spec.add_development_dependency "bundler", ">= 1.17"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rubocop", "~> 0.62"
+end

data/lib/clamp/completer.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "clamp/completer/version"
+require 'shellwords'
+
+module Clamp
+  module Completer
+    module Builder
+      autoload :ERB, 'erb'
+      autoload :OpenStruct, 'ostruct'
+
+      class Iterator
+        def initialize(root)
+          @root = root
+        end
+
+        def recurse(base = [], &block)
+          if @root.has_subcommands?
+            @root.recognised_subcommands.each do |sc|
+              sc.names.each do |name|
+                Iterator.new(sc.subcommand_class).recurse(base + [name], &block)
+              end
+            end
+          end
+          yield(base, @root) unless base.empty?
+        end
+      end
+
+      def root
+        self.class.root_command
+      end
+
+      def template_path(shell_name)
+        File.join(__dir__, 'completer', 'templates', "#{shell_name}.sh.erb")
+      end
+
+      def wrapper
+        klass = Class.new(self.class)
+        klass.subcommand(File.basename($PROGRAM_NAME), root.description || "main", root)
+        klass
+      end
+
+      def execute
+        template_file = template_path(shell)
+        unless File.exist?(template_file)
+          warn "Completion generation is not supported for #{shell}, defaulting to bash"
+          template_file = template_path("bash")
+        end
+
+        puts ERB.new(File.read(template_file), nil, '%-').tap { |e| e.location = [template_file, nil] }.result(
+          OpenStruct.new(progname: File.basename($PROGRAM_NAME), iterator: Iterator.new(wrapper)).instance_eval { binding }
+        )
+      end
+    end
+
+    def self.new(root_command, inherit_from: Clamp::Command)
+      @klass = Class.new(inherit_from) do
+        include Builder
+
+        class << self
+          attr_accessor :root_command
+        end
+      end
+
+      @klass.parameter('[SHELL]', 'shell', environment_variable: 'SHELL', default: 'bash') do |shell|
+        File.basename(shell)
+      end
+
+      @klass.root_command = root_command
+
+      @klass.banner("To load, use: source <(#{File.basename($PROGRAM_NAME)} complete #{@klass.usage_descriptions.join(' ')})")
+      @klass
+    end
+  end
+end

data/lib/clamp/completer/templates/bash.sh.erb

@@ -0,0 +1,92 @@
+_clamp_completer_<%= progname %>_current_subcommand() {
+  local ret="_${COMP_WORDS[0]}"
+  for ((i=1; i<$COMP_CWORD; i++)); do
+    if [[ ! $COMP_WORDS[$i] == -* ]]; then
+      declare -fF -- "${ret}_${COMP_WORDS[$i]}" >/dev/null && ret="${ret}_${COMP_WORDS[$i]}"
+    fi
+  done
+
+  if [ -n "$ret" ]; then
+    RET="${ret}"
+    return 0
+  else
+    return 1
+  fi
+}
+
+_clamp_completer_<%= progname %>_nospace() {
+  command -v compopt &> /dev/null && compopt -o nospace
+}
+
+<%- iterator.recurse do |invocation_path, command_class| -%>
+_<%= invocation_path.join('_') %>() {
+  local cur prev subcmd
+  COMPREPLY=()
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+  _clamp_completer_<%= progname %>_current_subcommand && subcmd="$RET"
+
+  if [ "$subcmd" = "${FUNCNAME[0]}${funcstack[1]}" ]; then
+    <%- visible_opts = command_class.recognised_options.reject(&:hidden?) -%>
+    if [[ ${cur} == -* ]] ; then
+      COMPREPLY=( $(compgen -W "<%= visible_opts.map(&:long_switch).join(' ') %>" -- ${cur}) )
+      return 0
+    fi
+
+    <%- visible_non_flag_opts = visible_opts.reject { |o| o.type == :flag } -%>
+    <%- unless visible_non_flag_opts.empty? -%>
+    <%- instance = command_class.new(invocation_path) -%>
+    case "$prev" in
+      <%- visible_non_flag_opts.each do |option| -%>
+      <%= option.switches.join('|') %>)
+       COMPREPLY=()
+        <%- if instance.respond_to?("complete_#{option.attribute_name}")
+              reply = instance.send("complete_#{option.attribute_name}")
+            else
+              cleaned_type = "complete_#{option.type.downcase.delete_prefix('[').split(' ').first}"
+              if instance.respond_to?(cleaned_type)
+                reply = instance.send(cleaned_type)
+              end
+            end -%>
+       <%- [reply].compact.each do |reply| -%>
+       <%= case reply
+          when String
+            "COMPREPLY+=( $(compgen -W \"#{reply}\" -- \"${cur}\") );"
+          when Symbol
+            case reply
+            when :dirs
+              "COMPREPLY+=( $(compgen -o nospace -d -S \"/\"  -- \"${cur}\") ); _clamp_completer_#{ progname }_nospace;"
+            when :hosts
+              "COMPREPLY+=( $(compgen -A hostname -- \"${cur}\") );"
+            when :files
+              "COMPREPLY+=( $(compgen -o filenames -f -- \"${cur}\") );"
+            end
+          when Hash
+            case reply.first.first
+            when :glob
+              "COMPREPLY+=( $(compgen -o filenames -f -G \"#{reply.first.last}\" -- \"${cur}\") );"
+            when :command
+              "COMPREPLY+=( $(compgen -C \"#{reply.first.last}\" -- \"${cur}\") );"
+            end
+          else
+            "COMPREPLY+=( $(compgen -o bashdefault -- \"${cur}\") );"
+          end %>
+        <%- end -%>
+        return 0
+        ;;
+      <%- end -%>
+    esac
+    <%- end -%>
+
+    <%- if command_class.has_subcommands? -%>
+    COMPREPLY=( $(compgen -W "<%= command_class.recognised_subcommands.flat_map(&:names).join(' ') %>" -- ${cur}) )
+    <%- else -%>
+    COMPREPLY=()
+    <%- end -%>
+  elif [ -n "$subcmd" ]; then
+    eval "$subcmd"
+  fi
+}
+
+<%- end -%>
+complete -F _<%= progname %> <%= progname %>

data/lib/clamp/completer/templates/zsh.sh.erb

@@ -0,0 +1,94 @@
+#compdef <%= progname %>
+
+<%- iterator.recurse do |invocation_path, command_class| -%>
+<%- if command_class.has_subcommands? -%>
+_<%= invocation_path.join('_') %>_subcommands() {
+  local subcommands=( <%= command_class.recognised_subcommands.map { |sc| "'#{sc.names.first}:#{sc.description.gsub(/'\$\\/, '\\\1') }'" }.join(' ') %> )
+  _describe 'subcommands' subcommands && return 0
+  return 1
+}
+
+<%- else -%>
+_<%= invocation_path.join('_') %>_subcommands() {
+  return 1
+}
+
+<%- end -%>
+
+_<%= invocation_path.join('_') %>() {
+  local curcontext="$curcontext" state state_descr line expl
+  local ret=1
+
+  _arguments -C : \
+    '1:subcommands:_<%= invocation_path.join('_') %>_subcommands' \
+    <%- command_class.recognised_options.each do |opt| -%>
+      <%- if opt.type == :flag -%>
+        <%- if opt.long_switch.include?('[no-]') -%>
+          '<%= opt.long_switch.gsub('[no-]', 'no-') %>[(disable) <%= opt.description.gsub(/\[|\]|:/, '\\\1') %>]' \
+          '<%= opt.long_switch.gsub('[no-]', '') %>[(enable) <%= opt.description.gsub(/\[|\]|:/, '\\\1') %>]' \
+        <%- else -%>
+          '<%= opt.long_switch %>[<%= opt.description.gsub(/\[|\]|:/, '\\\1') %>]' \
+        <%- end -%>
+      <%- else
+            instance = command_class.new(invocation_path)
+            if instance.respond_to?("complete_#{opt.attribute_name}")
+              reply = instance.send("complete_#{opt.attribute_name}")
+            else
+              cleaned_type = "complete_#{opt.type.downcase.delete_prefix('[').split(' ').first}"
+              if instance.respond_to?(cleaned_type)
+                reply = instance.send(cleaned_type)
+              end
+            end
+            result=[]
+            [reply].compact.each do |reply|
+            case reply
+            when String
+              result << "(#{reply})"
+            when Symbol
+              case reply
+              when :dirs
+                result << "_path_files -/"
+              when :hosts
+              when :files
+                result << "_path_files -f"
+              end
+            when Hash
+              case reply.first.first
+              when :glob
+                result << "_path_files -f -g \"#{reply.first.last}\""
+              when :command
+                result << "(${(k)commands})"
+              end
+            else
+            end
+        -%>
+        <%- if opt.long_switch.include?('[no-]') -%>
+          '<%= opt.long_switch.gsub('[no-]', 'no-') %>:(disable) <%= opt.description.gsub(/\[|\]|:/, '\\\1') %>:<%= result.first %>' \
+          '<%= opt.long_switch.gsub('[no-]', '') %>:(enable) <%= opt.description.gsub(/\[|\]|:/, '\\\1') %>:<%= result.first %>' \
+        <%- else -%>
+          '<%= opt.long_switch %>:<%= opt.description.gsub(/\[|\]|:/, '\\\1') %>:<%= result.first %>' \
+        <%- end -%>
+        <%- end -%>
+        <%- end -%>
+        <%- end -%>
+    '*::options:->options' && return 0
+
+  case "$state" in
+    command) _<%= invocation_path.join('_') %>_subcommands && return 0 ;;
+    options)
+      local command="${line[1]}"
+      curcontext="${curcontext%:*:*}:<%= invocation_path.join('-') %>-${command}"
+
+      line=(${line:1})
+      local completion_func="_<%= invocation_path.join('_') %>_${command//-/_}"
+      _call_function ret "${completion_func}" && return ret
+
+      _message "a completion function is not defined for ${command}"
+      return 1
+    ;;
+  esac
+}
+
+<%- end -%>
+
+compdef _<%= progname %> <%= progname %>

data/lib/clamp/completer/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Clamp
+  module Completer
+    VERSION = "0.1.0"
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: clamp-completer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kontena, Inc
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-01-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: clamp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.62'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.62'
+description: 
+email:
+- info@kontena.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- clamp-completer.gemspec
+- lib/clamp/completer.rb
+- lib/clamp/completer/templates/bash.sh.erb
+- lib/clamp/completer/templates/zsh.sh.erb
+- lib/clamp/completer/version.rb
+homepage: https://github.com/kontena/clamp-completer
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.2
+signing_key: 
+specification_version: 4
+summary: Automatically generate shell auto-completion scripts for clamp based cli
+  tools
+test_files: []