From 081baf96a24d75741f4bfc22c27e07881033d925 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Fri, 2 Aug 2024 03:20:00 +0000 Subject: [PATCH 1/3] add flag.needs --- src/configuration/flag.md | 18 +++++++++++++++++- src/examples.md | 1 + 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/src/configuration/flag.md b/src/configuration/flag.md index 56c1936f..a274b552 100644 --- a/src/configuration/flag.md +++ b/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,6 +163,22 @@ 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] diff --git a/src/examples.md b/src/examples.md index 4b8d08c3..12922a11 100644 --- a/src/examples.md +++ b/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 From 8649b636e76608e264db7a4c5523a9b7b8b1c167 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Wed, 14 Aug 2024 13:01:10 +0000 Subject: [PATCH 2/3] add environment_variables.validate --- src/advanced/validations.md | 4 ++-- src/configuration/environment-variable.md | 8 ++++++++ src/examples.md | 2 +- 3 files changed, 11 insertions(+), 3 deletions(-) diff --git a/src/advanced/validations.md b/src/advanced/validations.md index 8a5ae189..992086f9 100644 --- a/src/advanced/validations.md +++ b/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. diff --git a/src/configuration/environment-variable.md b/src/configuration/environment-variable.md index 2f875ca2..bab4e5a3 100644 --- a/src/configuration/environment-variable.md +++ b/src/configuration/environment-variable.md @@ -85,3 +85,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) diff --git a/src/examples.md b/src/examples.md index 7f5f862a..8c03ba29 100644 --- a/src/examples.md +++ b/src/examples.md @@ -72,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 From f9b88b5e21acc93c6f5d8abc6c92291b629ab9f1 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Thu, 15 Aug 2024 07:46:19 +0000 Subject: [PATCH 3/3] add private_reveal_key --- src/configuration/command.md | 5 +++ src/configuration/environment-variable.md | 5 +++ src/configuration/flag.md | 5 +++ src/usage/settings.md | 49 +++++++++++++++++++++++ 4 files changed, 64 insertions(+) diff --git a/src/configuration/command.md b/src/configuration/command.md index 0cf6611d..83f89970 100644 --- a/src/configuration/command.md +++ b/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) diff --git a/src/configuration/environment-variable.md b/src/configuration/environment-variable.md index bab4e5a3..ca62a354 100644 --- a/src/configuration/environment-variable.md +++ b/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] diff --git a/src/configuration/flag.md b/src/configuration/flag.md index a274b552..a09f4585 100644 --- a/src/configuration/flag.md +++ b/src/configuration/flag.md @@ -185,6 +185,11 @@ This option should be specified on both sides of the requirement. 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] diff --git a/src/usage/settings.md b/src/usage/settings.md index 1701ebfb..cd0ac8f6 100644 --- a/src/usage/settings.md +++ b/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