command_kit-completion 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f85e448a2df37a8bc6231b839b8e56992432498384e6ea4c2e1060a9485c874
-  data.tar.gz: 898168ab4ed70e3e595de27c933432a085976ea81980c7bcc3572e6e2cc4c38c
+  metadata.gz: 721a31416806fcf1375dfa9060827013fbde3ffc06f0d9916f31c5602d4386f7
+  data.tar.gz: e6bb27f5dd650bfb26b9fda270bb66a97c7c260cbaa45b3a520a93aa53594567
 SHA512:
-  metadata.gz: 45ceb26079e0d5caf31e94ea0851fc30e5175661491bed0d6da4f57feb3bc37352ef48e9f7d817f5dced1825db2aa94e0500387a8175dde6b805921c62453ab6
-  data.tar.gz: 8858593122d06c2e4fff8d5f78fae75cd8f23665732131d36eb2fd9c52a51e94a8aa5fe3920b5b622a4f03a16360f442b79e6fd5a9b1c96cf78389c1871a6872
+  metadata.gz: 6e9820c5f5ae32b4f9672d9b05bec71b86e0a66a9a8ae873e74346d65fe2d5b8d37c205921689d7c842d30e1d8411328fc5181da61b57abe71fbd31518485229
+  data.tar.gz: 855fd91e1a677a359f62f1ebcc38350e6308e5451cfa7d69dea172ec3d88c015a2323e1b7d6559f64cd6667bd1c5ac2489d62644523e39bf80f8a2628bd64621

data/.github/workflows/ruby.yml

@@ -9,9 +9,10 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
-          - 3.0
-          - 3.1
-          - 3.2
+          - '3.0'
+          - '3.1'
+          - '3.2'
+          - '3.3'
           - jruby
           - truffleruby
     name: OS ${{ matrix.os }} / Ruby ${{ matrix.ruby }}

data/ChangeLog.md

@@ -1,3 +1,13 @@
+### 0.3.0 / 2024-12-16
+
+* Generate `<file>` and `<directory>` completion rules for arguments named
+  `PATH` or ending in `_PATH`, so they can tab complete both files and
+  directories.
+
+### 0.2.1 / 2024-04-29
+
+* Support loading YAML input files that contain YAML aliases.
+
 ### 0.2.0 / 2024-04-26
 
 * Also generate completion rules for option's short flags.

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2023 Hal Brodigan
+Copyright (c) 2023-2024 Hal Brodigan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -45,7 +45,7 @@ rake command_kit:completion
 
 ## License
 
-Copyright (c) 2023 Hal Brodigan
+Copyright (c) 2023-2024 Hal Brodigan
 
 See {file:LICENSE.txt} for details.
 

data/lib/command_kit/completion/task.rb

@@ -10,37 +10,61 @@ require 'fileutils'
 
 module CommandKit
   module Completion
+    #
+    # `command_kit-completion` rake task.
+    #
+    # ## Example
+    #
+    #     require 'command_kit/completion/task'
+    #     CommandKit::Completion::Task.new(
+    #       class_file:  './examples/cli',
+    #       class_name:  'Foo::CLI',
+    #       output_file: 'completion.sh'
+    #     )
+    #
     class Task < Rake::TaskLib
 
       # The file that the command_kit CLI is defined in.
       #
       # @return [String]
+      #
+      # @api private
       attr_reader :class_file
 
       # The class name of the command_kit CLI.
       #
       # @return [String]
+      #
+      # @api private
       attr_reader :class_name
 
       # The output file to write the shell completions to.
       #
       # @return [String]
+      #
+      # @api private
       attr_reader :output_file
 
       # Optional input YAML file to read additional shell completions from.
       #
       # @return [String, nil]
+      #
+      # @api private
       attr_reader :input_file
 
       # Specifies whether the shell completion logic should be wrapped in a
       # function.
       #
       # @return [Boolean]
+      #
+      # @api private
       attr_reader :wrap_function
 
       # Optional function name to wrap the shell completions within.
       #
       # @return [String, nil]
+      #
+      # @api private
       attr_reader :function_name
 
       #
@@ -61,6 +85,8 @@ module CommandKit
       #
       #   [completely examples]: https://github.com/DannyBen/completely?tab=readme-ov-file#using-the-completely-command-line
       #
+      # @api public
+      #
       def initialize(class_file: ,
                      class_name: ,
                      output_file: ,
@@ -81,6 +107,8 @@ module CommandKit
       #
       # Defines the `command_kit:completion` task.
       #
+      # @api private
+      #
       def define
         task(@output_file) do
           completions  = Completely::Completions.new(completion_rules)
@@ -105,28 +133,45 @@ module CommandKit
       #
       # @return [Class]
       #
+      # @api private
+      #
       def load_class
         require(@class_file)
         Object.const_get(@class_name)
       end
 
+      #
+      # Loads the completion rules from the {#input_file}.
+      #
+      # @return [Hash]
+      #   The completion rules from the {#input_file}.
+      #
+      # @api private
+      #
+      def load_input_file
+        YAML.load_file(@input_file, aliases: true)
+      end
+
       #
       # Maps the argument name strings to completely suggestion `<keyword>`s.
       #
       # @param [String] arg
       #   The argument name.
       #
-      # @return [String, nil]
+      # @return [Array<String>, nil]
       #   The suggestion keyword for the argument name.
       #
-      # @since 0.2.0
+      # @since 0.3.0
+      #
+      # @api private
       #
-      def suggestion_for_argument(arg)
+      def suggestions_for_argument(arg)
         case arg
-        when /\AFILE\z|_FILE\z/ then '<file>'
-        when /\ADIR\z|_DIR\z/   then '<directory>'
-        when /\AHOST\z|_HOST\z/ then '<hostname>'
-        when /\AUSER\z|_USER\z/ then '<user>'
+        when /\AFILE\z|_FILE\z/ then %w[<file>]
+        when /\ADIR\z|_DIR\z/   then %w[<directory>]
+        when /\APATH\z|_PATH\z/ then %w[<file> <directory>]
+        when /\AHOST\z|_HOST\z/ then %w[<hostname>]
+        when /\AUSER\z|_USER\z/ then %w[<user>]
         end
       end
 
@@ -142,6 +187,8 @@ module CommandKit
       # @return [Hash{String => Array<String>}]
       #   The completion rules for the command class and any sub-commands.
       #
+      # @api private
+      #
       def completion_rules_for(command_class)
         command_name = command_class.command_name
         completions  = {command_name => []}
@@ -154,16 +201,16 @@ module CommandKit
             completions[command_name] << option.short if option.short
 
             if option.value
-              if (suggestion = suggestion_for_argument(option.value.usage))
+              if (suggestions = suggestions_for_argument(option.value.usage))
                 command_pattern = "#{command_name}*#{option.long}"
 
                 # add a special rule if the option's value USAGE maps to a
                 # 'completely' completion keyword (ex: `FILE` -> `<file>`).
-                completions[command_pattern] = [suggestion]
+                completions[command_pattern] = suggestions
 
                 if option.short
                   # also add another rule with the option's short flag
-                  completions["#{command_name}*#{option.short}"] = [suggestion]
+                  completions["#{command_name}*#{option.short}"] = suggestions
                 end
               end
             end
@@ -185,9 +232,9 @@ module CommandKit
           completions[command_name].concat(command_class.command_aliases.keys)
         elsif command_class.include?(CommandKit::Arguments)
           if (argument = command_class.arguments.values.first)
-            if (suggestion = suggestion_for_argument(argument.usage))
+            if (suggestions = suggestions_for_argument(argument.usage))
               # add a suggestion for the first argument
-              completions[command_name] << suggestion
+              completions[command_name].concat(suggestions)
             end
           end
         end
@@ -206,12 +253,14 @@ module CommandKit
       #
       # @return [Hash{String => Array<String>}]
       #
+      # @api private
+      #
       def completion_rules
         completion_rules = completion_rules_for(load_class)
 
         if @input_file
           # load the additional rules from the input file
-          additional_completion_rules = YAML.load_file(@input_file)
+          additional_completion_rules = load_input_file
 
           # merge the additional completion rules
           additional_completion_rules.each do |command_string,completions|

data/lib/command_kit/completion/version.rb

@@ -3,6 +3,6 @@
 module CommandKit
   module Completion
     # command_kit-completion version
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/spec/fixtures/additional_rules_with_aliases.yml

@@ -0,0 +1,4 @@
+---
+foo update: &update
+  - $(foo list)
+foo up: *update

data/spec/task_spec.rb

@@ -69,6 +69,42 @@ describe CommandKit::Completion::Task do
     end
   end
 
+  describe "#load_input_file" do
+    let(:input_file) { File.join(fixtures_dir,'additional_rules.yml') }
+
+    subject do
+      described_class.new(
+        class_file:  class_file,
+        class_name:  class_name,
+        input_file:  input_file,
+        output_file: output_file
+      )
+    end
+
+    it "must load the YAML from the input file" do
+      expect(subject.load_input_file).to eq(
+        {
+          'foo update' => ['$(foo list)']
+        }
+      )
+    end
+
+    context "when the input file contains YAML aliases" do
+      let(:input_file) do
+        File.join(fixtures_dir,'additional_rules_with_aliases.yml')
+      end
+
+      it "must support parsing YAML aliases" do
+        expect(subject.load_input_file).to eq(
+          {
+            'foo update' => ['$(foo list)'],
+            'foo up'=> ['$(foo list)']
+          }
+        )
+      end
+    end
+  end
+
   describe "#completion_rules_for" do
     context "when given a simple CommandKit::Command class" do
       class TestBasicCommand < CommandKit::Command
@@ -569,52 +605,90 @@ describe CommandKit::Completion::Task do
     end
   end
 
-  describe "#suggestion_for_argument" do
+  describe "#suggestions_for_argument" do
     context "when given 'FILE'" do
-      it "must return '<file>'" do
-        expect(subject.suggestion_for_argument('FILE')).to eq('<file>')
+      it "must return ['<file>']" do
+        expect(subject.suggestions_for_argument('FILE')).to eq(
+          %w[<file>]
+        )
       end
     end
 
     context "when the string ends with '_FILE'" do
-      it "must return '<file>'" do
-        expect(subject.suggestion_for_argument('FOO_FILE')).to eq('<file>')
+      it "must return ['<file>']" do
+        expect(subject.suggestions_for_argument('FOO_FILE')).to eq(
+          %w[<file>]
+        )
       end
     end
 
     context "when given 'DIR'" do
-      it "must return '<directory>'" do
-        expect(subject.suggestion_for_argument('DIR')).to eq('<directory>')
+      it "must return ['<directory>']" do
+        expect(subject.suggestions_for_argument('DIR')).to eq(
+          %w[<directory>]
+        )
       end
     end
 
     context "when the string ends with '_DIR'" do
-      it "must return '<directory>'" do
-        expect(subject.suggestion_for_argument('FOO_DIR')).to eq('<directory>')
+      it "must return ['<directory>']" do
+        expect(subject.suggestions_for_argument('FOO_DIR')).to eq(
+          %w[<directory>]
+        )
+      end
+    end
+
+    context "when given 'PATH'" do
+      it "must return ['<file>', '<directory>']" do
+        expect(subject.suggestions_for_argument('PATH')).to eq(
+          %w[
+            <file>
+            <directory>
+          ]
+        )
+      end
+    end
+
+    context "when the string ends with '_PATH'" do
+      it "must return ['<file>', '<directory>']" do
+        expect(subject.suggestions_for_argument('FOO_PATH')).to eq(
+          %w[
+            <file>
+            <directory>
+          ]
+        )
       end
     end
 
     context "when given 'HOST'" do
-      it "must return '<hostname>'" do
-        expect(subject.suggestion_for_argument('HOST')).to eq('<hostname>')
+      it "must return ['<hostname>']" do
+        expect(subject.suggestions_for_argument('HOST')).to eq(
+          %w[<hostname>]
+        )
       end
     end
 
     context "when the string ends with '_HOST'" do
-      it "must return '<hostname>'" do
-        expect(subject.suggestion_for_argument('FOO_HOST')).to eq('<hostname>')
+      it "must return ['<hostname>']" do
+        expect(subject.suggestions_for_argument('FOO_HOST')).to eq(
+          %w[<hostname>]
+        )
       end
     end
 
     context "when given 'USER'" do
-      it "must return '<user>'" do
-        expect(subject.suggestion_for_argument('USER')).to eq('<user>')
+      it "must return ['<user>']" do
+        expect(subject.suggestions_for_argument('USER')).to eq(
+          %w[<user>]
+        )
       end
     end
 
     context "when the string ends with '_USER'" do
-      it "must return '<user>'" do
-        expect(subject.suggestion_for_argument('FOO_USER')).to eq('<user>')
+      it "must return ['<user>']" do
+        expect(subject.suggestions_for_argument('FOO_USER')).to eq(
+          %w[<user>]
+        )
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_kit-completion
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Postmodern
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-27 00:00:00.000000000 Z
+date: 2024-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: command_kit
@@ -84,6 +84,7 @@ files:
 - lib/command_kit/completion/task.rb
 - lib/command_kit/completion/version.rb
 - spec/fixtures/additional_rules.yml
+- spec/fixtures/additional_rules_with_aliases.yml
 - spec/spec_helper.rb
 - spec/task_spec.rb
 homepage: https://github.com/postmodern/command_kit-completion#readme
@@ -110,7 +111,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Generate shell completions for command_kit commands