Add support for needy flags: flag.needs

examples/command-default-force/README.md

@@ -93,7 +93,7 @@ args: none
 tester all - Run all tests
 
 Usage:
-  tester all
+  tester [all]
   tester all --help | -h
 
 Options:

examples/command-default/README.md

@@ -102,6 +102,38 @@ args:
 - ${args[source]} = something
 
 
+````
+
+### `$ ./ftp upload`
+
+````shell
+missing required argument: SOURCE
+usage: ftp [upload] SOURCE
+
+
+````
+
+### `$ ./ftp upload -h`
+
+````shell
+ftp upload - Upload a file
+
+Alias: u
+
+Usage:
+  ftp [upload] SOURCE
+  ftp upload --help | -h
+
+Options:
+  --help, -h
+    Show this help
+
+Arguments:
+  SOURCE
+    File to upload
+
+
+
 ````
 
 ### `$ ./ftp upload something`

examples/conflicts/README.md

@@ -51,12 +51,15 @@ Usage:
 Options:
   --cache
     Enable cache
+    Conflicts: --no-cache
 
   --no-cache
     Disable cache
+    Conflicts: --cache, --fast
 
   --fast
     Run faster
+    Conflicts: --no-cache
 
   --help, -h
     Show this help

examples/needs/.gitignore

@@ -0,0 +1 @@
+cli

examples/needs/README.md

@@ -0,0 +1,113 @@
+# Needy Flags Example
+
+Demonstrates the use of needy flags that must be executed together.
+
+This example was generated with:
+
+```bash
+$ bashly init --minimal
+# ... now edit src/bashly.yml to match the example ...
+$ bashly generate
+```
+
+-----
+
+## `bashly.yml`
+
+````yaml
+name: cli
+help: Sample application to demonstrate the use of needy flags
+version: 0.1.0
+
+flags:
+- long: --add
+  short: -a
+  arg: alias
+  help: Alias to add
+  # When using --add, --command and --target must also be provided
+  needs: [--command, --target]
+
+- long: --command
+  short: -c
+  arg: command
+  help: Command for the alias
+  # Note that this relationship is marked on both sides
+  needs: [--add]
+
+- long: --target
+  short: -t
+  arg: target
+  help: Where to add the alias
+  needs: [--add]
+  allowed: [global, local]
+````
+
+
+
+## Output
+
+### `$ ./cli -h`
+
+````shell
+cli - Sample application to demonstrate the use of needy flags
+
+Usage:
+  cli [OPTIONS]
+  cli --help | -h
+  cli --version | -v
+
+Options:
+  --add, -a ALIAS
+    Alias to add
+    Needs: --command, --target
+
+  --command, -c COMMAND
+    Command for the alias
+    Needs: --add
+
+  --target, -t TARGET
+    Where to add the alias
+    Allowed: global, local
+    Needs: --add
+
+  --help, -h
+    Show this help
+
+  --version, -v
+    Show version number
+
+
+
+````
+
+### `$ ./cli --add deploy`
+
+````shell
+--add requires --command
+
+
+````
+
+### `$ ./cli --add deploy --command 'git push'`
+
+````shell
+--add requires --target
+
+
+````
+
+### `$ ./cli --add deploy --command 'git push' --target local`
+
+````shell
+# this file is located in 'src/root_command.sh'
+# you can edit it freely and regenerate (it will not be overwritten)
+args:
+- ${args[--add]} = deploy
+- ${args[--command]} = git push
+- ${args[--target]} = local
+
+
+````
+
+
+

examples/needs/src/bashly.yml

@@ -0,0 +1,26 @@
+name: cli
+help: Sample application to demonstrate the use of needy flags
+version: 0.1.0
+
+flags:
+- long: --add
+  short: -a
+  arg: alias
+  help: Alias to add
+  # When using --add, --command and --target must also be provided
+  needs: [--command, --target]
+
+- long: --command
+  short: -c
+  arg: command
+  help: Command for the alias
+  # Note that this relationship is marked on both sides
+  needs: [--add]
+
+- long: --target
+  short: -t
+  arg: target
+  help: Where to add the alias
+  needs: [--add]
+  allowed: [global, local]
+

examples/needs/src/root_command.sh

@@ -0,0 +1,3 @@
+echo "# this file is located in 'src/root_command.sh'"
+echo "# you can edit it freely and regenerate (it will not be overwritten)"
+inspect_args

examples/needs/test.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -x
+
+bashly generate
+
+### Try Me ###
+
+./cli -h
+./cli --add deploy
+./cli --add deploy --command 'git push'
+./cli --add deploy --command 'git push' --target local

examples/render-mandoc/README.md

@@ -102,7 +102,7 @@ ISSUE TRACKER
 AUTHORS
        Lana Lang.
 
-Version 0.1.0                      July 2024                       download(1)
+Version 0.1.0                     August 2024                      download(1)
 
 
 ````

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "July 2024" "Version 0.1.0" "Sample application"
+.TH "download" "1" "August 2024" "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
-% July 2024
+% August 2024
 
 NAME
 ==================================================

lib/bashly/docs/flag.yml

@@ -113,6 +113,29 @@ flag.long:
       short: -s
       help: Clone using SSH
 
+flag.needs:
+  help: Specify that this flag needs one or more additional flags. Use the long name of these needed flags.
+  url: https://bashly.dannyb.co/configuration/flag/#needs
+  example: |-
+    flags:
+    - long: --add
+      arg: alias
+
+      # When using --add, --command and --target must also be provided
+      needs: [--command, --target]
+
+    - long: --command
+      arg: command
+      help: Command for the alias
+
+      # Note that this relationship is marked on both sides
+      needs: [--add]
+
+    - long: --target
+      arg: target
+      help: Where to add the alias
+      needs: [--add]
+
 flag.private:
   help: Specify that this flag should not be displayed in the help text.
   url: https://bashly.dannyb.co/configuration/flag/#private

lib/bashly/libraries/render/mandoc/mandoc.gtx

@@ -127,6 +127,9 @@ if flags.any?
     if flag.conflicts
       > - Conflicts With: **{{ flag.conflicts.join(', ') }}**
     end
+    if flag.needs
+      > - Needs: **{{ flag.needs.join(', ') }}**
+    end
     >
   end
 end

lib/bashly/libraries/render/markdown/markdown.gtx

@@ -152,7 +152,8 @@ if flags.any?
   > ## Options
   >
   flags.each do |flag|
-    attributes = flag.required || flag.repeatable || flag.default || flag.allowed || flag.conflicts
+    attributes = flag.required || flag.repeatable || flag.default ||
+      flag.allowed || flag.conflicts || flag.needs
 
     > #### *{{ flag.usage_string }}*
     >
@@ -177,6 +178,9 @@ if flags.any?
       if flag.conflicts
         > | Conflicts With: | *{{ flag.conflicts.join(', ') }}*
       end
+      if flag.needs
+        > | Needs: | *{{ flag.needs.join(', ') }}*
+      end
       >
     end
   end

lib/bashly/libraries/strings/strings.yml

@@ -18,13 +18,16 @@ required: "(required)"
 repeatable: "(repeatable)"
 default: "Default: %{value}"
 allowed: "Allowed: %{values}"
+needs: "Needs: %{values}"
+conflicts: "Conflicts: %{values}"
 
 # Fixed flags help text
 help_flag_text: Show this help
 version_flag_text: Show version number
 
 # Error messages
 flag_requires_an_argument: "%{name} requires an argument: %{usage}"
+flag_needs_another: "%{name} needs %{need}"
 invalid_argument: "invalid argument: %s"
 invalid_flag: "invalid option: %s"
 invalid_command: "invalid command: %s"

lib/bashly/script/command.rb

@@ -286,6 +286,10 @@ def required_flags
         flags.select(&:required)
       end
 
+      def needy_flags
+        flags.select(&:needs)
+      end
+
       # Returns true if this is the root command (no parents)
       def root_command?
         parents.empty?

lib/bashly/script/flag.rb

@@ -1,3 +1,5 @@
+require 'shellwords'
+
 module Bashly
   module Script
     class Flag < Base
@@ -6,8 +8,8 @@ class Flag < Base
       class << self
         def option_keys
           @option_keys ||= %i[
-            allowed arg completions conflicts default help long repeatable
-            required short unique validate private
+            allowed arg completions conflicts default help long needs
+            repeatable required short unique validate private
           ]
         end
       end

lib/bashly/views/command/needy_flags_filter.gtx

@@ -0,0 +1,9 @@
+if needy_flags.any?
+  = view_marker
+
+  needy_flags.each do |flag|
+    = flag.render(:needs)
+  end
+
+  >
+end

lib/bashly/views/command/parse_requirements.gtx

@@ -13,6 +13,7 @@ end
 = render(:parse_requirements_while).indent 2
 = render(:required_args_filter).indent 2
 = render(:required_flags_filter).indent 2
+= render(:needy_flags_filter).indent 2
 = render(:catch_all_filter).indent 2
 = render(:default_assignments).indent 2
 = render(:validations).indent 2

lib/bashly/views/flag/needs.gtx

@@ -0,0 +1,22 @@
+if needs
+
+  = view_marker
+
+  if needs.count == 1
+    > if [[ -n ${args['{{ name }}']+x} ]] && [[ -z "${args[{{ needs.first }}]:-}" ]]; then
+    >   printf "%s\n" "{{ strings[:flag_needs_another] % { name: name, need: needs.first } }}" >&2
+    >   exit 1
+    > fi
+    >
+  else
+    > if [[ -n ${args['{{ name }}']+x} ]]; then
+    >   for need in {{ needs.join ' ' }}; do
+    >     if [[ -z "${args[$need]:-}" ]]; then
+    >       printf "%s\n" "{{ strings[:flag_needs_another] % { name: name, need: "$need" } }}" >&2
+    >       exit 1
+    >     fi
+    >   done
+    > fi
+    >
+  end
+end