Merge pull request #680 from bashly-framework/add/support-for-disabling-help-flag

Add support for captuing `--help` when using `catch_all`

Author: DannyBen

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "September 2025" "Version 0.1.0" "Sample application"
+.TH "download" "1" "November 2025" "Version 0.1.0" "Sample application"
 .SH NAME
 \f[B]download\f[R] \- Sample application
 .SH SYNOPSIS

examples/render-mandoc/docs/download.md

@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% September 2025
+% November 2025
 
 NAME
 ==================================================

lib/bashly/config_validator.rb

@@ -35,6 +35,7 @@ def assert_catch_all_hash(key, value)
       assert_string "#{key}.label", value['label']
       assert_optional_string "#{key}.help", value['help']
       assert_boolean "#{key}.required", value['required']
+      assert_boolean "#{key}.catch_help", value['catch_help']
     end
 
     def assert_default_command(key, value)

lib/bashly/script/catch_all.rb

@@ -3,7 +3,7 @@ module Script
     class CatchAll
       class << self
         def option_keys
-          @option_keys ||= %i[label help required]
+          @option_keys ||= %i[label help required catch_help]
         end
 
         def from_config(config)
@@ -13,7 +13,7 @@ def from_config(config)
           when String
             { label: config }
           when Hash
-            { label: config['label'], help: config['help'], required: config['required'] }
+            config.transform_keys(&:to_sym).slice(*option_keys)
           else
             {}
           end
@@ -22,11 +22,12 @@ def from_config(config)
         end
       end
 
-      def initialize(label: nil, help: nil, required: false, enabled: true)
+      def initialize(label: nil, help: nil, required: false, catch_help: false, enabled: true)
         @label = label
         @help = help
         @required = required
         @enabled = enabled
+        @catch_help = catch_help
       end
 
       def enabled?
@@ -45,6 +46,10 @@ def required?
         @required
       end
 
+      def catch_help?
+        @catch_help
+      end
+
       def usage_string
         return nil unless enabled?
 

lib/bashly/script/introspection/flags.rb

@@ -16,6 +16,13 @@ def flags
           end
         end
 
+        # Returns true if there is at least one fixed flag (--version / --help)
+        # Root command always has --version and subcommands always have --help
+        # except when it is consumed by catch_all
+        def fixed_flags?
+          root_command? || !catch_all.catch_help?
+        end
+
         # Returns true if this command's flags should be considered as gloal
         # flags, and cascade to subcommands
         def global_flags?

lib/bashly/views/command/fixed_flags_filter.gtx

@@ -12,12 +12,14 @@ if root_command?
   > 
 end
 
-= (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
->       long_usage=yes
->       <%= function_name %>_usage
->       exit
->       ;;
-> 
+unless catch_all.catch_help?
+  = (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
+  >       long_usage=yes
+  >       <%= function_name %>_usage
+  >       exit
+  >       ;;
+  > 
+end
 
 if global_flags?
   flags.each do |flag|

lib/bashly/views/command/long_usage.gtx

@@ -1,15 +1,7 @@
 = view_marker
 
 > if [[ -n "$long_usage" ]]; then
-options_caption = strings[:options]
-if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
-  options_caption = strings[:global_options]
-end
-
->   printf "%s\n" "{{ options_caption.color(:caption) }}"
->
-= render(:usage_flags).indent 2 if flags.any?
-= render(:usage_fixed_flags).indent 2
+= render(:usage_options).indent 2 if flags.any? || fixed_flags?
 = render(:usage_args).indent 2 if args.any? or catch_all.help
 = render(:usage_environment_variables).indent 2 if environment_variables.any?
 = render(:usage_examples).indent 2 if examples

lib/bashly/views/command/usage_fixed_flags.gtx

@@ -1,13 +1,15 @@
 = view_marker
 
-if short_flag_exist?("-h")
-  > printf "  %s\n" "{{ '--help'.color(:flag) }}"
-else
-  > printf "  %s\n" "{{ '--help, -h'.color(:flag) }}"
-end
+unless catch_all.catch_help?
+  if short_flag_exist?("-h")
+    > printf "  %s\n" "{{ '--help'.color(:flag) }}"
+  else
+    > printf "  %s\n" "{{ '--help, -h'.color(:flag) }}"
+  end
 
-> printf "    {{ strings[:help_flag_text] }}\n"
-> echo
+  > printf "    {{ strings[:help_flag_text] }}\n"
+  > echo
+end
 
 if root_command?
   if short_flag_exist?("-v")

lib/bashly/views/command/usage_options.gtx

@@ -0,0 +1,11 @@
+= view_marker
+
+options_caption = strings[:options]
+if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
+  options_caption = strings[:global_options]
+end
+
+> printf "%s\n" "{{ options_caption.color(:caption) }}"
+>
+= render(:usage_flags) if flags.any?
+= render(:usage_fixed_flags)

schemas/bashly.json

@@ -683,6 +683,11 @@
               "description": "Whether the current argument or flag is required\nhttps://bashly.dev/configuration/command/#catch_all",
               "type": "boolean",
               "default": false
+            },
+            "catch_help": {
+              "description": "Whether to also disable the --help flag and catch it like any other\nhttps://bashly.dev/configuration/command/#catch_all",
+              "type": "boolean",
+              "default": false
             }
           },
           "additionalProperties": false