command_kit 0.1.0.pre1 → 0.1.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa6096447b8ddf59149147d020c3fe6f5fcf6de1c167f749692fc1b50dec1b8a
-  data.tar.gz: c4c0a58596e92563f9f69a7fd151a7b7dd9121c8083ca104a21dd3ce53ef2fc5
+  metadata.gz: baf0cab5c4519bef85a5ac27597c1c67b28a77cbe86d6c34b72687a91e1ef906
+  data.tar.gz: 1b816bb979dcff48caf5c09ac7f4dcd9006871c94b9fd3bee5a7c2ce1763815a
 SHA512:
-  metadata.gz: a777422cddc17a986940b7cd902ac43c01765b6ef98efe717307f545a29dfe975579bb8eacdce9647cd2ccbd0f210b7a8b0ab3ffac026d8341f2c9669ef56a18
-  data.tar.gz: 7b768f74911ac136b24f755534d31844febb92b5b034e672b4b93c3a45083b4731d9658830b6f700bc8b70106b772f253291ed15fcd36f5f709351808910c93b
+  metadata.gz: 284c9a6ff6bb1584add29558658054fc0814cfc0b1a1609b16a577154bc85e7011d9989abc75418bbd631f00a5f6c444dd104b3d938be347ad32ddf08e84ec83
+  data.tar.gz: f0df98d7654058aa5be0aa884703ef540be3a1b7e2be52cd4a975913731ee4572d30cfc1a7b5213b9a165e7a18f95f4bbd3d9eb1a217362370a6c3b9e6c7ea93

data/README.md

@@ -14,6 +14,7 @@ classes.
 
 * Supports defining commands as Classes.
 * Supports defining options and arguments as attributes.
+* Supports extending commands via inheritance.
 * Supports subcommands (explicit or lazy-loaded) and command aliases.
 * Correctly handles Ctrl^C and SIGINT interrupts (aka exit 130).
 * Correctly handles broken pipes (aka `mycmd | head`).
@@ -22,36 +23,38 @@ classes.
 * Supports optionally displaying a man-page instead of `--help`
   (see {CommandKit::Help::Man}).
 * Supports XDG directories (`~/.config/`, `~/.local/share/`, `~/.cache/`).
-* Easy to test:
-  * `MyCmd.main(arg1, arg2, options: {foo: foo}) # => 0`
-
-### Modules
-
-* {CommandKit::Arguments}
-* {CommandKit::Colors}
-* {CommandKit::CommandName}
-* {CommandKit::Commands}
-  * {CommandKit::Commands::AutoLoad}
-  * {CommandKit::Commands::AutoRequire}
-* {CommandKit::Console}
-* {CommandKit::Description}
-* {CommandKit::Env}
-  * {CommandKit::Env::Home}
-  * {CommandKit::Env::Path}
-* {CommandKit::Examples}
-* {CommandKit::ExceptionHandler}
-* {CommandKit::Help}
-  * {CommandKit::Help::Man}
-* {CommandKit::Main}
-* {CommandKit::Options}
-  * {CommandKit::Options::Quiet}
-  * {CommandKit::Options::Verbose}
-* {CommandKit::Pager}
-* {CommandKit::Printing}
-* {CommandKit::ProgramName}
-* {CommandKit::Stdio}
-* {CommandKit::Usage}
-* {CommandKit::XDG}
+* Easy to test (ex: `MyCmd.main(arg1, arg2, options: {foo: foo}) # => 0`)
+* Modular design (everything is a module).
+
+### API
+
+* [CommandKit::Arguments](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Arguments)
+* [CommandKit::Colors](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Colors)
+* [CommandKit::Command](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Command)
+* [CommandKit::CommandName](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/CommandName)
+* [CommandKit::Commands](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands)
+  * [CommandKit::Commands::AutoLoad](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands/AutoLoad)
+  * [CommandKit::Commands::AutoRequire](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands/AutoRequire)
+* [CommandKit::Console](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Console)
+* [CommandKit::Description](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Description)
+* [CommandKit::Env](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env)
+  * [CommandKit::Env::Home](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env/Home)
+  * [CommandKit::Env::Path](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env/Path)
+* [CommandKit::Examples](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Examples)
+* [CommandKit::ExceptionHandler](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/ExceptionHandler)
+* [CommandKit::Help](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Help)
+  * [CommandKit::Help::Man](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Help/Man)
+* [CommandKit::Main](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Main)
+* [CommandKit::Options](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options)
+  * [CommandKit::Options::Quiet](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options/Quiet)
+  * [CommandKit::Options::Verbose](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options/Verbose)
+* [CommandKit::Pager](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Pager)
+* [CommandKit::Printing](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Printing)
+  * [CommandKit::Printing::Indent](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Printing/Indent)
+* [CommandKit::ProgramName](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/ProgramName)
+* [CommandKit::Stdio](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Stdio)
+* [CommandKit::Usage](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Usage)
+* [CommandKit::XDG](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/XDG)
 
 ## Anti-Features
 
@@ -61,9 +64,7 @@ classes.
 
 ## Examples
 
-### Command
-
-#### lib/foo/cli/my_cmd.rb
+### lib/foo/cli/my_cmd.rb
 
     require 'command_kit'
 
@@ -91,8 +92,7 @@ classes.
             @verbose += 1
           end
     
-          argument :file, type: String,
-                          required: true,
+          argument :file, required: true,
                           usage: 'FILE',
                           desc: "Input file"
 
@@ -120,7 +120,7 @@ classes.
       end
     end
 
-#### bin/my_cmd
+### bin/my_cmd
 
     #!/usr/bin/env ruby
     
@@ -129,7 +129,7 @@ classes.
     
     Foo::CLI::MyCmd.start
 
-#### --help
+### --help
 
     Usage: my_cmd [OPTIONS] [-o OUTPUT] FILE
     
@@ -148,109 +148,6 @@ classes.
     
     Example command
 
-### Options
-
-Define an option:
-
-    option :foo, desc: "Foo option"
-
-With a custom short option:
-
-    option :foo, short: '-f',
-                 desc: "Foo option"
-
-With a custom long option:
-
-    option :foo, short: '--foo-opt',
-                 desc: "Foo option"
-
-With a custom usage string:
-
-    option :foo, value: {usage: 'FOO'},
-                 desc: "Foo option"
-
-With a custom block:
-
-    option :foo, desc: "Foo option" do |value|
-      @foo = Foo.new(value)
-    end
-
-With a custom type:
-
-    option :foo, value: {type: Integer},
-                 desc: "Foo option"
-
-With a default value:
-
-    option :foo, value: {type: Integer, default: 1},
-                 desc: "Foo option"
-
-With a required value:
-
-    option :foo, value: {type: String, required: true},
-                 desc: "Foo option"
-
-With a custom option value Hash map:
-
-    option :flag, value: {
-                    type: {
-                      'enabled'  => :enabled,
-                      'yes'      => :enabled,
-                      'disabled' => :disabled,
-                      'no'       => :disabled
-                    }
-                  },
-                  desc: "Flag option"
-
-With a custom option value Array enum:
-
-    option :enum, value: {type: %w[yes no]},
-                  desc: "Enum option"
-
-With a custom option value Regexp:
-
-    option :date, value: {type: /(\d+)-(\d+)-(\d{2,4})/},
-                  desc: "Regexp optin" do |date,d,m,y|
-      # ...
-    end
-
-### Arguments
-
-Define an argument:
-
-    argument :bar, desc: "Bar argument"
-
-With a custom usage string:
-
-    option :bar, usage: 'BAR',
-                 desc: "Bar argument"
-
-With a custom block:
-
-    argument :bar, desc: "Bar argument" do |bar|
-      # ...
-    end
-
-With a custom type:
-
-    argument :bar, type: Integer,
-                   desc: "Bar argument"
-
-With a default value:
-
-    argument :bar, default: "bar.txt",
-                   desc: "Bar argument"
-
-An optional argument:
-
-    argument :bar, required: true,
-                   desc: "Bar argument"
-
-A repeating argument:
-
-    argument :bar, repeats: true,
-                   desc: "Bar argument"
-
 ## Requirements
 
 * [ruby] >= 2.7.0

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/lib/command_kit/arguments.rb

@@ -1,3 +1,4 @@
+require 'command_kit/main'
 require 'command_kit/help'
 require 'command_kit/arguments/argument'
 
@@ -9,13 +10,40 @@ module CommandKit
   #
   #     include CommandKit::Arguments
   #     
-  #     argument :output, type: String,
-  #                       desc: 'The output file'
+  #     argument :output, desc: 'The output file'
   #     
-  #     argument :input, type: Array,
-  #                      desc: 'The input file(s)'
+  #     argument :input, 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
 
     module ModuleMethods
@@ -61,13 +89,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.
+      #
+      # @option kwargs [String, nil] usage
+      #   The usage string for the argument. Defaults to the argument's name.
       #
-      # @yield [(arg)]
-      #   If a block is given, it will be passed the parsed argument.
+      # @option kwargs [Boolean] required
+      #   Specifies whether the argument is required or optional.
       #
-      # @yieldparam [Object, nil] arg
-      #   The parsed argument.
+      # @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 +116,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 +131,8 @@ module CommandKit
       #     argument :bar, repeats: true,
       #                    desc: "Bar argument"
       #
-      def argument(name,**kwargs,&block)
-        arguments[name] = Argument.new(name,**kwargs,&block)
+      def argument(name,**kwargs)
+        arguments[name] = Argument.new(name,**kwargs)
       end
     end