command_kit 0.1.0.pre1 → 0.2.0

data/Rakefile

@@ -1,5 +1,3 @@
-# encoding: utf-8
-
 require 'rubygems'
 
 begin
@@ -21,3 +19,6 @@ task :default => :spec
 require 'yard'
 YARD::Rake::YardocTask.new
 task :doc => :yard
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new

data/command_kit.gemspec

@@ -1,5 +1,3 @@
-# encoding: utf-8
-
 require 'yaml'
 
 Gem::Specification.new do |gem|
@@ -20,11 +18,13 @@ Gem::Specification.new do |gem|
   gem.authors     = Array(gemspec['authors'])
   gem.email       = gemspec['email']
   gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
 
   glob = lambda { |patterns| gem.files & Dir[*patterns] }
 
-  gem.files = `git ls-files`.split($/)
-  gem.files = glob[gemspec['files']] if gemspec['files']
+  gem.files = if gemspec['files'] then glob[gemspec['files']]
+              else                     `git ls-files`.split($/)
+              end
 
   gem.executables = gemspec.fetch('executables') do
     glob['bin/*'].map { |path| File.basename(path) }

data/examples/colors.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('../../lib',__FILE__))
+require 'command_kit/command'
+require 'command_kit/colors'
+
+class ColorsCmd < CommandKit::Command
+
+  include CommandKit::Colors
+
+  description "Prints all of the standard ANSI colors"
+
+  def run
+    colors do |c|
+      puts c.black("Black")     + "\t" + c.bold(c.black("Bold"))
+      puts c.red("Red")         + "\t" + c.bold(c.red("Bold"))
+      puts c.green("Green")     + "\t" + c.bold(c.green("Bold"))
+      puts c.yellow("Yellow")   + "\t" + c.bold(c.yellow("Bold"))
+      puts c.blue("Blue")       + "\t" + c.bold(c.blue("Bold"))
+      puts c.magenta("Magenta") + "\t" + c.bold(c.magenta("Bold"))
+      puts c.cyan("Cyan")       + "\t" + c.bold(c.cyan("Bold"))
+      puts c.cyan("White")      + "\t" + c.bold(c.white("Bold"))
+    end
+  end
+
+end
+
+if __FILE__ == $0
+  ColorsCmd.start
+end

data/examples/command.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('../../lib',__FILE__))
+require 'command_kit/command'
+
+class Command < CommandKit::Command
+
+  usage '[OPTIONS] [-o OUTPUT] FILE'
+
+  option :count, short: '-c',
+                 value: {
+                   type: Integer,
+                   default: 1
+                 },
+                 desc: "Number of times"
+
+  option :output, value: {
+                    type: String,
+                    usage: 'FILE'
+                  },
+                  short: '-o',
+                  desc: "Optional output file"
+
+  option :verbose, short: '-v', desc: "Increase verbose level" do
+    @verbose += 1
+  end
+
+  argument :file, required: true,
+                  usage: 'FILE',
+                  desc: "Input file"
+
+  examples [
+    '-o path/to/output.txt path/to/input.txt',
+    '-v -c 2 -o path/to/output.txt path/to/input.txt'
+  ]
+
+  description "Example command"
+
+  def initialize
+    super
+
+    @verbose = 0
+  end
+
+  def run(file)
+    unless options.empty?
+      puts "Options:"
+      options.each do |name,value|
+        puts "  #{name.inspect} => #{value.inspect}"
+      end
+      puts
+    end
+
+    puts "Arguments:"
+    puts "  file = #{file.inspect}"
+    puts
+
+    puts "Custom Variables:"
+    puts "  version = #{@verbose.inspect}"
+  end
+end
+
+if __FILE__ == $0
+  Command.start
+end

data/examples/pager.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('../../lib',__FILE__))
+require 'command_kit/command'
+require 'command_kit/pager'
+
+class PagerCmd < CommandKit::Command
+
+  include CommandKit::Pager
+
+  description "Demos using the pager"
+
+  def run
+    puts "Starting pager ..."
+
+    pager do |io|
+      10.times do |i|
+        io.puts i
+        sleep 0.5
+      end
+    end
+
+    puts "Exiting pager ..."
+  end
+
+end
+
+if __FILE__ == $0
+  PagerCmd.start
+end

data/gemspec.yml

@@ -2,11 +2,19 @@ name: command_kit
 summary: A toolkit for building Ruby CLI commands
 description:
   A Ruby toolkit for building clean, correct, and robust CLI commands as
-  Ruby classes.
+  plain-old Ruby classes.
+
 license: MIT
 authors: Postmodern
 email: postmodern.mod3@gmail.com
-homepage: https://github.com/postmodern/command_kit#readme
+homepage: https://github.com/postmodern/command_kit.rb#readme
+
+metadata:
+  documentation_uri: https://rubydoc.info/gems/command_kit
+  source_code_uri:   https://github.com/postmodern/command_kit.rb
+  bug_tracker_uri:   https://github.com/postmodern/command_kit.rb/issues
+  changelog_uri:     https://github.com/postmodern/command_kit.rb/blob/main/ChangeLog.md
+
 
 required_ruby_version: ">= 2.7.0"
 

data/lib/command_kit/arguments/argument.rb

@@ -5,84 +5,56 @@ module CommandKit
     #
     # Represents a defined argument.
     #
+    # @api private
+    #
     class Argument < ArgumentValue
 
+      # The argument's name.
+      #
       # @return [Symbol]
       attr_reader :name
 
-      # @return [Boolean]
-      attr_reader :repeats
-
-      # @return [String, nil]
+      # The argument's description.
+      #
+      # @return [String]
       attr_reader :desc
 
-      # @return [Regexp, nil]
-      attr_reader :pattern
-
-      # @return [Proc, nil]
-      attr_reader :parser
-
-      # @return [Proc, nil]
-      attr_reader :block
-
       #
       # Initializes the argument.
       #
       # @param [Symbol] name
-      #
-      # @param [Class, Hash, Array, Regexp] type
+      #   The name of the argument.
       #
       # @param [String, nil] usage
-      #
-      # @param [Object, Proc, nil] default
+      #   The usage string for the argument. Defaults to the argument's name.
       #
       # @param [Boolean] required
+      #   Specifies whether the argument is required or optional.
       #
       # @param [Boolean] repeats
+      #   Specifies whether the argument can be repeated multiple times.
       #
       # @param [String] desc
-      #
-      # @note `usage` will be assigned a default value based on `type` and
-      # `name`.
+      #   The description for the argument.
       #
       # @yield [(value)]
+      #   If a block is given, it will be used to parse the argument's value.
+      #   Note: not currently used.
       #
       # @yieldparam [Object, nil] value
       #
-      def initialize(name, type:     String,
-                           usage:    name.to_s.upcase,
-                           default:  nil,
+      def initialize(name, usage:    name.to_s.upcase,
                            required: true,
                            repeats:  false,
-                           desc:     ,
-                           &block)
+                           desc:     )
         super(
-          type:     type,
           usage:    usage,
-          default:  default,
           required: required
         )
 
         @name    = name
         @repeats = repeats
         @desc    = desc
-
-        @pattern, @parser = self.class.parser(@type)
-
-        @block = block
-      end
-
-      #
-      # Looks up the option parser for the given `OptionParser` type.
-      #
-      # @param [Class] type
-      #   The `OptionParser` type class.
-      #
-      # @return [(Regexp, Proc), nil]
-      #   The matching pattern and converter proc.
-      #
-      def self.parser(type)
-        OptionParser::DefaultList.search(:atype,type)
       end
 
       #

data/lib/command_kit/arguments/argument_value.rb

@@ -3,18 +3,10 @@ module CommandKit
     #
     # Represents an individual argument value.
     #
+    # @api private
+    #
     class ArgumentValue
 
-      # The desired type of the argument value.
-      #
-      # @return [Class, Hash, Array, Regexp, nil]
-      attr_reader :type
-
-      # The default parsed value for the argument value.
-      #
-      # @return [Object, Proc, nil]
-      attr_reader :default
-
       # Specifies whether the argument value is required or optional.
       #
       # @return [Boolean]
@@ -28,22 +20,14 @@ module CommandKit
       #
       # Initializes the argument value.
       #
-      # @param [Class, Hash, Array, Regexp] type
-      #   The type of the argument value.
-      #
       # @param [Boolean] required
       #   Specifies whether the argument value is required or optional.
       #
       # @param [String] usage
       #   The usage string to represent the argument value.
       #
-      # @param [Object, Proc, nil] default
-      #   The default parsed value for the argument value.
-      #
-      def initialize(type: nil, required: true, default: nil, usage: )
-        @type     = type
+      def initialize(required: true, usage: )
         @required = required
-        @default  = default
         @usage    = usage
       end
 
@@ -65,17 +49,6 @@ module CommandKit
         !@required
       end
 
-      #
-      # Returns a new default value.
-      #
-      # @return [Object]
-      #
-      def default_value
-        if @default.respond_to?(:call) then @default.call
-        else                                @default.dup
-        end
-      end
-
     end
   end
 end

data/lib/command_kit/arguments.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+require 'command_kit/main'
 require 'command_kit/help'
 require 'command_kit/arguments/argument'
 
@@ -9,15 +12,45 @@ module CommandKit
   #
   #     include CommandKit::Arguments
   #     
-  #     argument :output, type: String,
-  #                       desc: 'The output file'
+  #     argument :output, desc: 'The output file'
+  #     
+  #     argument :input, desc: 'The input file(s)'
   #     
-  #     argument :input, type: Array,
-  #                      desc: 'The input file(s)'
+  #     def run(output,input)
+  #     end
+  #
+  # ### Optional Arguments
+  #
+  #     argument :dir, required: false,
+  #                    desc:     'Can be omitted'
+  #
+  #     def run(dir=nil)
+  #     end
+  #
+  # ### Repeating Arguments
+  #
+  #     argument :files, repeats: true,
+  #                      desc:    'Can be repeated one or more times'
+  #
+  #     def run(*files)
+  #     end
+  #
+  # ### Optional Repeating Arguments
+  #
+  #     argument :files, required: true,
+  #                      repeats:  true,
+  #                      desc:     'Can be repeated one or more times'
+  #
+  #     def run(*files)
+  #     end
   #
   module Arguments
+    include Main
     include Help
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -49,6 +82,8 @@ module CommandKit
       # @return [Hash{Symbol => Argument}]
       #   The defined argument for the class and it's superclass.
       #
+      # @api semipublic
+      #
       def arguments
         @arguments ||= if superclass.kind_of?(ClassMethods)
                          superclass.arguments.dup
@@ -61,13 +96,22 @@ module CommandKit
       # Defines an argument for the class.
       #
       # @param [Symbol] name
-      #   The argument name.
+      #   The name of the argument.
+      #
+      # @param [Hash{Symbol => Object}] kwargs
+      #   Keyword arguments.
       #
-      # @yield [(arg)]
-      #   If a block is given, it will be passed the parsed argument.
+      # @option kwargs [String, nil] usage
+      #   The usage string for the argument. Defaults to the argument's name.
       #
-      # @yieldparam [Object, nil] arg
-      #   The parsed argument.
+      # @option kwargs [Boolean] required
+      #   Specifies whether the argument is required or optional.
+      #
+      # @option kwargs [Boolean] repeats
+      #   Specifies whether the argument can be repeated multiple times.
+      #
+      # @option kwargs [String] desc
+      #   The description for the argument.
       #
       # @return [Argument]
       #   The newly defined argument.
@@ -79,14 +123,8 @@ module CommandKit
       #     option :bar, usage: 'BAR',
       #                  desc: "Bar argument"
       #
-      # @example With a custom block:
-      #     argument :bar, desc: "Bar argument" do |bar|
-      #       # ...
-      #     end
-      #
       # @example With a custom type:
-      #     argument :bar, type: Integer,
-      #                    desc: "Bar argument"
+      #     argument :bar, desc: "Bar argument"
       #
       # @example With a default value:
       #     argument :bar, default: "bar.txt",
@@ -100,8 +138,10 @@ module CommandKit
       #     argument :bar, repeats: true,
       #                    desc: "Bar argument"
       #
-      def argument(name,**kwargs,&block)
-        arguments[name] = Argument.new(name,**kwargs,&block)
+      # @api public
+      #
+      def argument(name,**kwargs)
+        arguments[name] = Argument.new(name,**kwargs)
       end
     end
 
@@ -116,6 +156,8 @@ module CommandKit
     #   The exit status code. If too few or too many arguments are given, then
     #   an error message is printed and `1` is returned.
     #
+    # @api public
+    #
     def main(argv=[])
       required_args   = self.class.arguments.each_value.count(&:required?)
       optional_args   = self.class.arguments.each_value.count(&:optional?)
@@ -137,12 +179,14 @@ module CommandKit
     #
     # Prints any defined arguments, along with the usual `--help` information.
     #
+    # @api semipublic
+    #
     def help_arguments
       unless (arguments = self.class.arguments).empty?
         puts
         puts 'Arguments:'
 
-        self.class.arguments.each_value do |arg|
+        arguments.each_value do |arg|
           puts "    #{arg.usage.ljust(33)}#{arg.desc}"
         end
       end
@@ -152,8 +196,10 @@ module CommandKit
     # Calls the superclass'es `#help` method, if it's defined, then calls
     # {#help_arguments}.
     #
+    # @api public
+    #
     def help
-      super if defined?(super)
+      super
 
       help_arguments
     end