benry-cmdopt 2.0.2 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c4c465878a37b15c65090a251e576059ac389d2a3457379980e8bb353e43a97
-  data.tar.gz: e0607fa34db598eb81014b7ed63bebe82985ad20a9a311e7be6b0c6c52f01a88
+  metadata.gz: 9308d0182f3f4a17d45f3b7a1f212a4f5f2112f4084d725b2de05271a908bb1d
+  data.tar.gz: f9b8e9066b9857d2693382f03bcbeacdd040695287d426d8ef8c28cf242f1cd1
 SHA512:
-  metadata.gz: 01cc7b1487d89b9777478064f068c31b847038da6fda2841b9b59c0ee55fc9d62a4d3dac7eae5964c9b25fd0da5e52459c27cbb8eac0412293c0b4de8fb910d9
-  data.tar.gz: 934952f9cc686d6014c69034b7aa5810341266b627f5f22719da543baf9f38267cab4214a0aeae8315bb601bc72f96597d976896977c1151fff50c37fe8dce59
+  metadata.gz: e231075a8a9fdd99a0379390ebc1fae07c812f8229d1689e0b7f04b91d5c0c596122835dde000c3ba609681898c3048fa51d08232cd33d4b9df0bacbc22036c6
+  data.tar.gz: bcabe45f475efd7c95e989c9f7f2c9b61c65396b6373cbb0a68427ce10798a942c4af3cfd8ae66a34928c710b2cac24388d8848a6a1271ca40d3e9458a217898

data/CHANGES.md

@@ -2,6 +2,21 @@ CHANGES
 =======
 
 
+Release 2.2.0 (2023-10-28)
+--------------------------
+
+* [enhance] Define `SchemaItem#add_item()` which adds option item into the schema. This is for Benry-CmdApp framework.
+* [change] (EXPERIMENTAL) Make `desc`, `detail`, `hidden`, `important`, `tag` attrubtes of `SchemaItem` object to be writable. This is for Benry-CmdApp framework.
+
+
+Release 2.1.0 (2023-10-15)
+--------------------------
+
+* [enhance] Add `hidden: true` keyword argument to `Benry::Schema#add()` and `Benry::Facade#add()`. This keyword argument makes the option as hidden option.
+* [change] Option which name stars with '_' is now not regarded as hidden option. Use `hidden: true` instead.
+* [enhance] Add `important: (true|false)` keyword argument to `Benry::Schema#add()` and `Benry::Facade#add()`. This keyword argument makes help message of the option printed in decorated format.
+
+
 Release 2.0.2 (2023-10-12)
 --------------------------
 

data/README.md

@@ -1,6 +1,6 @@
 # Benry-CmdOpt
 
-($Release: 2.0.2 $)
+($Release: 2.2.0 $)
 
 
 
@@ -38,6 +38,7 @@ Benry-CmdOpt requires Ruby >= 2.3.
   * [Global Options with Sub-Commands](#global-options-with-sub-commands)
   * [Detailed Description of Option](#detailed-description-of-option)
   * [Option Tag](#option-tag)
+  * [Important Options](#important-options)
   * [Not Supported](#not-supported)
 * [Internal Classes](#internal-classes)
 * [License and Copyright](#license-and-copyright)
@@ -470,22 +471,20 @@ p options   #=> {:lib=>["foo", "bar", "baz"]}
 
 Benry-CmdOpt regards the following options as hidden.
 
-* Key name starts with `_` (for example `:_debug`).
+* Keyword argument `hidden: true` is passed to `.add()` method.
 * Or description is nil.
 
-The former is better than the latter, because even hidden option should have its own description.
-
-These hidden options are not included in help message.
+Hidden options are not included in help message.
 
 ```ruby
 require 'benry/cmdopt'
 cmdopt = Benry::CmdOpt.new
-cmdopt.add(:help , '-h', "help message")
-cmdopt.add(:debug, '-D', nil)       # hidden (because description is nil)
-cmdopt.add(:_log , '-L', "logging") # hidden (because key starts with '_')
+cmdopt.add(:help   , '-h', "help message")
+cmdopt.add(:logging, '-L', "logging", hidden: true)  # hidden
+cmdopt.add(:debug  , '-D', nil)                      # hidden (desc is nil)
 puts cmdopt.to_s()
 
-### output (neither '-D' nor '-L' is shown because hidden options)
+### output (neither '-L' nor '-D' is shown because hidden options)
 #  -h             : help message
 ```
 
@@ -497,8 +496,8 @@ puts cmdopt.to_s(all: true)   # or: cmdopt.to_s(nil, all: true)
 
 ### output
 #  -h             : help message
-#  -D             :
 #  -L             : logging
+#  -D             : 
 ```
 
 
@@ -613,11 +612,37 @@ end
 ```
 
 
+### Important Options
+
+You can specify that the option is important or not.
+Pass `important: true` or `important: false` keyword argument to `#add()` method of `Benry::CmdOpt` or `Benry::CmdOpt::Schema` object.
+
+The help message of options is decorated according to value of `important:` keyword argument.
+
+* Printed in bold font when `important: true` specified to the option.
+* Printed in gray color when `important: false` specified to the option.
+
+```ruby
+require 'benry/cmdopt'
+
+cmdopt = Benry::CmdOpt.new()
+cmdopt.add(:help   , "-h", "help message")
+cmdopt.add(:verbose, "-v", "verbose mode", important: true)   # !!!
+cmdopt.add(:debug  , "-D", "debug mode"  , important: false)  # !!!
+puts cmdopt.option_help()
+
+## output:
+#  -h       : help message
+#  -v       : verbose mode      # bold font
+#  -D       : debug mode        # gray color
+```
+
+
 ### Not Supported
 
-* default value
+* default value when the option not specified in command-line
 * `--no-xxx` style option
-* bash/zsh completion
+* bash/zsh completion (may be supported in the future)
 * I18N of error message (may be supported in the future)
 
 

data/benry-cmdopt.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name            = "benry-cmdopt"
-  spec.version         = "$Release: 2.0.2 $".split()[1]
+  spec.version         = "$Release: 2.2.0 $".split()[1]
   spec.author          = "kwatch"
   spec.email           = "kwatch@gmail.com"
   spec.platform        = Gem::Platform::RUBY

data/doc/benry-cmdopt.html

@@ -21,7 +21,7 @@
   <ul class="nav">
   </ul>
 </nav>
-<p>($Release: 2.0.2 $)</p>
+<p>($Release: 2.2.0 $)</p>
 <section class="section" id="whats-this">
 <h2>What's This?</h2>
 <p>Benry-CmdOpt is a command option parser library, like <code>optparse.rb</code>
@@ -53,6 +53,7 @@ and easy to understahnd.</p>
 <li><a href="#global-options-with-sub-commands">Global Options with Sub-Commands</a></li>
 <li><a href="#detailed-description-of-option">Detailed Description of Option</a></li>
 <li><a href="#option-tag">Option Tag</a></li>
+<li><a href="#important-options">Important Options</a></li>
 <li><a href="#not-supported">Not Supported</a></li>
 </ul></li>
 <li><a href="#internal-classes">Internal Classes</a></li>
@@ -462,20 +463,19 @@ p options   #=&gt; <strong>{:lib=&gt;["foo", "bar", "baz"]}</strong>
 <h3>Hidden Option</h3>
 <p>Benry-CmdOpt regards the following options as hidden.</p>
 <ul>
-<li>Key name starts with <code>_</code> (for example <code>:_debug</code>).</li>
+<li>Keyword argument <code>hidden: true</code> is passed to <code>.add()</code> method.</li>
 <li>Or description is nil.</li>
 </ul>
-<p>The former is better than the latter, because even hidden option should have its own description.</p>
-<p>These hidden options are not included in help message.</p>
+<p>Hidden options are not included in help message.</p>
 <pre class="language-ruby">
 require 'benry/cmdopt'
 cmdopt = Benry::CmdOpt.new
-cmdopt.add(:help , '-h', "help message")
-cmdopt.add(:debug, '-D', <strong>nil</strong>)       # hidden (because description is nil)
-cmdopt.add(<strong>:_log</strong> , '-L', "logging") # hidden (because key starts with '_')
+cmdopt.add(:help   , '-h', "help message")
+cmdopt.add(:logging, '-L', "logging", <strong>hidden: true</strong>)  # hidden
+cmdopt.add(:debug  , '-D', <strong>nil</strong>)                      # hidden (desc is nil)
 puts cmdopt.to_s()
 
-### output (neither '-D' nor '-L' is shown because hidden options)
+### output (neither '-L' nor '-D' is shown because hidden options)
 #  -h             : help message
 </pre>
 <p>To show all options including hidden ones, add <code>all: true</code> to <code>cmdopt.to_s()</code>.</p>
@@ -485,8 +485,8 @@ puts cmdopt.to_s(<strong>all: true</strong>)   # or: cmdopt.to_s(nil, all: true)
 
 ### output
 #  -h             : help message
-#  <strong>-D             :</strong>
 #  <strong>-L             : logging</strong>
+#  <strong>-D             : </strong>
 </pre>
 </section>
 <section class="subsection" id="global-options-with-sub-commands">
@@ -591,12 +591,36 @@ end
 #version: <strong>tag=nil</strong>
 </pre>
 </section>
+<section class="subsection" id="important-options">
+<h3>Important Options</h3>
+<p>You can specify that the option is important or not.
+Pass <code>important: true</code> or <code>important: false</code> keyword argument to <code>#add()</code> method of <code>Benry::CmdOpt</code> or <code>Benry::CmdOpt::Schema</code> object.</p>
+<p>The help message of options is decorated according to value of <code>important:</code> keyword argument.</p>
+<ul>
+<li>Printed in bold font when <code>important: true</code> specified to the option.</li>
+<li>Printed in gray color when <code>important: false</code> specified to the option.</li>
+</ul>
+<pre class="language-ruby">
+require 'benry/cmdopt'
+
+cmdopt = Benry::CmdOpt.new()
+cmdopt.add(:help   , "-h", "help message")
+cmdopt.add(:verbose, "-v", "verbose mode", <strong>important: true</strong>)   # !!!
+cmdopt.add(:debug  , "-D", "debug mode"  , <strong>important: false</strong>)  # !!!
+puts cmdopt.option_help()
+
+## output:
+#  -h       : help message
+#  -v       : verbose mode      # bold font
+#  -D       : debug mode        # gray color
+</pre>
+</section>
 <section class="subsection" id="not-supported">
 <h3>Not Supported</h3>
 <ul>
-<li>default value</li>
+<li>default value when the option not specified in command-line</li>
 <li><code>--no-xxx</code> style option</li>
-<li>bash/zsh completion</li>
+<li>bash/zsh completion (may be supported in the future)</li>
 <li>I18N of error message (may be supported in the future)</li>
 </ul>
 </section>

data/lib/benry/cmdopt.rb

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 ###
-### $Release: 2.0.2 $
+### $Release: 2.2.0 $
 ### $Copyright: copyright(c) 2021 kwatch@gmail.com $
 ### $License: MIT License $
 ###
@@ -23,7 +23,7 @@ end
 module Benry::CmdOpt
 
 
-  VERSION = '$Release: 2.0.2 $'.split()[1]
+  VERSION = '$Release: 2.2.0 $'.split()[1]
 
 
   def self.new()
@@ -40,11 +40,11 @@ module Benry::CmdOpt
 
     attr_reader :schema
 
-    def add(key, optdef, desc, *rest, type: nil, rexp: nil, pattern: nil, enum: nil, range: nil, value: nil, detail: nil, tag: nil, &callback)
+    def add(key, optdef, desc, *rest, type: nil, rexp: nil, pattern: nil, enum: nil, range: nil, value: nil, detail: nil, hidden: nil, important: nil, tag: nil, &callback)
       rexp ||= pattern    # for backward compatibility
       #; [!vmb3r] defines command option.
       #; [!71cvg] type, rexp, enum, and range are can be passed as positional args as well as keyword args.
-      @schema.add(key, optdef, desc, *rest, type: type, rexp: rexp, enum: enum, range: range, value: value, detail: detail, tag: tag, &callback)
+      @schema.add(key, optdef, desc, *rest, type: type, rexp: rexp, enum: enum, range: range, value: value, detail: detail, hidden: hidden, important: important, tag: tag, &callback)
       #; [!tu4k3] returns self.
       self
     end
@@ -103,7 +103,7 @@ module Benry::CmdOpt
       self
     end
 
-    def add(key, optdef, desc, *rest, type: nil, rexp: nil, pattern: nil, enum: nil, range: nil, value: nil, detail: nil, tag: nil, &callback)
+    def add(key, optdef, desc, *rest, type: nil, rexp: nil, pattern: nil, enum: nil, range: nil, value: nil, detail: nil, hidden: nil, important: nil, tag: nil, &callback)
       rexp ||= pattern    # for backward compatibility
       #; [!kuhf9] type, rexp, enum, and range are can be passed as positional args as well as keyword args.
       rest.each do |x|
@@ -137,11 +137,17 @@ module Benry::CmdOpt
       end
       #; [!yht0v] keeps command option definitions.
       item = SchemaItem.new(key, optdef, desc, short, long, param, required,
-                 type: type, rexp: rexp, enum: enum, range: range, value: value, detail: detail, tag: tag, &callback)
+                 type: type, rexp: rexp, enum: enum, range: range, value: value, detail: detail, hidden: hidden, important: important, tag: tag, &callback)
       @items << item
       item
     end
 
+    def add_item(item)
+      #; [!a693h] adds option item into current schema.
+      @items << item
+      self
+    end
+
     def option_help(width_or_format=nil, all: false)
       #; [!0aq0i] can take integer as width.
       #; [!pcsah] can take format string.
@@ -157,10 +163,16 @@ module Benry::CmdOpt
       #; [!to1th] includes all option help when `all` is true.
       #; [!a4qe4] option should not be hidden if description is empty string.
       sb = []
-      width = nil; indent = nil
-      each_option_and_desc(all: all) do |opt, desc, detail|
-        sb << format % [opt, desc || ""] << "\n"
+      width = nil; indent = nil; color_p = $stdout.tty?
+      @items.each do |item|
+        next if ! all && item.hidden?
+        #; [!jrwb6] decorates help message according to `important:` value of option.
+        #; [!9nlfb] not decorate help message when stdout is not a tty.
+        s = format % [item.optdef, item.desc || ""]
+        s = _decorate_str(s, item.important?) if color_p
+        sb << s << "\n"
         #; [!848rm] supports multi-lines help message.
+        detail = item.detail
         if detail
           width  ||= (format % ['', '']).length
           indent ||= ' ' * width
@@ -276,12 +288,20 @@ module Benry::CmdOpt
       return short_p ? 8 : long_p ? 20 : 14
     end
 
+    def _decorate_str(str, important)
+      case important
+      when true  ; return "\e[1m#{str}\e[0m"  # bold
+      when false ; return "\e[2m#{str}\e[0m"  # gray
+      else       ; return str
+      end
+    end
+
   end
 
 
   class SchemaItem    # avoid Struct
 
-    def initialize(key, optdef, desc, short, long, param, required, type: nil, rexp: nil, pattern: nil, enum: nil, range: nil, detail: nil, value: nil, tag: nil, &callback)
+    def initialize(key, optdef, desc, short, long, param, required, type: nil, rexp: nil, pattern: nil, enum: nil, range: nil, detail: nil, value: nil, hidden: nil, important: nil, tag: nil, &callback)
       rexp ||= pattern    # for backward compatibility
       _init_validation(param, required, type, rexp, enum, range, value)
       @key      = key       unless nil == key
@@ -297,6 +317,8 @@ module Benry::CmdOpt
       @range    = range     unless nil == range
       @detail   = detail    unless nil == detail
       @value    = value     unless nil == value
+      @hidden   = hidden    unless nil == hidden
+      @important = important unless nil == important
       @tag      = tag       unless nil == tag
       @callback = callback  unless nil == callback
       #; [!nn4cp] freezes enum object.
@@ -304,6 +326,7 @@ module Benry::CmdOpt
     end
 
     attr_reader :key, :optdef, :desc, :short, :long, :param, :type, :rexp, :enum, :range, :detail, :value, :tag, :callback
+    attr_writer :desc, :detail, :hidden, :important, :tag    # !!experimental!!
     alias pattern rexp   # for backward compatibility
     alias help desc      # for backward compatibility
 
@@ -324,10 +347,18 @@ module Benry::CmdOpt
     end
 
     def hidden?()
+      #; [!no6ov] returns true if @hidden is true.
+      #; [!ej8ot] returns false if @hidden is false.
+      return @hidden if @hidden != nil
       #; [!h0uxs] returns true if desc is nil.
-      #; [!su00g] returns true if key starts with '_'.
       #; [!28vzx] returns false if else.
-      return @desc == nil || @key.to_s.start_with?('_')
+      return @desc == nil
+    end
+
+    def important?()
+      #; [!ua8kt] returns true/false if `important:` kwarg passed to constructor.
+      #; [!hz9sx] returns nil if `important:` kwarg not passed to constructor.
+      return @important
     end
 
     def validate_and_convert(val, optdict)

data/test/cmdopt_test.rb

@@ -256,6 +256,19 @@ Oktest.scope do
     end
 
 
+    topic '#add_item()' do
+
+      spec "[!a693h] adds option item into current schema." do
+        item = Benry::CmdOpt::SchemaItem.new(:quiet, "-q", "quiet", "q", nil, nil, false)
+        sc = Benry::CmdOpt::Schema.new
+        sc.add_item(item)
+        ok {sc.to_s} == <<"END"
+  -q       : quiet
+END
+      end
+
+    end
+
     topic '#option_help()' do
 
       before do
@@ -342,13 +355,49 @@ END
       spec "[!a4qe4] option should not be hidden if description is empty string." do
         sc = Benry::CmdOpt::Schema.new
         sc.add(:debug , "-D", nil)       # hidden
-        sc.add(:_trace, "-T", "trace")   # hidden
+        sc.add(:trace, "-T", "trace", hidden: true)   # hidden
         sc.add(:what  , "-W", "")        # NOT hidden!
         ok {sc.option_help()} == <<END
   -W             : 
 END
       end
 
+      fixture :schema_with_importance do
+        sc = Benry::CmdOpt::Schema.new
+        sc.add(:help  , "-h, --help" , "help message")
+        sc.add(:trace , "-T, --trace", "trace"      , important: true)
+        sc.add(:debug , "-D, --debug", "debug mode" , important: false)
+        sc.add(:quiet , "-q, --quiet", "quiet mode")
+        sc
+      end
+
+      spec "[!jrwb6] decorates help message according to `important:` value of option." do
+        |schema_with_importance|
+        sc = schema_with_importance
+        ok {sc.option_help()} == <<END
+  -h, --help     : help message
+\e[1m  -T, --trace    : trace\e[0m
+\e[2m  -D, --debug    : debug mode\e[0m
+  -q, --quiet    : quiet mode
+END
+      end
+
+      spec "[!9nlfb] not decorate help message when stdout is not a tty." do
+        |schema_with_importance|
+        sc = schema_with_importance
+        output = nil
+        capture_sio() {
+          ok {$stdout}.NOT.tty?
+          output = sc.option_help()
+        }
+        ok {output} == <<END
+  -h, --help     : help message
+  -T, --trace    : trace
+  -D, --debug    : debug mode
+  -q, --quiet    : quiet mode
+END
+      end
+
     end
 
 
@@ -445,7 +494,7 @@ END
         sc.add(:help, "-h, --help", "show help message")
         sc.add(:version, "    --version", "print version")
         sc.add(:debug  , "-d, --debug"  , nil)            # hidden
-        sc.add(:_DEBUG , "-D, --DEBUG"  , "debug mode")   # hidden
+        sc.add(:DEBUG  , "-D, --DEBUG"  , "debug mode", hidden: true)   # hidden
         @schema = sc
       end
 
@@ -532,7 +581,7 @@ END
       spec "[!icvm1] ignores hidden items if 'all: false' kwarg specified." do
         schema = Benry::CmdOpt::Schema.new
         schema.add(:debug , "-D", nil)
-        schema.add(:_trace, "-T", "trace")
+        schema.add(:trace, "-T", "trace", hidden: true)
         ok {schema.empty?()} == false
         ok {schema.empty?(all: true)} == false
         ok {schema.empty?(all: false)} == true
@@ -898,15 +947,19 @@ END
 
     topic '#hidden?()' do
 
-      spec "[!h0uxs] returns true if desc is nil." do
-        desc = nil
-        item = Benry::CmdOpt::SchemaItem.new(:debug, "-D", desc, "D", nil, nil, nil)
+      spec "[!no6ov] returns true if @hidden is true." do
+        item = Benry::CmdOpt::SchemaItem.new(:debug, "-D", "debug mode", "D", nil, nil, nil, hidden: true)
         ok {item.hidden?} == true
       end
 
-      spec "[!su00g] returns true if key starts with '_'." do
-        desc = "debug mode"
-        item = Benry::CmdOpt::SchemaItem.new(:_debug, "-D", desc, "D", nil, nil, nil)
+      spec "[!ej8ot] returns false if @hidden is false." do
+        item = Benry::CmdOpt::SchemaItem.new(:debug, "-D", "debug mode", "D", nil, nil, nil, hidden: false)
+        ok {item.hidden?} == false
+      end
+
+      spec "[!h0uxs] returns true if desc is nil." do
+        desc = nil
+        item = Benry::CmdOpt::SchemaItem.new(:debug, "-D", desc, "D", nil, nil, nil)
         ok {item.hidden?} == true
       end
 
@@ -919,6 +972,23 @@ END
     end
 
 
+    topic '#important?()' do
+
+      spec "[!ua8kt] returns true/false if `important:` kwarg passed to constructor." do
+        item1 = Benry::CmdOpt::SchemaItem.new(:debug, "-D", "debug mode", "D", nil, nil, nil, important: true)
+        ok {item1.important?} == true
+        item2 = Benry::CmdOpt::SchemaItem.new(:debug, "-D", "debug mode", "D", nil, nil, nil, important: false)
+        ok {item2.important?} == false
+      end
+
+      spec "[!hz9sx] returns nil if `important:` kwarg not passed to constructor." do
+        item3 = Benry::CmdOpt::SchemaItem.new(:debug, "-D", "debug mode", "D", nil, nil, nil)
+        ok {item3.important?} == nil
+      end
+
+    end
+
+
     topic '#validate_and_convert()' do
 
       def new_item(key, optstr, desc, short, long, param, required,
@@ -1520,7 +1590,7 @@ END
         @cmdopt.add(:help   , "-h, --help"        , "show help message")
         @cmdopt.add(:version, "    --version"     , "print version")
         @cmdopt.add(:debug  , "-D"                , nil)       # hidden option
-        @cmdopt.add(:_trace , "-T"                , "trace")   # hidden option
+        @cmdopt.add(:trace  , "-T"                , "trace", hidden: true)  # hidden option
       end
 
       spec "[!bw9qx] yields each option definition string and help message." do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: benry-cmdopt
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.2.0
 platform: ruby
 authors:
 - kwatch
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-12 00:00:00.000000000 Z
+date: 2023-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oktest