command_kit 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72a3fdeb65d9eb4c4e996aa95ea7e8131e220c2cb24be8b17d56e1742a156d35
-  data.tar.gz: d05b75366f58c219c9680d07571a171239f0ab8f77580cb1c2d47c6322d7e74c
+  metadata.gz: 3a35e836c936c91aa916f33e691260a591d2e363de6a0fd3d9259150b86add15
+  data.tar.gz: fe2e2cc87a8a0fe889cba23b5567b307bb088fdf3ee4eff7d681694a981b5143
 SHA512:
-  metadata.gz: 1cc85835b40fded3170ee21619620dbb988dd3427fa8cb48456f09a7991b6eed72299a81ba19be543c260557504d5636237993f33360d463d72a87600ca14441
-  data.tar.gz: 9d57ec57d540547d2fa664faf8e3bb1e0c0aa06929162d3dac849f858911aa5e7610e8294b2189927d8633de8e9784079df548a3e900fd73c57f76e72c87ad9d
+  metadata.gz: da2676ab635edc9898457b1c532af6ac4c478c6f3a0ab19dfc42f0abc4ddd73ef4f473fe7699f8bed3ac5abec3381a7a9ca9c50736c4cc3697612ef36f3d6fea
+  data.tar.gz: d30a04ab5274f489ef3e534950301669d47112ee56d43b59e51c5e816f7de21fba72197d43f3362331c40f3e75a70e0c316d53fe12bf8960daf79efec270a372

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,15 @@
+### 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

@@ -253,7 +253,7 @@ Twitter.
 
 ## Copyright
 
-Copyright (c) 2021-2022 Hal Brodigan
+Copyright (c) 2021-2024 Hal Brodigan
 
 See {file:LICENSE.txt} for details.
 

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/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}.

data/lib/command_kit/inflector.rb

@@ -103,7 +103,7 @@ module CommandKit
           new_string << word
         elsif scanner.scan(/[_-]+/)
           # skip
-        elsif scanner.scan(/\//)
+        elsif scanner.scan(%r{/})
           new_string << '::'
         else
           raise(ArgumentError,"cannot convert string to CamelCase: #{scanner.string.inspect}")

data/lib/command_kit/options/parser.rb

@@ -50,7 +50,7 @@ module CommandKit
 
           if context.class == Module
             context.extend ModuleMethods
-          else
+          elsif context.usage.nil?
             context.usage '[options]'
           end
         end

data/lib/command_kit/os/linux.rb

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

data/lib/command_kit/os.rb

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

data/lib/command_kit/printing/tables/table_formatter.rb

@@ -87,7 +87,7 @@ module CommandKit
                               column_border: ,
                               joined_border: ,
                               right_border: )
-          line = String.new
+          line = String.new(encoding: Encoding::UTF_8)
           line << left_border
 
           @table.max_columns.times do |column_index|
@@ -191,7 +191,7 @@ module CommandKit
         #   The formatted row line.
         #
         def format_row_line(row,line_index, justify: @style.justify)
-          line = String.new
+          line = String.new(encoding: Encoding::UTF_8)
           line << @style.border.left_border if @style.border
 
           @table.max_columns.times do |column_index|

data/lib/command_kit/version.rb

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

data/lib/command_kit/xdg.rb

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

data/spec/commands_spec.rb

@@ -155,6 +155,32 @@ describe CommandKit::Commands do
 
   let(:command_class) { TestCommands::TestCommands }
 
+  describe ".included" do
+    subject { command_class }
+
+    it "must set .usage to '[options] [COMMAND [ARGS...]]'" do
+      expect(subject.usage).to eq('[options] [COMMAND [ARGS...]]')
+    end
+
+    it "must add a 'command' argument" do
+      expect(subject.arguments[:command]).to_not be_nil
+      expect(subject.arguments[:command].required?).to be(false)
+      expect(subject.arguments[:command].desc).to eq('The command name to run')
+    end
+
+    it "must add a 'args' argument" do
+      expect(subject.arguments[:args]).to_not be_nil
+      expect(subject.arguments[:args].required?).to be(false)
+      expect(subject.arguments[:args].repeats?).to be(true)
+      expect(subject.arguments[:args].desc).to eq('Additional arguments for the command')
+    end
+
+    it "must add a 'help' command" do
+      expect(subject.commands['help']).to_not be(nil)
+      expect(subject.commands['help'].command).to be(described_class::Help)
+    end
+  end
+
   describe ".commands" do
     subject { command_class }
 

data/spec/options/parser_spec.rb

@@ -19,6 +19,25 @@ describe CommandKit::Options::Parser do
     it { expect(subject).to include(CommandKit::Main) }
     it { expect(subject).to include(CommandKit::Usage) }
     it { expect(subject.usage).to eq('[options]') }
+
+    context "when the command class already defines a usage string" do
+      module TestOptionParser
+        class TestCommandWithUsage
+          include CommandKit::Usage
+
+          usage '[options] ARGS...'
+
+          include CommandKit::Options::Parser
+        end
+      end
+
+      let(:command_class) { TestOptionParser::TestCommandWithUsage }
+      subject { command_class }
+
+      it "must not override the usage" do
+        expect(subject.usage).to eq('[options] ARGS...')
+      end
+    end
   end
 
   subject { command_class.new }

data/spec/printing/tables/table_formatter_spec.rb

@@ -57,6 +57,16 @@ describe CommandKit::Printing::Tables::TableFormatter do
       )
     end
 
+    it "must encode the Strings as UTF-8" do
+      yielded_lines = []
+
+      subject.format do |line|
+        yielded_lines << line
+      end
+
+      expect(yielded_lines.map(&:encoding)).to all(be(Encoding::UTF_8))
+    end
+
     context "but when the table contains multi-line cells" do
       let(:rows) { multiline_rows }
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_kit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Postmodern
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-11 00:00:00.000000000 Z
+date: 2024-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -50,6 +50,12 @@ files:
 - examples/command.rb
 - examples/pager.rb
 - examples/printing/tables.rb
+- examples/subcommands/cli.rb
+- examples/subcommands/cli/config.rb
+- examples/subcommands/cli/config/get.rb
+- examples/subcommands/cli/config/set.rb
+- examples/subcommands/cli/list.rb
+- examples/subcommands/cli/update.rb
 - gemspec.yml
 - lib/command_kit.rb
 - lib/command_kit/arguments.rb
@@ -198,7 +204,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: An all-in-one modular Ruby CLI toolkit