command_kit 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a35e836c936c91aa916f33e691260a591d2e363de6a0fd3d9259150b86add15
-  data.tar.gz: fe2e2cc87a8a0fe889cba23b5567b307bb088fdf3ee4eff7d681694a981b5143
+  metadata.gz: 5f815869f166ce21da0c32699e8dcd7cebdb17cdbcc74fba1be3572ebb2d15a0
+  data.tar.gz: 2e2db9a8f190308d473959274dad507095baba55e0e73f7fcd969a4f23267054
 SHA512:
-  metadata.gz: da2676ab635edc9898457b1c532af6ac4c478c6f3a0ab19dfc42f0abc4ddd73ef4f473fe7699f8bed3ac5abec3381a7a9ca9c50736c4cc3697612ef36f3d6fea
-  data.tar.gz: d30a04ab5274f489ef3e534950301669d47112ee56d43b59e51c5e816f7de21fba72197d43f3362331c40f3e75a70e0c316d53fe12bf8960daf79efec270a372
+  metadata.gz: b0055ba75d1dc4aef15bf280ed86f5d4a514e5e95c00bc1285c9f29327d5b03ab4415a6001bc4ee05be04bb5504b2d6a0a8de0d33f6048a1ea333adb93915f54
+  data.tar.gz: a198cc0fe966abb5f20f5025b52144bce290d06602e93afd13e2eca03d8aa87477511a598562f023ef921490084c200896c453e78b75d9061216dc8e548f923b

data/ChangeLog.md

@@ -1,3 +1,9 @@
+### 0.5.0 / 2024-01-04
+
+* Added {CommandKit::Env::Shell}.
+* Added {CommandKit::Env::Prefix}.
+* Added {CommandKit::Completion::Install}.
+
 ### 0.4.1 / 2024-01-03
 
 * Added more examples of how to define sub-commands and sub-sub-commands.

data/README.md

@@ -214,11 +214,14 @@ end
 * [CommandKit::Commands](https://rubydoc.info/gems/command_kit/CommandKit/Commands)
   * [CommandKit::Commands::AutoLoad](https://rubydoc.info/gems/command_kit/CommandKit/Commands/AutoLoad)
   * [CommandKit::Commands::AutoRequire](https://rubydoc.info/gems/command_kit/CommandKit/Commands/AutoRequire)
+* [CommandKit::Completion::Install](https://rubydoc.info/gems/command_kit/CommandKit/Completion/Install)
 * [CommandKit::Description](https://rubydoc.info/gems/command_kit/CommandKit/Description)
 * [CommandKit::Edit](https://rubydoc.info/gems/command_kit/CommandKit/Edit)
 * [CommandKit::Env](https://rubydoc.info/gems/command_kit/CommandKit/Env)
   * [CommandKit::Env::Home](https://rubydoc.info/gems/command_kit/CommandKit/Env/Home)
   * [CommandKit::Env::Path](https://rubydoc.info/gems/command_kit/CommandKit/Env/Path)
+  * [CommandKit::Env::Prefix](https://rubydoc.info/gems/command_kit/CommandKit/Env/Prefix)
+  * [CommandKit::Env::Shell](https://rubydoc.info/gems/command_kit/CommandKit/Env/Shell)
 * [CommandKit::Examples](https://rubydoc.info/gems/command_kit/CommandKit/Examples)
 * [CommandKit::ExceptionHandler](https://rubydoc.info/gems/command_kit/CommandKit/ExceptionHandler)
 * [CommandKit::FileUtils](https://rubydoc.info/gems/command_kit/CommandKit/FileUtils)

data/command_kit.gemspec

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'yaml'
 
 Gem::Specification.new do |gem|
@@ -20,12 +22,15 @@ Gem::Specification.new do |gem|
   gem.homepage    = gemspec['homepage']
   gem.metadata    = gemspec['metadata'] if gemspec['metadata']
 
-  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+  glob = ->(patterns) { gem.files & Dir[*patterns] }
 
   gem.files = if gemspec['files'] then glob[gemspec['files']]
               else                     `git ls-files`.split($/)
               end
 
+  # exclude test files from the packages gem
+  gem.files -= glob[gemspec['test_files'] || 'spec/{**/}*']
+
   gem.executables = gemspec.fetch('executables') do
     glob['bin/*'].map { |path| File.basename(path) }
   end
@@ -43,7 +48,7 @@ Gem::Specification.new do |gem|
   gem.required_rubygems_version = gemspec['required_rubygems_version']
   gem.post_install_message      = gemspec['post_install_message']
 
-  split = lambda { |string| string.split(/,\s*/) }
+  split = ->(string) { string.split(/,\s*/) }
 
   if gemspec['dependencies']
     gemspec['dependencies'].each do |name,versions|

data/lib/command_kit/completion/install.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require 'command_kit/printing'
+require 'command_kit/env/home'
+require 'command_kit/env/shell'
+require 'command_kit/env/prefix'
+require 'fileutils'
+
+module CommandKit
+  module Completion
+    #
+    # Mixins that adds methods for installing shell completion files.
+    #
+    # ## Environment Variables
+    #
+    # * `SHELL` - The current shell.
+    # * `PREFIX` - The optional root prefix of the file-system.
+    #
+    # @api public
+    #
+    # @since 0.5.0
+    #
+    module Install
+      include Printing
+      include Env::Home
+      include Env::Shell
+      include Env::Prefix
+
+      # The installation directory for completion files for the current shell.
+      #
+      # @return [String, nil]
+      #   * Bash
+      #     * Regular users: `~/.local/share/bash-completion/completions`
+      #     * Root users:`$PREFIX/usr/local/share/bash-completion/completions`
+      #   * Zsh: `$PREFIX/usr/local/share/zsh/site-functions`
+      #   * Fish:
+      #     * Regular users: `~/.config/fish/completions`
+      #     * Root users: `$PREFIX/usr/local/share/fish/completions`
+      #
+      # @api private
+      attr_reader :completions_dir
+
+      #
+      # Initialize {#completions_dir} based on the `SHELL` environment variable
+      # and the UID of the process.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments.
+      #
+      # @api public
+      #
+      def initialize(**kwargs)
+        super(**kwargs)
+
+        @completions_dir = case shell_type
+                           when :bash
+                             if Process.uid == 0
+                               File.join(root,'usr','local','share','bash-completion','completions')
+                             else
+                               xdg_data_home = env.fetch('XDG_DATA_HOME') do
+                                 File.join(home_dir,'.local','share')
+                               end
+
+                               File.join(xdg_data_home,'bash-completion','completions')
+                             end
+                           when :zsh
+                             File.join(root,'usr','local','share','zsh','site-functions')
+                           when :fish
+                             if Process.uid == 0
+                               File.join(root,'usr','local','share','fish','completions')
+                             else
+                               xdg_config_home = env.fetch('XDG_CONFIG_HOME') do
+                                 File.join(home_dir,'.config')
+                               end
+
+                               File.join(xdg_config_home,'fish','completions')
+                             end
+                           end
+      end
+
+      #
+      # Prints the shell completion file to stdout.
+      #
+      # @param [String] path
+      #   The path to the shell completion file.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments.
+      #
+      # @option kwargs [:bash, :zsh, :fish] :type (:bash)
+      #   The type of the completion file.
+      #
+      # @example Prints a Bash completion file:
+      #   print_completion_file 'path/to/completions/foo'
+      #
+      # @example Prints a Zsh completion file:
+      #   print_completion_file 'path/to/completions/foo', type: :zsh
+      #
+      # @example Prints a Fish completion file:
+      #   print_completion_file 'path/to/completions/foo', type: :fish
+      #
+      # @api public
+      #
+      def print_completion_file(path,**kwargs)
+        write_completion_file(path,stdout,**kwargs)
+      end
+
+      #
+      # Installs the shell completion file into {#completions_dir}.
+      #
+      # @param [String] path
+      #   The path to the shell completion file.
+      #
+      # @param [:bash, :zsh, :fish] type
+      #   The type of the shell completion file.
+      #
+      # @example Install a Bash completion file:
+      #   install_completion_file 'path/to/completions/foo'
+      #
+      # @example Install a Zsh completion file:
+      #   install_completion_file 'path/to/completions/foo', type: :zsh
+      #
+      # @example Install a Fish completion file:
+      #   install_completion_file 'path/to/completions/foo', type: :fish
+      #
+      # @api public
+      #
+      def install_completion_file(path, type: :bash)
+        completion_file = normalize_completion_file(path, type: type)
+        completion_path = File.join(@completions_dir,completion_file)
+
+        begin
+          ::FileUtils.mkdir_p(@completions_dir)
+        rescue Errno::EACCES
+          print_error "cannot write to #{shell_type} completions directory: #{@completions_dir}"
+          exit(-1)
+        end
+
+        begin
+          File.open(completion_path,'w') do |output|
+            write_completion_file(path,output, type: type)
+          end
+        rescue Errno::EACCES
+          print_error "cannot write to #{shell_type} completion file: #{completion_path}"
+          exit(-1)
+        end
+      end
+
+      #
+      # Uninstalls a shell completion file for the specified command.
+      #
+      # @param [String] command
+      #   The command to uninstall the completions for.
+      #
+      # @example Removes the completion file for the command 'foo':
+      #   uninstall_completion_file_for 'foo'
+      #
+      # @api public
+      #
+      def uninstall_completion_file_for(command)
+        completion_file = completion_file_for_command(command)
+        completion_path = File.join(@completions_dir,completion_file)
+
+        begin
+          ::FileUtils.rm_f(completion_path)
+        rescue Errno::EACCES
+          print_error "cannot remove #{shell_type} completion file: #{completion_path}"
+          exit(-1)
+        end
+      end
+
+      private
+
+      #
+      # Calculates the installed completion file for the given command.
+      #
+      # @param [String] command
+      #   The command name.
+      #
+      # @return [String]
+      #   The path to the completion file for the command.
+      #
+      # @api private
+      #
+      def completion_file_for_command(command)
+        case shell_type
+        when :bash then command
+        when :zsh  then "_#{command}"
+        when :fish then "#{command}.fish"
+        when nil
+          if shell then print_error("cannot identify shell: #{shell}")
+          else          print_error("cannot identify shell")
+          end
+
+          exit(-1)
+        else
+          print_error("completions not support for the #{shell_type} shell: #{shell}")
+          exit(-1)
+        end
+      end
+
+      #
+      # Calculates the installation path for the given completion file.
+      #
+      # @param [String] path
+      #   The path to the completion file that will be installed.
+      #
+      # @param [:bash, :zsh, :fish] type
+      #   The type of the shell completion file.
+      #
+      # @return [String]
+      #   The installation path for the completion file.
+      #
+      # @api private
+      #
+      def normalize_completion_file(path, type: :bash)
+        ext  = File.extname(path)
+        file = File.basename(path,ext)
+
+        case [shell_type, type]
+        when [:bash, :bash] # no-op
+        when [:zsh, :zsh],
+             [:zsh, :bash]
+          unless file.start_with?('_')
+            file = "_#{file}"
+          end
+        when [:fish, :fish]
+          file = "#{file}.fish"
+        else
+          if shell_type
+            print_error("cannot install #{type} completion file into the #{shell_type} shell: #{path}")
+          elsif shell
+            print_error("cannot identify shell: #{shell}")
+          else
+            print_error("cannot identify shell")
+          end
+
+          exit(-1)
+        end
+
+        return file
+      end
+
+      #
+      # Writes the shell completion file to the output
+      #
+      # @param [String] path
+      #   The path to the shell completion file.
+      #
+      # @param [IO] output
+      #   The output stream to write to.
+      #
+      # @param [:bash, :zsh, :fish] type
+      #   The type of the shell completion file.
+      #
+      # @api private
+      #
+      def write_completion_file(path,output, type: :bash)
+        if shell_type == :zsh && type == :bash
+          file_name = File.basename(path,File.extname(path))
+          command   = file_name.sub(/\A_/,'')
+
+          # add the #compdef magic comments for zsh
+          output.puts "#compdef #{command}"
+          output.puts
+        end
+
+        File.open(path) do |file|
+          file.each_line do |line|
+            output.write(line)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/command_kit/env/prefix.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'command_kit/env'
+
+module CommandKit
+  module Env
+    #
+    # Methods related to the `PREFIX` environment variable.
+    #
+    # ## Environment Variables
+    #
+    # * `PREFIX` - The optional root prefix of the file-system.
+    #
+    # @since 0.5.0
+    #
+    module Prefix
+      include Env
+
+      # The root of the file-system.
+      #
+      # @return [String]
+      #   The `PREFIX` environment variable, or `/` if no `PREFIX` environment
+      #   variable is given.
+      attr_reader :root
+
+      #
+      # Initialize {#root} based on the `PREFIX` environment
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments.
+      #
+      # @api public
+      #
+      def initialize(**kwargs)
+        super(**kwargs)
+
+        @root = env.fetch('PREFIX','/')
+      end
+    end
+  end
+end

data/lib/command_kit/env/shell.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'command_kit/env'
+
+module CommandKit
+  module Env
+    #
+    # Methods related to the `SHELL` environment variable.
+    #
+    # ## Environment Variables
+    #
+    # * `SHELL` - The current shell.
+    #
+    # @since 0.5.0
+    #
+    module Shell
+      include Env
+
+      # The current shell.
+      #
+      # @return [String, nil]
+      attr_reader :shell
+
+      # The current shell type.
+      #
+      # @return [:bash, :zsh, :fish, :dash, :mksh, :ksh, :tcsh, :csh, :sh, nil]
+      attr_reader :shell_type
+
+      #
+      # Initialize {#shell} and {#shell_type} based on the `SHELL` environment
+      # variable.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments.
+      #
+      # @api public
+      #
+      def initialize(**kwargs)
+        super(**kwargs)
+
+        @shell      = env['SHELL']
+        @shell_type = if @shell
+                        case File.basename(@shell)
+                        when /bash/ then :bash
+                        when /zsh/  then :zsh
+                        when /fish/ then :fish
+                        when /dash/ then :dash
+                        when /mksh/ then :mksh
+                        when /ksh/  then :ksh
+                        when /tcsh/ then :tcsh
+                        when /csh/  then :csh
+                        when /sh/   then :sh
+                        end
+                      end
+      end
+    end
+  end
+end

data/lib/command_kit/version.rb

@@ -1,4 +1,4 @@
 module CommandKit
   # command_kit version
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: command_kit
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Postmodern
@@ -73,11 +73,14 @@ files:
 - lib/command_kit/commands/help.rb
 - lib/command_kit/commands/parent_command.rb
 - lib/command_kit/commands/subcommand.rb
+- lib/command_kit/completion/install.rb
 - lib/command_kit/description.rb
 - lib/command_kit/edit.rb
 - lib/command_kit/env.rb
 - lib/command_kit/env/home.rb
 - lib/command_kit/env/path.rb
+- lib/command_kit/env/prefix.rb
+- lib/command_kit/env/shell.rb
 - lib/command_kit/examples.rb
 - lib/command_kit/exception_handler.rb
 - lib/command_kit/file_utils.rb
@@ -117,69 +120,6 @@ files:
 - lib/command_kit/usage.rb
 - lib/command_kit/version.rb
 - lib/command_kit/xdg.rb
-- spec/arguments/argument_spec.rb
-- spec/arguments/argument_value_spec.rb
-- spec/arguments_spec.rb
-- spec/bug_report_spec.rb
-- spec/colors_spec.rb
-- spec/command_kit_spec.rb
-- spec/command_name_spec.rb
-- spec/command_spec.rb
-- spec/commands/auto_load/subcommand_spec.rb
-- spec/commands/auto_load_spec.rb
-- spec/commands/auto_require_spec.rb
-- spec/commands/fixtures/test_auto_load/cli/commands/test1.rb
-- spec/commands/fixtures/test_auto_load/cli/commands/test2.rb
-- spec/commands/fixtures/test_auto_require/lib/test_auto_require/cli/commands/test1.rb
-- spec/commands/help_spec.rb
-- spec/commands/parent_command_spec.rb
-- spec/commands/subcommand_spec.rb
-- spec/commands_spec.rb
-- spec/description_spec.rb
-- spec/edit_spec.rb
-- spec/env/home_spec.rb
-- spec/env/path_spec.rb
-- spec/env_spec.rb
-- spec/examples_spec.rb
-- spec/exception_handler_spec.rb
-- spec/file_utils_spec.rb
-- spec/fixtures/template.erb
-- spec/help/man_spec.rb
-- spec/help_spec.rb
-- spec/inflector_spec.rb
-- spec/interactive_spec.rb
-- spec/main_spec.rb
-- spec/man_spec.rb
-- spec/open_app_spec.rb
-- spec/options/option_spec.rb
-- spec/options/option_value_spec.rb
-- spec/options/parser_spec.rb
-- spec/options/quiet_spec.rb
-- spec/options/verbose_spec.rb
-- spec/options/version_spec.rb
-- spec/options_spec.rb
-- spec/os/linux_spec.rb
-- spec/os_spec.rb
-- spec/package_manager_spec.rb
-- spec/pager_spec.rb
-- spec/printing/fields_spec.rb
-- spec/printing/indent_spec.rb
-- spec/printing/lists_spec.rb
-- spec/printing/tables/border_style.rb
-- spec/printing/tables/cell_builer_spec.rb
-- spec/printing/tables/row_builder_spec.rb
-- spec/printing/tables/style_spec.rb
-- spec/printing/tables/table_builder_spec.rb
-- spec/printing/tables/table_formatter_spec.rb
-- spec/printing/tables_spec.rb
-- spec/printing_spec.rb
-- spec/program_name_spec.rb
-- spec/spec_helper.rb
-- spec/stdio_spec.rb
-- spec/sudo_spec.rb
-- spec/terminal_spec.rb
-- spec/usage_spec.rb
-- spec/xdg_spec.rb
 homepage: https://github.com/postmodern/command_kit.rb#readme
 licenses:
 - MIT

data/spec/arguments/argument_spec.rb

@@ -1,133 +0,0 @@
-require 'spec_helper'
-require 'command_kit/arguments/argument'
-
-describe CommandKit::Arguments::Argument do
-  let(:name)     { :foo }
-  let(:usage)    { 'FOO' }
-  let(:required) { true }
-  let(:repeats)  { false }
-  let(:desc)     { 'Foo argument' }
-
-  subject do
-    described_class.new name, usage:    usage,
-                              required: required,
-                              repeats:  repeats,
-                              desc:     desc
-  end
-
-  describe "#initialize" do
-    context "when the usage: keyword is given" do
-      subject { described_class.new(name, usage: usage, desc: desc) }
-
-      it "must include usage: in #usage" do
-        expect(subject.usage).to include(usage)
-      end
-    end
-
-    context "when the usage: keyword is not given" do
-      subject { described_class.new(name, desc: desc) }
-
-      it "should use uppercased argument name in #usage" do
-        expect(subject.usage).to include(name.to_s.upcase)
-      end
-    end
-
-    context "when the required: keyword is given" do
-      subject { described_class.new(name, required: required, desc: desc) }
-
-      it "must set #required" do
-        expect(subject.required).to eq(required)
-      end
-    end
-
-    context "when the required: keyword is not given" do
-      subject { described_class.new(name, desc: desc) }
-
-      it "default #required to String" do
-        expect(subject.required).to eq(true)
-      end
-    end
-
-    context "when the repeats: keyword is given" do
-      subject { described_class.new(name, repeats: repeats, desc: desc) }
-
-      it "must set #repeats" do
-        expect(subject.repeats?).to eq(repeats)
-      end
-    end
-
-    context "when the repeats: keyword is not given" do
-      subject { described_class.new(name, desc: desc) }
-
-      it "default #repeats to String" do
-        expect(subject.repeats?).to eq(false)
-      end
-    end
-
-    context "when the desc: keyword is given" do
-      subject { described_class.new(name, desc: desc) }
-
-      it "must set #desc" do
-        expect(subject.desc).to eq(desc)
-      end
-    end
-
-    context "when the desc: keyword is not given" do
-      it do
-        expect {
-          described_class.new(name)
-        }.to raise_error(ArgumentError)
-      end
-    end
-  end
-
-  describe "#repeats?" do
-    context "when initialized with repeats: true" do
-      let(:repeats) { true }
-
-      it { expect(subject.repeats?).to be(true) }
-    end
-
-    context "when initialized with repeats: false" do
-      let(:repeats) { false }
-
-      it { expect(subject.repeats?).to be(false) }
-    end
-  end
-
-  describe "#usage" do
-    let(:usage) { 'FOO' }
-
-    context "initialized with required: true" do
-      let(:required) { true }
-
-      it "must return the usage unchanged" do
-        expect(subject.usage).to eq(usage)
-      end
-    end
-
-    context "initialized with required: false" do
-      let(:required) { false }
-
-      it "must wrap the usage in [ ] brackets" do
-        expect(subject.usage).to eq("[#{usage}]")
-      end
-    end
-
-    context "initialized with repeats: true" do
-      let(:repeats) { true }
-
-      it "must append the ... ellipses" do
-        expect(subject.usage).to eq("#{usage} ...")
-      end
-    end
-
-    context "initialized with repeats: false" do
-      let(:repeats) { false }
-
-      it "must return the usage name unchanged" do
-        expect(subject.usage).to eq(usage)
-      end
-    end
-  end
-end