dry-cli-completion 0.3.0 → 0.9.0.pre.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb611ff121ae25f5f4b8cbe926d7742a28885e2408cabb2e589fce724d67b85c
-  data.tar.gz: '008ba658f43ec5177037e31f0bf4e78aafbfcbb866065e1cbd702117815495f3'
+  metadata.gz: f964195592d079499e1ac64d97966be5041cec718b12d7dbdcad3a13a78a987c
+  data.tar.gz: 19eb60e90e5d136ac43762f8c897b7f3b9d0197074e12c3a7237ad96230034e2
 SHA512:
-  metadata.gz: 9362523877d4147af5ffdbbb53a54158ffee4b2a5709c6e3aa854197da105f391861fd6daacd80bedf0d1b7b4fbb1cd520e9a5abb56cdc4dd83b384ba0d8504a
-  data.tar.gz: b5603912acb40ff3a2d4e0cdf2c8734a86cef9572139b9087e31d33e84d833bd081c47f7429716aa18a8a6ed0804780004234090eb82a68f4b28cbbad39ab976
+  metadata.gz: 85b055c56a7fd6c9752449275766126f57a51aa2a74e976246b62b25b4a7625cc858b794121d5443b03020cee8407cc00b4fdb79be1c3cbb8b7d738255d10dbf
+  data.tar.gz: 943acef312431e8176115bea9c3dcdbcef4960640eb409f391a731442b1098f7dbafb5562546c120e00f01524c4087d54b98cd505688923d5de3bcc3a18ff109

data/CHANGELOG.md

@@ -1,3 +1,5 @@
 # CHANGELOG
 
+## 0.9.0-alpha First full fledged Implementation
+
 ## 0.3.0 Inital Skeleton

data/Gemfile

@@ -7,3 +7,5 @@ gemspec
 
 gem "rspec", "~> 3.0"
 gem "standard"
+gem "dry-cli"
+gem "pry"

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Tobias Bielohlawek
+Copyright (c) 2022 Tobias Bielohlawek (rngtng)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,15 +1,15 @@
-# Dry::Cli::Completion
-
-Dry::CLI Command to generate a completion script for bash/zsh
+# Dry::CLI::Completion
 
 [![Gem Version](https://badge.fury.io/rb/dry-cli-completion.svg)](https://badge.fury.io/rb/dry-cli-completion)
 
-## About
+---
 
-Extension Command for Dry::CLI which generates a completion script for bash/zsh.
+[Dry::CLI](https://github.com/dry-rb/dry-cli) extension & drop-in Command to generate a completion
+script for bash/zsh. It heavily relies on the great work of https://github.com/dannyben/completely.
 
-## Installation
+---
 
+## Installation
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -25,18 +25,112 @@ Or install it yourself as:
     $ gem install dry-cli-completion
 
 ## Usage
+The gems architecture consits of three layers which each abstracts & simplifies the completion script generation and its usage:
 
-TODO: Write usage instructions here
+1. Command layer - drop-in dry-cli command to print the completion script for given shell
+2. Generator layer - the actual script generation leveraging [completely](https://github.com/dannyben/completely)
+3. Input layer - interspecting the dry-cli registry to extract each command with it options, arguements and aliases
 
-## Development
+### 1. Command layer
+Simplest usage is to drop in the `Dry::CLI::Completion::Command` to your existing registry:
+
+```ruby
+module MyRegistry
+  extend Dry::CLI::Registry
+
+   register "cmd1", MyCmd1
+   #....
+
+   register "completion", Dry::CLI::Completion::Command[self]
+  end
+end
+```
 
+This will extend your cli for a new command `completion` with following usage:
+
+```sh
+Usage:
+  foo-cli completion [SHELL]
+
+Description:
+  Print tab completion script for given shell
+
+Arguments:
+  SHELL                             # Shell for which to print the completion script: (bash/zsh)
+
+Options:
+  --[no-]include-aliases, -a        # Include command aliases when true, default: false
+  --help, -h                        # Print this help
+
+Examples:
+  foo-cli completion bash # Print tab completion script for bash
+  foo-cli completion zsh # Print tab completion script for zsh
+  foo-cli completion -a bash # Include command aliases for bash
+```
+
+### 2. Generator Layer
+In case you want to change/extend the completion script, create a custom command and leverage just the generator:
+
+```ruby
+class MyCommand < Dry::CLI::Command
+  desc "Custom completion script command"
+
+  def call(**)
+    script = Dry::CLI::Completion::Generator.new(MyRegistry).call(shell: "bash")
+    # ... further processing here ...
+    puts script
+  end
+end
+```
 
-For local development, this project comes with a Dockerimage and Makefile. After checking out the repo, run the following to enter development console:
+### 3. Input layer
+Lastly, if the script generation input needs to be adjusted, leverage the input layer. Here the commands, arguments, options and their values/types extracted and put in an input format for `completely`. See [completely Readme](https://github.com/dannyben/completely) for details.
 
+```ruby
+input = Dry::CLI::Completion::Input.new(MyRegistry, "foo").call(include_aliases: false)
+# ... further processing here ...
+puts Completely::Completions.new(input)
 ```
-make build dev
+
+## Development
+For local development, this project comes dockerized - with a Dockerimage and Makefile. After checking out the repo, run the following to enter development console:
+
+    $ make build dev
+
+With that, any dependencies are maintained and no ruby version manager is required.
+
+### Testing
+The gem comes with a full-fledged rspec testsuite. To execute all tests run in developer console:
+
+    $ rspec
+
+### Manual Testing
+The foo registry is used in unit test is available as `spec/foo-cli` for manual testing. First source the comepltion script:
+
+    $ source <(spec/foo-cli completion bash)
+
+Then try the tab completion yourself:
+
+```sh
+$ spec/foo-cli <tab>
+completion  echo        exec        help        start       stop        version
 ```
 
-Then, run `rake spec` to run the tests.
+### Linting
+For liniting, the gem leverages the [standard Readme](https://github.com/testdouble/standard)  and [rubocop](https://github.com/rubocop/rubocop) rules. To execute just run:
+
+    $ rubocop
+
+### Releasing
+To release a new version, update the version number in `version.rb`, push commits to GitHub and then create a release. This will create a git tag for the version, and push the `.gem` file to [rubygems.org](https://rubygems.org) as well as GitHub packages.
+See GitHub actions in `.github` for more.
+
+## Supported Ruby versions
+
+This library officially supports the following Ruby versions:
+
+* MRI `>= 2.7.0`
+
+## License
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+See `LICENSE` file.

data/dry-cli-completion.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "lib/dry/cli/completion/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "dry-cli-completion"
+  spec.version = Dry::CLI::Completion::VERSION
+  spec.authors = ["rngtng"]
+  spec.email = ["tobi@rngtng.com"]
+  spec.licenses = ["MIT"]
+
+  spec.summary = "Dry::CLI Command to generate a completion script for bash/zsh"
+  spec.description = "Extension Command for Dry::CLI which generates a completion script for bash/zsh."
+  spec.homepage = "https://github.com/rngtng/dry-cli-completion"
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => "https://github.com/rngtng/dry-cli-completion",
+    "changelog_uri" => "https://github.com/rngtng/dry-cli-completion/CHANGELOG.md",
+    "github_repo" => "ssh://github.com/rngtng/dry-cli-completion",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir["lib/**/*"] + %w[Gemfile LICENSE README.md CHANGELOG.md dry-cli-completion.gemspec]
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.7.6"
+
+  spec.add_dependency "completely", "~> 0.4"
+end

data/lib/dry/cli/completion/command.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "dry/cli/completion"
+
+module Dry
+  class CLI
+    module Completion
+      class Command < Dry::CLI::Command
+        desc "Print tab completion script for given shell"
+
+        example [
+          "bash # Print tab completion script for bash",
+          "zsh # Print tab completion script for zsh",
+          "-a bash # Include command aliases for bash"
+        ]
+
+        option :include_aliases, required: true, type: :boolean, default: false, aliases: ["a"],
+          desc: "Include command aliases when true"
+        argument :shell, required: false, type: :string, values: Dry::CLI::Completion::SUPPORTED_SHELLS,
+          desc: "Shell for which to print the completion script"
+
+        def call(shell:, include_aliases: false, **)
+          puts Generator.new(self.class.registry).call(
+            shell: shell,
+            include_aliases: include_aliases
+          )
+        end
+
+        def self.[](registry)
+          @registry = registry
+          self
+        end
+
+        class << self
+          attr_reader :registry
+        end
+      end
+    end
+  end
+end

data/lib/dry/cli/completion/generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "input"
+require "completely"
+
+module Dry
+  class CLI
+    module Completion
+      class Generator
+        def initialize(registry, program_name: nil)
+          @registry = registry
+          @program_name = program_name || Dry::CLI::ProgramName.call
+        end
+
+        def call(shell:, include_aliases: false, out: StringIO.new)
+          raise ArgumentError, "Unknown shell" unless SUPPORTED_SHELLS.include?(shell)
+          if shell == ZSH
+            out.puts "# enable bash completion support, see https://github.com/dannyben/completely#completions-in-zsh"
+            out.puts "autoload -Uz +X compinit && compinit"
+            out.puts "autoload -Uz +X bashcompinit && bashcompinit"
+          end
+
+          out.puts Completely::Completions.new(
+            Input.new(@registry, @program_name).call(include_aliases: include_aliases)
+          ).script
+          out.string
+        end
+      end
+    end
+  end
+end

data/lib/dry/cli/completion/input.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module Completion
+      class Input
+        def initialize(registry, program_name)
+          @registry = registry
+          @program_name = program_name
+        end
+
+        def call(include_aliases:)
+          nodes = root_node.children.dup
+          nodes.merge!(root_node.aliases.dup) if include_aliases
+
+          commands = nodes.each_with_object({}) do |(name, sub_node), hash|
+            next unless sub_node.command
+            hash[name] = command(sub_node.command, include_aliases: include_aliases)
+          end
+
+          commands.each_with_object({
+            @program_name => commands.keys + ["help"]
+          }) do |(name, config), input|
+            input_line(input, "#{@program_name} #{name}", config[:arguments].shift, config)
+          end
+        end
+
+        private
+
+        def root_node
+          @registry.get({}).instance_variable_get(:@node)
+        end
+
+        def command(command, include_aliases: false)
+          {
+            options: {
+              "--help" => []
+            },
+            arguments: command.arguments.map { |arg|
+              [arg.name, argument_values(arg)]
+            }
+          }.tap do |hash|
+            command.options.each do |opt|
+              hash[:options]["--#{opt.name}"] = option_values(opt)
+              next unless include_aliases
+              opt.aliases.each { |arg|
+                hash[:options]["-#{arg}"] = option_values(opt)
+              }
+            end
+          end
+        end
+
+        def argument_values(argument)
+          return ["<file>"] if argument.name.to_s.include?("path")
+          return argument.values if argument.values
+          nil
+        end
+
+        def option_values(option)
+          return ["<file>"] if option.name.to_s.include?("path")
+          return option.values if option.values
+          return [] if option.type != :boolean
+          nil
+        end
+
+        def input_line(input, name, argument, config)
+          return if name.include?("<file>")
+          if argument
+            arg_values = argument.last || []
+            input[name] = arg_values + config[:options].keys
+            argument = config[:arguments].shift
+            arg_values.each { |v| input_line(input, "#{name}*#{v}", argument, config) }
+          else
+            input[name] = config[:options].keys
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/cli/completion/version.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Dry
-  module Cli
+  class CLI
     module Completion
-      VERSION = "0.3.0"
+      VERSION = "0.9.0-alpha"
     end
   end
 end

data/lib/dry/cli/completion.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 require_relative "completion/version"
+require_relative "completion/generator"
 
 module Dry
-  module Cli
+  class CLI
     module Completion
-      class Error < StandardError; end
-      # Your code goes here...
+      SUPPORTED_SHELLS = [
+        BASH = "bash",
+        ZSH = "zsh"
+      ]
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dry-cli-completion
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.9.0.pre.alpha
 platform: ruby
 authors:
 - rngtng
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-24 00:00:00.000000000 Z
+date: 2022-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: completely
@@ -32,18 +32,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
-- ".rubocop.yml"
 - CHANGELOG.md
-- Dockerfile
 - Gemfile
 - LICENSE
-- Makefile
 - README.md
-- Rakefile
+- dry-cli-completion.gemspec
 - lib/dry/cli/completion.rb
+- lib/dry/cli/completion/command.rb
+- lib/dry/cli/completion/generator.rb
+- lib/dry/cli/completion/input.rb
 - lib/dry/cli/completion/version.rb
-- sig/dry/cli/completion.rbs
 homepage: https://github.com/rngtng/dry-cli-completion
 licenses:
 - MIT
@@ -51,6 +49,8 @@ metadata:
   homepage_uri: https://github.com/rngtng/dry-cli-completion
   source_code_uri: https://github.com/rngtng/dry-cli-completion
   changelog_uri: https://github.com/rngtng/dry-cli-completion/CHANGELOG.md
+  github_repo: ssh://github.com/rngtng/dry-cli-completion
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -62,9 +62,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.7.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.3.7
 signing_key: 

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,9 +0,0 @@
-require: standard
-
-inherit_gem:
-  standard: config/base.yml
-
-AllCops:
-  TargetRubyVersion: 2.7
-  Exclude:
-    - 'vendor/**/*'

data/Dockerfile

@@ -1,19 +0,0 @@
-FROM ruby:2.7-slim
-
-RUN set -ex \
-    && apt update \
-    && apt install -y --no-install-recommends build-essential git
-
-RUN mkdir /app
-
-# COPY Gemfile Gemfile.lock /app/
-
-WORKDIR /app
-# RUN bundle install
-# RUN bundle binstubs --all --path /bin
-
-COPY . /app
-
-ENV HISTCONTROL=ignoreboth:erasedups
-
-ENTRYPOINT ["bash"]

data/Makefile

@@ -1,20 +0,0 @@
-PROJECT     ?= rngtng/dry-cli-completion
-BUILD_TAG   ?= dev
-REGISTRY_TAG = $(PROJECT):$(BUILD_TAG)
-
-.PHONY: help # List all documented targets
-help:
-	@grep '^.PHONY: .* #' Makefile | sed 's/\.PHONY: \(.*\) # \(.*\)/\1 $(shell echo "\t") \2/' | sort | expand -t20
-
-.PHONY: build # Build docker image with `dev` tag
-build:
-	docker build -t $(REGISTRY_TAG) .
-
-.PHONY: test-gh-action # Test github actions locally with https://github.com/nektos/act
-test-gh-action:
-  echo '{ "inputs": { "tag": "0.1.0" } }' > /tmp/act.json
-	act --artifact-server-path /tmp/artifacts workflow_dispatch -e /tmp/act.json
-
-.PHONY: dev # Build docker image, run and ssh inside
-dev:
-	docker run --rm -it -v "$(shell pwd):/app" $(REGISTRY_TAG)

data/Rakefile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]

data/sig/dry/cli/completion.rbs

@@ -1,8 +0,0 @@
-module Dry
-  module Cli
-    module Completion
-      VERSION: String
-      # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-    end
-  end
-end