command_kit 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72a3fdeb65d9eb4c4e996aa95ea7e8131e220c2cb24be8b17d56e1742a156d35
-  data.tar.gz: d05b75366f58c219c9680d07571a171239f0ab8f77580cb1c2d47c6322d7e74c
+  metadata.gz: 5f815869f166ce21da0c32699e8dcd7cebdb17cdbcc74fba1be3572ebb2d15a0
+  data.tar.gz: 2e2db9a8f190308d473959274dad507095baba55e0e73f7fcd969a4f23267054
 SHA512:
-  metadata.gz: 1cc85835b40fded3170ee21619620dbb988dd3427fa8cb48456f09a7991b6eed72299a81ba19be543c260557504d5636237993f33360d463d72a87600ca14441
-  data.tar.gz: 9d57ec57d540547d2fa664faf8e3bb1e0c0aa06929162d3dac849f858911aa5e7610e8294b2189927d8633de8e9784079df548a3e900fd73c57f76e72c87ad9d
+  metadata.gz: b0055ba75d1dc4aef15bf280ed86f5d4a514e5e95c00bc1285c9f29327d5b03ab4415a6001bc4ee05be04bb5504b2d6a0a8de0d33f6048a1ea333adb93915f54
+  data.tar.gz: a198cc0fe966abb5f20f5025b52144bce290d06602e93afd13e2eca03d8aa87477511a598562f023ef921490084c200896c453e78b75d9061216dc8e548f923b

data/.github/workflows/ruby.yml

@@ -12,6 +12,8 @@ jobs:
         ruby:
           - '3.0'
           - '3.1'
+          - '3.2'
+          - '3.3'
           # TODO: uncomment when jruby supports ruby >= 2.7
           # - jruby
           - truffleruby

data/.rubocop.yml

@@ -152,3 +152,6 @@ Bundler/OrderedGems: { Enabled: false }
 Layout/SpaceInsideArrayLiteralBrackets: { Enabled: false }
 
 Naming/HeredocDelimiterNaming: { Enabled: false }
+
+# I prefer to use explicit parenthesis for compound logical statements
+Style/RedundantParentheses: { Enabled: false }

data/ChangeLog.md

@@ -1,3 +1,21 @@
+### 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.
+
+#### CommandKit::Options::Parser
+
+* Do not override the command's `usage` if it's already been set.
+
+#### CommandKit::Printing::Tables
+
+* Format the table output as UTF-8 to allow UTF-8 data in the formatted table.
+
 ### 0.4.0 / 2022-11-11
 
 * Added {CommandKit::BugReport}.

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2021-2022 Hal Brodigan
+Copyright (c) 2021-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

@@ -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)
@@ -253,7 +256,7 @@ Twitter.
 
 ## Copyright
 
-Copyright (c) 2021-2022 Hal Brodigan
+Copyright (c) 2021-2024 Hal Brodigan
 
 See {file:LICENSE.txt} for details.
 

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/examples/subcommands/cli/config/get.rb

@@ -0,0 +1,47 @@
+require 'command_kit/command'
+
+module Foo
+  class CLI
+    class Config < CommandKit::Command
+      #
+      # The `config get` sub-command.
+      #
+      class Get < CommandKit::Command
+
+        usage '[options] NAME'
+
+        argument :name, required: false,
+                        desc:     'Configuration variable name'
+
+        description 'Gets a configuration variable'
+
+        CONFIG = {
+          'name'  => 'John Smith',
+          'email' => 'john.smith@example.com'
+        }
+
+        #
+        # Runs the `config get` sub-command.
+        #
+        # @param [String, nil] name
+        #   The optional name argument.
+        #
+        def run(name=nil)
+          if name
+            unless CONFIG.has_key?(name)
+              print_error "unknown config variable: #{name}"
+              exit(1)
+            end
+
+            puts CONFIG.fetch(name)
+          else
+            CONFIG.each do |name,value|
+              puts "#{name}:\t#{value}"
+            end
+          end
+        end
+
+      end
+    end
+  end
+end

data/examples/subcommands/cli/config/set.rb

@@ -0,0 +1,44 @@
+require 'command_kit/command'
+
+module Foo
+  class CLI
+    class Config < CommandKit::Command
+      #
+      # The `config set` sub-command.
+      #
+      class Set < CommandKit::Command
+
+        usage '[options] NAME'
+
+        argument :name, required: true,
+                        desc:     'Configuration variable name to set'
+
+        argument :value, required: true,
+                         desc:     'Configuration variable value to set'
+
+        description 'Sets a configuration variable'
+
+        CONFIG = {
+          'name'  => 'John Smith',
+          'email' => 'john.smith@example.com'
+        }
+
+        #
+        # Runs the `config get` sub-command.
+        #
+        # @param [String] name
+        #   The name argument.
+        #
+        def run(name,value)
+          unless CONFIG.has_key?(name)
+            print_error "unknown config variable: #{name}"
+            exit(1)
+          end
+
+          puts "Configuration variable #{name} was #{CONFIG.fetch(name)}, but is now #{value}"
+        end
+
+      end
+    end
+  end
+end

data/examples/subcommands/cli/config.rb

@@ -0,0 +1,23 @@
+require 'command_kit/command'
+require 'command_kit/commands'
+
+require_relative 'config/get'
+require_relative 'config/set'
+
+module Foo
+  class CLI
+    #
+    # The `config` sub-command.
+    #
+    class Config < CommandKit::Command
+
+      include CommandKit::Commands
+
+      command Get
+      command Set
+
+      description 'Get or set the configuration'
+
+    end
+  end
+end

data/examples/subcommands/cli/list.rb

@@ -0,0 +1,35 @@
+require 'command_kit/command'
+
+module Foo
+  class CLI
+    #
+    # The `list` sub-command.
+    #
+    class List < CommandKit::Command
+
+      usage '[options] [NAME]'
+
+      argument :name, required: false,
+                      desc:     'Optional name to list'
+
+      description 'Lists the contents'
+
+      ITEMS = %w[foo bar baz]
+
+      #
+      # Runs the `list` sub-command.
+      #
+      # @param [String, nil] name
+      #   The optional name argument.
+      #
+      def run(name=nil)
+        if name
+          puts ITEMS.grep(name)
+        else
+          puts ITEMS
+        end
+      end
+
+    end
+  end
+end

data/examples/subcommands/cli/update.rb

@@ -0,0 +1,47 @@
+require 'command_kit/command'
+
+module Foo
+  class CLI
+    #
+    # The `update` sub-command.
+    #
+    class Update < CommandKit::Command
+
+      usage '[options] [NAME]'
+
+      option :quiet, short: '-q',
+                     desc:  'Suppresses logging messages'
+
+      argument :name, required: false,
+                      desc:     'Optional name to update'
+
+      description 'Updates an item or all items'
+
+      ITEMS = %w[foo bar baz]
+
+      #
+      # Runs the `update` sub-command.
+      #
+      # @param [String, nil] name
+      #   The optional name argument.
+      #
+      def run(name=nil)
+        if name
+          unless ITEMS.include?(name)
+            print_error "unknown item: #{name}"
+            exit(1)
+          end
+
+          puts "Updating #{name} ..." unless options[:quiet]
+          sleep 1
+          puts "Item #{name} updated." unless options[:quiet]
+        else
+          puts "Updating ..." unless options[:quiet]
+          sleep 2
+          puts "All items updated." unless options[:quiet]
+        end
+      end
+
+    end
+  end
+end

data/examples/subcommands/cli.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('../../../lib',__FILE__))
+
+require 'command_kit/commands'
+
+require_relative 'cli/config'
+require_relative 'cli/list'
+require_relative 'cli/update'
+
+module Foo
+  #
+  # The main CLI command.
+  #
+  class CLI
+
+    include CommandKit::Commands
+
+    class << self
+      # The global configuration file setting.
+      #
+      # @return [String, nil]
+      attr_accessor :config_file
+    end
+
+    command_name 'foo'
+
+    # Commands must be explicitly registered, unless
+    # CommandKit::Commands::AutoLoad.new(...) is included.
+    command Config
+    command List
+    command Update
+
+    # Commands may have aliases
+    command_aliases['ls'] = 'list'
+    command_aliases['up'] = 'update'
+
+    # Global options may be defined which are parsed before the sub-command's
+    # options are parsed and the sub-command is executed.
+    option :config_file, short: '-C',
+                         value: {
+                           type: String,
+                           usage: 'FILE'
+                         },
+                         desc: 'Global option to set the config file' do |file|
+                           CLI.config_file = file
+                         end
+
+  end
+end
+
+if $0 == __FILE__
+  # Normally you would invoke Foo::CLI.start from a bin/ script.
+  Foo::CLI.start
+end

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/home.rb

@@ -20,7 +20,7 @@ module CommandKit
       module ModuleMethods
         #
         # Extends {ClassMethods} or {ModuleMethods}, depending on whether
-        # {Env::Home} is being included into a class or a module..
+        # {Env::Home} is being included into a class or a module.
         #
         # @param [Class, Module] context
         #   The class or module which is including {Home}.