Merge pull request #519 from DannyBen/change/global-options-caption

Add 'Global Options' caption when appropriate
DannyBen · Apr 23, 2024 · 83e49b2 · 83e49b2
2 parents 0301e27 + 6592666
commit 83e49b2
Show file tree

Hide file tree

Showing 11 changed files with 47 additions and 41 deletions.
diff --git a/examples/catch-all/src/root_command.sh b/examples/catch-all/src/root_command.sh
diff --git a/examples/command-default-force/README.md b/examples/command-default-force/README.md
@@ -46,7 +46,7 @@ commands:
 tester - Sample application that uses the forced default command option
 
 Usage:
-  tester COMMAND
+  tester [COMMAND]
   tester [COMMAND] --help | -h
   tester --version | -v
 

diff --git a/examples/command-paths/README.md b/examples/command-paths/README.md
@@ -123,7 +123,7 @@ Commands:
   image       Image commands
   ps          List containers
 
-Options:
+Global Options:
   --debug, -d
     Enable debug mode
 

diff --git a/examples/docker-like/README.md b/examples/docker-like/README.md
@@ -107,7 +107,7 @@ Commands:
   image       Image commands
   ps          List containers
 
-Options:
+Global Options:
   --debug, -d
     Enable debug mode
 

diff --git a/examples/render-mandoc/README.md b/examples/render-mandoc/README.md
@@ -102,7 +102,7 @@ ISSUE TRACKER
 AUTHORS
        Lana Lang.
 
-Version 0.1.0                     March 2024                       download(1)
+Version 0.1.0                     April 2024                       download(1)
 
 
 ````

diff --git a/lib/bashly/libraries/strings/strings.yml b/lib/bashly/libraries/strings/strings.yml
@@ -4,6 +4,7 @@
 # Usage captions
 usage: "Usage:"
 options: "Options:"
+global_options: "Global Options:"
 arguments: "Arguments:"
 commands: "Commands:"
 examples: "Examples:"

diff --git a/lib/bashly/views/command/long_usage.gtx b/lib/bashly/views/command/long_usage.gtx
@@ -1,7 +1,8 @@
 = view_marker
 
 > if [[ -n $long_usage ]]; then
->   printf "%s\n" "{{ strings[:options].color(:caption) }}"
+options_caption = public_commands.any? && public_flags.any? ? strings[:global_options] : strings[:options]
+>   printf "%s\n" "{{ options_caption.color(:caption) }}"
 >
 = render(:usage_flags).indent 2 if public_flags.any?
 = render(:usage_fixed_flags).indent 2

diff --git a/schemas/strings.json b/schemas/strings.json
@@ -1,208 +1,215 @@
 {
     "$schema": "https://json.schemastore.org/metaschema-draft-07-unofficial-strict.json",
     "title": "strings",
-    "description": "Strings of the current application\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+    "description": "Strings of the generated script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
     "type": "object",
     "properties": {
         "usage": {
             "title": "usage",
-            "description": "A usage caption of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The caption for the usage patterns\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "Usage:"
         },
         "options": {
             "title": "options",
-            "description": "An option caption of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The caption for the options section\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "type": "string",
+            "minLength": 1,
+            "default": "Options:"
+        },
+        "global_options": {
+            "title": "global_options",
+            "description": "The caption for the options section, when a command has flags and sub-commands\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "Options:"
         },
         "arguments": {
             "title": "arguments",
-            "description": "An argument caption of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The caption for the argument section\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "Arguments:"
         },
         "commands": {
             "title": "commands",
-            "description": "A command caption of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The caption for the command section\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "Commands:"
         },
         "examples": {
             "title": "examples",
-            "description": "An example caption of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The caption for the examples section\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "Examples:"
         },
         "environment_variables": {
             "title": "environment variables",
-            "description": "An environment variable caption of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The caption for the environment variables section\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "Environment Variables:"
         },
         "group": {
             "title": "group",
-            "description": "A group caption of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The caption template for custom command groups\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "%{group} Commands:"
         },
         "command_alias": {
             "title": "command alias",
-            "description": "An alias helper of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The string template for a command alias\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "Alias: %{alias}"
         },
         "default_command_summary": {
             "title": "default command summary",
-            "description": "A default command summary helper of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The string template for the summary of a default command\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "%{summary} (default)"
         },
         "required": {
             "title": "required",
-            "description": "A required helper of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The string suffix for required arguments, flags, or commands\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "(required)"
         },
         "repeatable": {
             "title": "repeatable",
-            "description": "A repeatable helper of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The string suffix for repeatable arguments, flags, or commands\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "(repeatable)"
         },
         "default": {
             "title": "default",
-            "description": "A default helper of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The string template for a default argument or flag\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "Default: %{value}"
         },
         "allowed": {
             "title": "allowed",
-            "description": "An allowed helper of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The string template for the list of allowed values\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "Allowed: %{values}"
         },
         "help_flag_text": {
             "title": "help flag text",
-            "description": "A help flag of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The help message for --help\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "Show this help"
         },
         "version_flag_text": {
             "title": "version flag text",
-            "description": "A version flag of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The help message for --version\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "Show version number"
         },
         "flag_requires_an_argument": {
             "title": "flag requires an argument",
-            "description": "A missing flag argument error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for missing flag argument\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "%{name} requires an argument: %{usage}"
         },
         "invalid_argument": {
             "title": "invalid argument",
-            "description": "An invalid argument error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for invalid argument\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "invalid argument: %s"
         },
         "invalid_flag": {
             "title": "invalid flag",
-            "description": "An invalid option error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for invalid flag\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "invalid option: %s"
         },
         "invalid_command": {
             "title": "invalid command",
-            "description": "An invalid command error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for invalid command\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "invalid command: %s"
         },
         "conflicting_flags": {
             "title": "conflicting flags",
-            "description": "A conflicting options error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for conflicting flags\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "conflicting options: %s cannot be used with %s"
         },
         "missing_required_argument": {
             "title": "missing required argument",
-            "description": "A missing required argument error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for missing required argument\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "missing required argument: %{arg}\\nusage: %{usage}"
         },
         "missing_required_flag": {
             "title": "missing required flag",
-            "description": "A missing required flag error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for missing required flag\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "missing required flag: %{usage}"
         },
         "missing_required_environment_variable": {
             "title": "missing required environment variable",
-            "description": "A missing required environment variable error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for missing required environment variable\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "missing required environment variable: %{var}"
         },
         "missing_dependency": {
             "title": "missing dependency",
-            "description": "A missing dependency error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for missing dependency\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "missing dependency: %{dependency}"
         },
         "disallowed_flag": {
             "title": "disallowed flag",
-            "description": "A forbidden flag error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for forbidden flag\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "%{name} must be one of: %{allowed}"
         },
         "disallowed_argument": {
             "title": "disallowed argument",
-            "description": "A forbidden argument error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for forbidden argument\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "%{name} must be one of: %{allowed}"
         },
         "disallowed_environment_variable": {
             "title": "disallowed_environment_variable",
-            "description": "A forbidden environment variable error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for forbidden environment variable\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "%{name} environment variable must be one of: %{allowed}"
         },
         "unsupported_bash_version": {
             "title": "unsupported bash version",
-            "description": "An unsupported Bash version error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message for unsupported Bash version\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "bash version 4 or higher is required"
         },
         "validation_error": {
             "title": "validation error",
-            "description": "A validation error of the current script\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
+            "description": "The error message template for failed custom validation\nhttps://bashly.dannyb.co/advanced/strings/#custom-strings",
             "type": "string",
             "minLength": 1,
             "default": "validation error in %s:\\n%s"

diff --git a/spec/approvals/examples/command-paths b/spec/approvals/examples/command-paths
@@ -32,7 +32,7 @@ Commands:
   image       Image commands
   ps          List containers
 
-Options:
+Global Options:
   --debug, -d
     Enable debug mode
 

diff --git a/spec/approvals/examples/docker-like b/spec/approvals/examples/docker-like
@@ -32,7 +32,7 @@ Commands:
   image       Image commands
   ps          List containers
 
-Options:
+Global Options:
   --debug, -d
     Enable debug mode
 

diff --git a/spec/approvals/fixtures/global-flags b/spec/approvals/fixtures/global-flags
@@ -14,7 +14,7 @@ Usage:
 Commands:
   show   
 
-Options:
+Global Options:
   --alpha, -a
     Alpha
-Original file line number
+Diff line change
@@ Expand Up / @@ -102,7 +102,7 @@ ISSUE TRACKER @@
     AUTHORS
            Lana Lang.
-    Version 0.1.0                     March 2024                       download(1)
+    Version 0.1.0                     April 2024                       download(1)
     ````
@@ Expand Down @@