cl 0.1.23 → 0.1.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1e48bfc8c20e185f62bb0b729a9bbbb27a24f470
-  data.tar.gz: a8c88e60d22e9ee3d4961301b6322d0b2961a3ab
+  metadata.gz: 72952e2db91c199b725e62742a795797062e4ce6
+  data.tar.gz: 44492b50481c1622bc45436f611ae1a4211169a6
 SHA512:
-  metadata.gz: f147afa28916b0b348a840ad74da1373f418756160128bc2e48401abaa003fc431c803df74f9b1a924b4cb8fbf529073713efe13cac2af37b09ae4a92a9355ef
-  data.tar.gz: 87d62debde99d4d840dad4811c828868bb3feeea6aaa84f4eda65fd5a26f565beb2d18e3b149e5a739eae8299b4b7657d1582f14767dccdeb7f9dabbf93522f3
+  metadata.gz: 7b4a5998249ae7521747203fc2e7b3f21f66bcbef86568d025113b4e808faa84f4f7f7b2aa7401eb9ca1e190f25977bf0c5a5856a5b128181e551584a021e665
+  data.tar.gz: 11d40ccbca05ab8dc596dca41d7610992a09745809fb19fdb1ba3c17828a1bf49a0bf1f4e935e5776b6d5a541980b4fe482f82b228d9afd08c760f3bc76be16e

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cl (0.1.22)
+    cl (0.1.23)
       regstry (~> 1.0.3)
 
 GEM

data/README.md

@@ -18,7 +18,9 @@ Further documentation is available on [rubydoc.info](https://www.rubydoc.info/gi
 * [Command Registry](#command-registry)
 * [Runners](#runners)
 * [Command DSL](#command-dsl)
-  * [Description, Summary, Examples](#description-summary-examples)
+  * [Commands](#commands)
+    * [Description, Summary, Examples](#description-summary-examples)
+    * [Abstract](#abstract)
   * [Arguments](#arguments)
     * [Types](#types)
     * [Splat](#splat)
@@ -32,6 +34,8 @@ Further documentation is available on [rubydoc.info](https://www.rubydoc.info/gi
     * [Format](#format)
     * [Internal](#internal)
     * [Min and Max](#min-and-max)
+    * [Note](#note)
+    * [Secret](#secret)
     * [See Also](#see-also)
     * [Types](#types)
     * [Required Options](#required-options)
@@ -135,6 +139,13 @@ module One
 end
 ```
 
+Be aware that if you derive a common base command class from `Cl::Cmd` it
+should be declared as `abstract` in order to unregister itself from the command
+registry.
+
+This will prevent the runner to consider it as a runnable command, and omit it
+from help output. See [abstract](#abstract) for details.
+
 ### Runners
 
 Runners lookup the command to execute from the registry, by checking the
@@ -217,7 +228,11 @@ See the example [rakeish](blob/master/examples/rakeish) for more details.
 
 The DSL is defined on the class body.
 
-## Description, Summary, Examples
+### Commands
+
+Commands are classes that are derived from the base class `Cl::Cmd`.
+
+#### Description, Summary, Examples
 
 The description, summary, and examples are used in the help output.
 
@@ -234,16 +249,48 @@ module Owners
     examples <<~str
       Adding a single user to the group admins:
 
-        ./bin/owners add user --to admins
+        owners add user --to admins
 
       Adding a several users at once:
 
-        ./bin/owners add one two three --to admins
+        owners add one two three --to admins
     str
   end
 end
 ```
 
+#### Abstract
+
+Command base classes can be declared abstract in order to prevent them from
+being identified as a runnable command and to  omit them from help output.
+
+This is only relevant if a command base class is registered. See [Command
+Registry](#command-registry) for details.
+
+```ruby
+class Base < Cl::Cmd
+  abstract
+end
+
+class Add < Base
+end
+
+Cl.new('owners').help
+
+# Output:
+#
+#   Type "owners help COMMAND [SUBCOMMAND]" for more details:
+#
+#   owners add [options]
+
+Cl.new('owners').run(%w(base))
+
+# Error output:
+#
+#   Unknown command: base
+
+```
+
 ### Arguments
 
 Arguments can be declared like so:
@@ -677,6 +724,54 @@ Cl.new('owners').run(%w(add --retries 10))
 
 ```
 
+#### Note
+
+Options can have a note that will be printed in the help output.
+
+```ruby
+class Add < Cl::Cmd
+  opt '--to GROUP', note: 'needs to be a group'
+end
+
+Cl.new('owners').run(%w(add --help))
+
+# Usage: owners add [options]
+#
+# Options:
+#
+#   --to GROUP      type: string, note: needs to be a group
+#   --help          Get help on this command
+
+```
+
+#### Secret
+
+Options can be declared as secret.
+
+This makes it possible for client code to inspect if a given option is secret.
+Also, option values given by the user will be tainted, so client code can rely
+on this in order to, for example, obfuscate values from log output.
+
+```ruby
+class Add < Cl::Cmd
+  opt '--to GROUP'
+  opt '--password PASS', secret: true
+
+  def run
+    puts [:secret?, self.class.opts[:password].secret?].join(' ')
+    puts [:tainted?, password.tainted?].join(' ')
+  end
+end
+
+Cl.new('owners').run(%w(add --password pass))
+
+# Output:
+#
+#   secret? true
+#   tainted? true
+
+```
+
 #### See Also
 
 Options can refer to documentation using the `see` option. This will be printed

data/examples/readme/abstract

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+$: << File.expand_path('lib')
+
+require 'cl'
+
+class Base < Cl::Cmd
+  abstract
+end
+
+class Add < Base
+end
+
+Cl.new('owners').help
+
+# Output:
+#
+#   Type "owners help COMMAND [SUBCOMMAND]" for more details:
+#
+#   owners add [options]
+
+Cl.new('owners').run(%w(base))
+
+# Error output:
+#
+#   Unknown command: base

data/examples/readme/note

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+$: << File.expand_path('lib')
+
+require 'cl'
+
+class Add < Cl::Cmd
+  opt '--to GROUP', note: 'needs to be a group'
+end
+
+Cl.new('owners').run(%w(add --help))
+
+# Usage: owners add [options]
+#
+# Options:
+#
+#   --to GROUP      type: string, note: needs to be a group
+#   --help          Get help on this command

data/examples/readme/secret

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+$: << File.expand_path('lib')
+
+require 'cl'
+
+class Add < Cl::Cmd
+  opt '--to GROUP'
+  opt '--password PASS', secret: true
+
+  def run
+    puts [:secret?, self.class.opts[:password].secret?].join(' ')
+    puts [:tainted?, password.tainted?].join(' ')
+  end
+end
+
+Cl.new('owners').run(%w(add --password pass))
+
+# Output:
+#
+#   secret? true
+#   tainted? true

data/lib/cl.rb

@@ -8,14 +8,14 @@ class Cl
 
   # @overload initialize(ctx, name, opts)
   #   @param ctx  [Cl::Ctx] the current execution context (optional)
-  #   @param name [String] the program (executable) name (optional, defaults to $0)
+  #   @param name [String] the program (executable) name (optional, defaults to the last segment of $0)
   #   @param opts [Hash] options (optional)
   #   @option opts [Cl::Runner] :runner registry key for a runner (optional, defaults to :default)
   #   @option opts [Cl::Ui] :ui the ui for handling user interaction
   def initialize(*args)
     ctx   = args.shift if args.first.is_a?(Ctx)
     @opts = args.last.is_a?(Hash) ? args.pop : {}
-    @name = args.shift || $0
+    @name = args.shift || $0.split('/').last
     @ctx  = ctx || Ctx.new(name, opts)
   end
 

data/lib/cl/ctx.rb

@@ -9,11 +9,12 @@ class Cl
     def_delegators :ui, :puts, :stdout, :announce, :info, :notice, :warn,
       :error, :success, :cmd
 
-    attr_accessor :config, :ui
+    attr_accessor :config, :name, :ui
 
     def initialize(name, opts = {})
       @config = Config.new(name).to_h
       @ui = opts[:ui] || Ui.new(self, opts)
+      @name = name
     end
 
     def abort(error, *strs)

data/lib/cl/help.rb

@@ -7,7 +7,7 @@ class Cl
     end
 
     def help
-      args.any? ? Cmd.new(cmd).format : Cmds.new(cmds).format
+      args.any? ? Cmd.new(ctx, cmd).format : Cmds.new(ctx, cmds).format
     end
 
     private

data/lib/cl/help/cmd.rb

@@ -3,21 +3,15 @@ require 'cl/help/usage'
 
 class Cl
   class Help
-    class Cmd
+    class Cmd < Struct.new(:ctx, :cmd)
       include Regex
 
-      attr_reader :cmd
-
-      def initialize(cmd)
-        @cmd = cmd
-      end
-
       def format
         [usage, summary, description, arguments, options, common, examples].compact.join("\n\n")
       end
 
       def usage
-        "Usage: #{Usage.new(cmd).format}"
+        "Usage: #{Usage.new(ctx, cmd).format}"
       end
 
       def summary

data/lib/cl/help/cmds.rb

@@ -3,17 +3,15 @@ require 'cl/help/usage'
 
 class Cl
   class Help
-    class Cmds
-      HEAD = %(Type "#{$0.split('/').last} help COMMAND [SUBCOMMAND]" for more details:\n)
+    class Cmds < Struct.new(:ctx, :cmds)
+      HEAD = %(Type "%s help COMMAND [SUBCOMMAND]" for more details:\n)
 
-      attr_reader :cmds
-
-      def initialize(cmds)
-        @cmds = cmds
+      def format
+        [head, Table.new(list).format].join("\n")
       end
 
-      def format
-        [HEAD, Table.new(list).format].join("\n")
+      def head
+        HEAD % ctx.name
       end
 
       def list
@@ -21,7 +19,7 @@ class Cl
       end
 
       def format_cmd(cmd)
-        ["#{Usage.new(cmd).format}", cmd.summary]
+        ["#{Usage.new(ctx, cmd).format}", cmd.summary]
       end
     end
   end

data/lib/cl/help/usage.rb

@@ -1,19 +1,17 @@
 class Cl
   class Help
-    class Usage
-      attr_reader :cmd
-
-      def initialize(cmd)
-        @cmd = cmd
-      end
-
+    class Usage < Struct.new(:ctx, :cmd)
       def format
-        usage = [$0.split('/').last, name]
+        usage = [executable, name]
         usage += cmd.args.map(&:to_s) # { |arg| "[#{arg}]" }
         usage << '[options]' if opts?
         usage.join(' ')
       end
 
+      def executable
+        ctx.name
+      end
+
       def name
         cmd.registry_key.to_s.gsub(':', ' ')
       end

data/lib/cl/version.rb

@@ -1,3 +1,3 @@
 class Cl
-  VERSION = '0.1.23'
+  VERSION = '0.1.24'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cl
 version: !ruby/object:Gem::Version
-  version: 0.1.23
+  version: 0.1.24
 platform: ruby
 authors:
 - Sven Fuchs
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-24 00:00:00.000000000 Z
+date: 2019-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: regstry
@@ -43,6 +43,7 @@ files:
 - examples/gem
 - examples/heroku
 - examples/rakeish
+- examples/readme/abstract
 - examples/readme/alias
 - examples/readme/arg
 - examples/readme/arg_array
@@ -57,12 +58,14 @@ files:
 - examples/readme/example
 - examples/readme/format
 - examples/readme/internal
+- examples/readme/note
 - examples/readme/opts
 - examples/readme/opts_block
 - examples/readme/range
 - examples/readme/required
 - examples/readme/requireds
 - examples/readme/requires
+- examples/readme/secret
 - examples/readme/see
 - examples/readme/type
 - lib/cl.rb