command_kit 0.5.6 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22cdb1135f132682db99b624f27bc5cfbadb51fb988c6c5751210d9e4da994c3
-  data.tar.gz: c01856011175c54fed46b0ab6663cb63eeb125de18767529ffc05b9ea3045d9b
+  metadata.gz: 5bf3011e0c065be0e6c7fd1da97f0c0de87b80674a29e782c339b63b15384992
+  data.tar.gz: bcad8e0d7ad0113bee65d2c5eda383f300b9764e3a0b53d90752e551299be0d0
 SHA512:
-  metadata.gz: d12c2d1904405af1fff0e36b3d73ab3c897d47057f6f71a6db8e34b6aa4419673c0e2b4a6bec2f9cefd4f90bd72be4c86b4e44d9e82912776f14691ffecbcd82
-  data.tar.gz: 349d3f009628535477976b63ce42a23ce30765592663b5ec76f0c07e3530edc723c2cad32441ec9c9559241825913e9afaad37822c64918b7985e3b6579703ff
+  metadata.gz: 9c13184c83e668c3afd46ad1ad28a7d78655f1e8602831120ead6f39f2f35f4f6ba08151339e16485ef9111690b7975af4cb6a219787ec3530fb0a822cd2c952
+  data.tar.gz: ba6caee506bb4085cab8a6fe8a389006e0423643a1ee35e1f0a26a2ec0e6fc1f5f53a982f3a8247fefebdf2e6fbf9a3c05afc5d78a1209f8921e1566643e30b8

data/ChangeLog.md

@@ -1,3 +1,9 @@
+### 0.6.0 / 2024-06-19
+
+* Added {CommandKit::Interactive#ask_multiline}.
+* Added {CommandKit::Open}.
+* Added {CommandKit::Options::VerboseLevel}.
+
 ### 0.5.6 / 2024-06-19
 
 #### CommandKit::Inflector

data/README.md

@@ -229,6 +229,7 @@ end
   * [CommandKit::Help::Man](https://rubydoc.info/gems/command_kit/CommandKit/Help/Man)
 * [CommandKit::Interactive](https://rubydoc.info/gems/command_kit/CommandKit/Interactive)
 * [CommandKit::Main](https://rubydoc.info/gems/command_kit/CommandKit/Main)
+* [CommandKit::Open](https://rubydoc.info/gems/command_kit/CommandKit/Open)
 * [CommandKit::Options](https://rubydoc.info/gems/command_kit/CommandKit/Options)
   * [CommandKit::Options::Quiet](https://rubydoc.info/gems/command_kit/CommandKit/Options/Quiet)
   * [CommandKit::Options::Verbose](https://rubydoc.info/gems/command_kit/CommandKit/Options/Verbose)

data/examples/interactive.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('../../lib',__FILE__))
+require 'command_kit/command'
+require 'command_kit/interactive'
+
+class InteractiveCmd < CommandKit::Command
+
+  include CommandKit::Interactive
+
+  description 'Demonstrates interactive prompt input'
+
+  def run
+    you_entered = ->(result) {
+      puts "You entered: #{result.inspect}"
+      puts
+    }
+
+    you_entered[ask("Single-line input")]
+    you_entered[ask_secret("Secret input")]
+    you_entered[ask_yes_or_no("Yes or no prompt")]
+    you_entered[ask_multiple_choice("Multiple choice", %w[Red Green Blue])]
+    you_entered[ask_multiline('Multi-line comment 1')]
+  end
+
+end
+
+if __FILE__ == $0
+  InteractiveCmd.start
+end

data/lib/command_kit/interactive.rb

@@ -34,6 +34,15 @@ module CommandKit
   #     #
   #     # => "Lime"
   #
+  # ### Prompt for multi-line input
+  #
+  #     ask_multiline('Comment')
+  #     # Comment (Press Ctrl^D to exit):
+  #     # foo bar
+  #     # baz qux
+  #     # Ctrl^D
+  #     # => "foo bar\nbaz qux\n"
+  #
   module Interactive
     include Stdio
 
@@ -244,5 +253,83 @@ module CommandKit
       end
     end
 
+    #
+    # Asks the user for multi-line text input.
+    #
+    # @param [String] prompt
+    #   The prompt that will be printed before reading input.
+    #
+    # @param [String, nil] help
+    #   Optional help instructions on how to exit from reading.
+    #
+    # @param [String, nil] default
+    #   The default value to return if no input is given.
+    #
+    # @param [Boolean] required
+    #   Requires non-empty input.
+    #
+    # @param [:double_newline, :ctrl_d] terminator
+    #   Indicates how the input should be terminated.
+    #   Defaults to `:ctrl_d` which indicates `Ctrl^D`.
+    #
+    # @return [String]
+    #   The user input.
+    #
+    # @example
+    #   ask_multiline('Comment')
+    #   # Comment (Press Ctrl^D to exit):
+    #   # foo bar
+    #   # baz qux
+    #   # Ctrl^D
+    #   # => "foo bar\nbaz qux\n"
+    #
+    # @example Terminate input on a double newline:
+    #   ask_multiline('Comment', terminator: :double_newline)
+    #   # Comment (Enter two empty lines to exit):
+    #   # foo bar
+    #   # baz qux
+    #   #
+    #   # => "foo bar\nbaz qux\n"
+    #
+    # @api public
+    #
+    # @since 0.6.0
+    #
+    def ask_multiline(prompt, help:       nil,
+                              default:    nil,
+                              required:   false,
+                              terminator: :ctrl_d)
+      case terminator
+      when :ctrl_d
+        eos    = nil
+        help ||= 'Press Ctrl^D to exit'
+      when :double_newline
+        eos    = "#{$/}#{$/}"
+        help ||= 'Press Enter twice to exit'
+      else
+        raise(ArgumentError,"invalid terminator: #{terminator.inspect}")
+      end
+
+      prompt = "#{prompt.chomp} (#{help})"
+      prompt << " [#{default}]" if default
+      prompt << ": "
+
+      loop do
+        stdout.puts(prompt)
+
+        value = stdin.gets(eos)
+        value ||= '' # convert nil values (ctrl^D) to an empty String
+
+        if value.empty?
+          if required
+            next
+          else
+            return (default || value)
+          end
+        else
+          return value
+        end
+      end
+    end
   end
 end

data/lib/command_kit/open.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative 'stdio'
+require_relative 'printing'
+
+module CommandKit
+  #
+  # Adds helper methods for opening files.
+  #
+  # ## Features
+  #
+  # * Prints `No such file or directory` error if the given file does not exist.
+  # * Handles `-` file paths which indicate input should be read from STDIN or
+  #   output written to STDOUT.
+  #
+  # ## Examples
+  #
+  #     include CommandKit::Open
+  #
+  #     def run(path)
+  #       open(path) do |file|
+  #         # ...
+  #       end
+  #     end
+  #
+  # @since 0.6.0
+  #
+  module Open
+    include Stdio
+    include Printing
+
+    #
+    # Opens a file for reading or writing.
+    #
+    # @param [String] path
+    #   The path of the given file. May be `"-"` to indicate that input should
+    #   be read from STDINT or output written to STDOUT.
+    #
+    # @param [String] mode
+    #   The mode to open the file with.
+    #
+    # @yield [file]
+    #   * If the given path is `"-"`.
+    #     * and the given mode contains `w` or `a`, then {#stdout} will be
+    #       yielded.
+    #     * and no mode is given or if the mode contains `r`, then {#stdin} will
+    #       be yielded.
+    #   * Otherwise, the newly opened file.
+    #
+    # @yieldparam [File, IO] file
+    #   The newly opened file, or {#stdin} / {#stdout} if the given path is
+    #   `"-"`.
+    #
+    # @return [File, IO, Object]
+    #   * If no block is given, the newly opened file, or {#stdin} / {#stdout}
+    #     if the given path is `"-"`, will be returned.
+    #   * If a block was given, then the return value of the block will be
+    #     returned.
+    #
+    # @example Opening a file for reading:
+    #   open(path)
+    #   # => #<File:...>
+    #
+    # @example Temporarily opening a file for reading:
+    #   open(path) do |file|
+    #     # ...
+    #   end
+    #
+    # @example Opening a file for writing:
+    #   open(path,'w')
+    #   # => #<File:...>
+    #
+    # @example Temporarily opening a file for writing:
+    #   open(path,'w') do |output|
+    #     output
+    #   end
+    #
+    # @api public
+    #
+    # @since 0.6.0
+    #
+    def open(path,mode='r',&block)
+      if path == '-'
+        io = case mode
+             when /[wa]/ then stdout
+             else             stdin
+             end
+
+        if block_given?
+          return yield(io)
+        else
+          return io
+        end
+      end
+
+      begin
+        File.open(path,mode,&block)
+      rescue Errno::ENOENT
+        print_error "No such file or directory: #{path}"
+        exit(1)
+      end
+    end
+  end
+end

data/lib/command_kit/options/verbose_level.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative '../options'
+
+module CommandKit
+  module Options
+    #
+    # Defines a `-v`,`--verbose` option that can be specified multiple times to
+    # increase the verbosity level.
+    #
+    # ## Examples
+    #
+    #     include CommandKit::Options::VerboseLevel
+    #
+    #     def run(*argv)
+    #       # ...
+    #       case verbose
+    #       when 1
+    #         puts "verbose output"
+    #       when 2
+    #         puts " extra verbose output"
+    #       end
+    #       # ...
+    #     end
+    #
+    # @since 0.6.0
+    #
+    module VerboseLevel
+      include Options
+
+      #
+      # @api private
+      #
+      module ModuleMethods
+        #
+        # Defines a `-v, --verbose` option or extends {ModuleMethods}, depending
+        # on whether {Options::Verbose} is being included into a class or a
+        # module.
+        #
+        # @param [Class, Module] context
+        #   The class or module including {Verbose}.
+        #
+        def included(context)
+          super(context)
+
+          if context.class == Module
+            context.extend ModuleMethods
+          else
+            context.option :verbose, short: '-v', desc: 'Increases the verbosity level' do
+              @verbose += 1
+            end
+          end
+        end
+      end
+
+      extend ModuleMethods
+
+      # The verbosity level.
+      #
+      # @return [Integer]
+      attr_reader :verbose
+
+      #
+      # Initializes the command and sets {#verbose} to 0.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments.
+      #
+      def initialize(**kwargs)
+        super(**kwargs)
+
+        @verbose = 0
+      end
+
+      #
+      # Determines if verbose mode is enabled.
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      #
+      def verbose?
+        @verbose > 0
+      end
+    end
+  end
+end

data/lib/command_kit/version.rb

@@ -2,5 +2,5 @@
 
 module CommandKit
   # command_kit version
-  VERSION = "0.5.6"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: command_kit
 version: !ruby/object:Gem::Version
-  version: 0.5.6
+  version: 0.6.0
 platform: ruby
 authors:
 - Postmodern
@@ -48,6 +48,7 @@ files:
 - command_kit.gemspec
 - examples/colors.rb
 - examples/command.rb
+- examples/interactive.rb
 - examples/pager.rb
 - examples/printing/tables.rb
 - examples/subcommands/cli.rb
@@ -90,6 +91,7 @@ files:
 - lib/command_kit/interactive.rb
 - lib/command_kit/main.rb
 - lib/command_kit/man.rb
+- lib/command_kit/open.rb
 - lib/command_kit/open_app.rb
 - lib/command_kit/options.rb
 - lib/command_kit/options/option.rb
@@ -97,6 +99,7 @@ files:
 - lib/command_kit/options/parser.rb
 - lib/command_kit/options/quiet.rb
 - lib/command_kit/options/verbose.rb
+- lib/command_kit/options/verbose_level.rb
 - lib/command_kit/options/version.rb
 - lib/command_kit/os.rb
 - lib/command_kit/os/linux.rb