Merge pull request #236 from DannyBen/refactor/expose

Refactor `command.expose` to show subcommands without `--help` when set to `always`

Author: DannyBen

examples/commands-expose/README.md

@@ -26,8 +26,8 @@ commands:
   help: Config management commands
 
   # Setting `expose` to true will show the summary of the subcommands when
-  # running the help for the parent command. In this case, `config edit` and
-  # `config show` will be displayed when running `cli --help`.
+  # using `cli --help` for the parent command. In this case, `config edit` and
+  # `config show` will be displayed.
   expose: true
   commands:
   - name: edit
@@ -38,9 +38,12 @@ commands:
 - name: server
   help: Server management commands
 
+  # Setting `expose` to `always` will also show the summary of the subcommands
+  # when running `cli` without arguments.
+  expose: always
+
   # Adding a `group` works well with `expose`. In this case, `server start` and
   # `server stop` will be listed under `Cluster Commands`.
-  expose: true
   group: Cluster
 
   commands:
@@ -81,6 +84,8 @@ Commands:
 
 Cluster Commands:
   server           Server management commands
+  server start     Start the server
+  server stop      Stop the server
   container        Container management commands
 
 

examples/commands-expose/src/bashly.yml

@@ -8,8 +8,8 @@ commands:
   help: Config management commands
 
   # Setting `expose` to true will show the summary of the subcommands when
-  # running the help for the parent command. In this case, `config edit` and
-  # `config show` will be displayed when running `cli --help`.
+  # using `cli --help` for the parent command. In this case, `config edit` and
+  # `config show` will be displayed.
   expose: true
   commands:
   - name: edit
@@ -20,9 +20,12 @@ commands:
 - name: server
   help: Server management commands
 
+  # Setting `expose` to `always` will also show the summary of the subcommands
+  # when running `cli` without arguments.
+  expose: always
+
   # Adding a `group` works well with `expose`. In this case, `server start` and
   # `server stop` will be listed under `Cluster Commands`.
-  expose: true
   group: Cluster
 
   commands:

lib/bashly/config_validator.rb

@@ -41,6 +41,11 @@ def assert_extensible(key, value)
         "#{key} must be a boolean or a string" 
     end
 
+    def assert_expose(key, value)
+      return unless value
+      assert [true, false, nil, 'always'].include?(value), "#{key} must be a boolean, or the string 'always'" 
+    end
+
     def assert_arg(key, value)
       assert_hash key, value, Script::Argument.option_keys
       assert_string "#{key}.name", value['name']
@@ -117,7 +122,7 @@ def assert_command(key, value)
 
       assert_boolean "#{key}.private", value['private']
       assert_boolean "#{key}.default", value['default']
-      assert_boolean "#{key}.expose", value['expose']
+      assert_expose "#{key}.expose", value['expose']
       assert_version "#{key}.version", value['version']
       assert_catch_all "#{key}.catch_all", value['catch_all']
       assert_string_or_array "#{key}.alias", value['alias']

lib/bashly/script/command.rb

@@ -86,7 +86,7 @@ def command_help_data
           command.public_commands.each do |subcommand|
             result[command.group_string]["#{command.name} #{subcommand.name}"] = {
               summary: subcommand.summary_string,
-              extended: true
+              help_only: command.expose != 'always'
             }
           end
         end

lib/bashly/views/command/usage_commands.erb

@@ -3,7 +3,7 @@
 % command_help_data.each do |group, commands|
 printf "<%= group %>\n"
 % commands.each do |command, info|
-% if info[:extended]
+% if info[:help_only]
 [[ -n $long_usage ]] && echo "  <%= command.ljust maxlen %>   <%= info[:summary] %>"
 % else
 echo "  <%= command.ljust maxlen %>   <%= info[:summary] %>"

spec/approvals/examples/commands-expose

@@ -24,6 +24,8 @@ Commands:
 
 Cluster Commands:
   server           Server management commands
+  server start     Start the server
+  server stop      Stop the server
   container        Container management commands
 
 + ./cli -h

spec/approvals/script/command/exposed_commands

@@ -6,24 +6,24 @@
     :summary: Config management commands
   config edit:
     :summary: Edit config file
-    :extended: true
+    :help_only: false
   config show:
     :summary: Show config file
-    :extended: true
+    :help_only: false
 'Cluster Commands:':
   server:
     :summary: Server management commands
   server start:
     :summary: Start the server
-    :extended: true
+    :help_only: true
   server stop:
     :summary: Stop the server
-    :extended: true
+    :help_only: true
   container:
     :summary: Container management commands
   container exec:
     :summary: Run a command in the container
-    :extended: true
+    :help_only: true
   container down:
     :summary: Terminate a container
-    :extended: true
+    :help_only: true

spec/approvals/validations/command_expose_not_boolean renamed to spec/approvals/validations/command_expose_invalid_string

@@ -1 +1 @@
-#<Bashly::ConfigurationError: root.commands[0].expose must be a boolean>
+#<Bashly::ConfigurationError: root.commands[0].expose must be a boolean, or the string 'always'>

spec/approvals/validations/command_expose_invalid_type

@@ -0,0 +1 @@
+#<Bashly::ConfigurationError: root.commands[0].expose must be a boolean, or the string 'always'>

spec/fixtures/script/commands.yml

@@ -147,7 +147,7 @@
     help: Start a new project
   - name: config
     help: Config management commands
-    expose: true
+    expose: always
     commands:
     - name: edit
       help: Edit config file