Merge pull request #34 from DannyBen/next

Add flag.needs

Author: DannyBen

src/advanced/validations.md

@@ -5,8 +5,8 @@ order: 80
 
 # Custom Validations
 
-Bashly supports custom validation functions for your arguments, and flag
-arguments. This is how it works:
+Bashly supports custom validation functions for your arguments, flag
+arguments, and environment variables. This is how it works:
 
 1. In your bashly configuration file, arguments and flags (with arguments)
    may have a `validate: function_name` option.

src/configuration/command.md

@@ -345,4 +345,9 @@ as a "last resort" mechanism to help in solving more complex scenarios.
 
 Setting this to `true` on any command, will hide it from the command list.
 
+!!!success Tip
+To allow users to see private commands, see
+[Settings :icon-chevron-right: private_reveal_key](/usage/settings/#private_reveal_key)
+!!!
+
 [!button variant="primary" icon="code-review" text="Private Command Example"](https://github.com/DannyBen/bashly/tree/master/examples/command-private#readme)

src/configuration/environment-variable.md

@@ -71,6 +71,11 @@ environment variable is optional.
 Setting this to `true` on any environment variable, will hide it from the help
 text.
 
+!!!success Tip
+To allow users to see private environment variables, see
+[Settings :icon-chevron-right: private_reveal_key](/usage/settings/#private_reveal_key)
+!!!
+
 ### required
 
 [!badge Boolean]
@@ -85,3 +90,11 @@ Specify if this variable is required.
 
 Limit the allowed values to a specified whitelist. Can be used in conjunction
 with [`default`](#default) or [`required`](#required).
+
+### validate
+
+[!badge String]
+
+Apply a custom validation function.
+
+[!ref](/advanced/validations)

src/configuration/flag.md

@@ -142,7 +142,7 @@ Remember to set the [`arg`](#arg) name when using this option.
 [!badge Array of Strings]
 
 Specify that this flag is mutually exclusive with one or more other flags.
-The values of this array should be the long versions of the flags:
+The values of this array should be the long versions of the flags:  
 `conflicts: [--other, --another]`
 
 !!! Note
@@ -163,12 +163,33 @@ Remember to set the [`arg`](#arg) name when using this option.
 
 [!ref](/advanced/bash-completion.md)
 
+
+### needs
+
+[!badge Array of Strings]
+
+Specify that this flag needs one or more other flags when executed.
+The values of this array should be the long versions of the flags:  
+`needs: [--other, --another]`
+
+!!! Note
+This option should be specified on both sides of the requirement.
+!!!
+
+[!button variant="primary" icon="code-review" text="Needy Flags Example"](https://github.com/DannyBen/bashly/tree/master/examples/needs#readme)
+
+
 ### private
 
 [!badge Boolean]
 
 Setting this to `true` on any flag, will hide it from the help text.
 
+!!!success Tip
+To allow users to see private flags, see
+[Settings :icon-chevron-right: private_reveal_key](/usage/settings/#private_reveal_key)
+!!!
+
 ### repeatable
 
 [!badge Boolean]

src/examples.md

@@ -44,6 +44,7 @@ All examples are listed below for convenience.
 - [repeatable-flag](https://github.com/DannyBen/bashly/tree/master/examples/repeatable-flag#readme) - allowing flags to be provided multiple times
 - [reusable-flags](https://github.com/DannyBen/bashly/tree/master/examples/reusable-flags#readme) - reuse flag definition for multiple commands
 - [conflicts](https://github.com/DannyBen/bashly/tree/master/examples/conflicts#readme) - defining mutually exclusive flags
+- [needs](https://github.com/DannyBen/bashly/tree/master/examples/needs#readme) - defining flags that need other flags
 - [command-private](https://github.com/DannyBen/bashly/tree/master/examples/command-private#readme) - hiding commands from the command list
 - [stdin](https://github.com/DannyBen/bashly/tree/master/examples/stdin#readme) - reading input from stdin
 - [filters](https://github.com/DannyBen/bashly/tree/master/examples/filters#readme) - preventing commands from running unless custom conditions are met
@@ -71,7 +72,7 @@ All examples are listed below for convenience.
 - [yaml](https://github.com/DannyBen/bashly/tree/master/examples/yaml#readme) - using the YAML reading functions
 - [colors](https://github.com/DannyBen/bashly/tree/master/examples/colors#readme) - using the color print feature
 - [completions](https://github.com/DannyBen/bashly/tree/master/examples/completions#readme) - adding bash completion functionality
-- [validations](https://github.com/DannyBen/bashly/tree/master/examples/validations#readme) - adding argument validation functions
+- [validations](https://github.com/DannyBen/bashly/tree/master/examples/validations#readme) - adding validation functions for arguments, flags or environment variables
 - [hooks](https://github.com/DannyBen/bashly/tree/master/examples/hooks#readme) - adding before/after hooks
 
 ## Real-world-like examples

src/usage/settings.md

@@ -48,6 +48,7 @@ When setting environment variables, you can use:
 ### `source_dir`
 
 ```yaml
+# default
 source_dir: src
 ```
 
@@ -56,6 +57,7 @@ Set the path containing the bashly source files.
 ### `config_path`
 
 ```yaml
+# default
 config_path: "%{source_dir}/bashly.yml"
 ```
 
@@ -65,6 +67,7 @@ reference the value of the `source_dir` option.
 ### `target_dir`
 
 ```yaml
+# default
 target_dir: .
 ```
 
@@ -73,6 +76,7 @@ Set the path to use for creating the final bash script.
 ### `lib_dir`
 
 ```yaml
+# default
 lib_dir: lib
 ```
 
@@ -81,7 +85,11 @@ Set the path to use for common library files, relative to `source_dir`.
 ### `commands_dir`
 
 ```yaml
+# default
 commands_dir: ~
+
+# example
+commands_dir: commands
 ```
 
 Set the path to use for command files, relative to `source_dir`.
@@ -99,7 +107,13 @@ recommended to enable this by setting it to something like
 ### `strict`
 
 ```yaml
+# default
 strict: false
+
+# examples
+strict: true
+strict: ''
+strict: set -o pipefail
 ```
 
 Specify which bash options to apply on initialization.
@@ -113,6 +127,7 @@ Specify which bash options to apply on initialization.
 ### `tab_indent`
 
 ```yaml
+# default
 tab_indent: false
 ```
 
@@ -125,6 +140,7 @@ Specify the indentation style of the generated script.
 ### `compact_short_flags`
 
 ```yaml
+# default
 compact_short_flags: true
 ```
 
@@ -136,6 +152,7 @@ Specify how the generated script should treat flags in the form of `-abc`
 ### `conjoined_flag_args`
 
 ```yaml
+# default
 conjoined_flag_args: true
 ```
 
@@ -148,6 +165,7 @@ or `-f=value`
 ### `env`
 
 ```yaml
+# default
 env: development
 ```
 
@@ -166,7 +184,11 @@ user's partial code files.
 ### `partials_extension`
 
 ```yaml
+# default
 partials_extension: sh
+
+# example
+partials_extension: bash
 ```
 
 Set the extension to use when reading/writing partial script snippets.
@@ -175,6 +197,7 @@ Set the extension to use when reading/writing partial script snippets.
 ### `show_examples_on_error`
 
 ```yaml
+# default
 show_examples_on_error: false
 ```
 
@@ -185,15 +208,41 @@ provide the required arguments.
 [!button variant="primary" icon="code-review" text="Show Examples on Error Example"](https://github.com/DannyBen/bashly/tree/master/examples/command-examples-on-error#readme)
 
 
+### `private_reveal_key`
+
+```yaml
+# default
+private_reveal_key: ~
+
+# example
+private_reveal_key: ADVANCED_FEATURES
+```
+
+When using private commands, flags, or environment variables, you may set 
+this option to a name of an environment variable that, if set, will reveal
+all the private elements in the usage texts, as if they were public.
+
+[!button variant="primary" icon="code-review" text="Private Reveal Example"](https://github.com/DannyBen/bashly/tree/master/examples/private-reveal#readme)
+
+
 ### `usage_colors`
 
 ```yaml
+# default
 usage_colors:
   caption: ~
   command: ~
   arg: ~
   flag: ~
   environment_variable: ~
+
+# example
+usage_colors:
+  caption: bold
+  command: green_underlined
+  arg: blue
+  flag: magenta
+  environment_variable: cyan_bold
 ```
 
 Enable color output for several aspects of the help message of the generated