From e48eb8e9736c269028e1d0b3d6cf6228a273178f Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Mon, 27 Jan 2025 11:36:15 +0000 Subject: [PATCH 1/8] changelog --- CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f705b4b..db1221e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,15 @@ Changelog ======================================== +v1.2.9 - 2025-01-27 +---------------------------------------- + +- Update colors library to support auto-colors based on TTY [`a4bbae9a`](https://github.com/DannyBen/bashly/commit/a4bbae9a) +- Add `--quiet` to `bashly add` command [`ca0a5468`](https://github.com/DannyBen/bashly/commit/ca0a5468) +- Update documentation domain to bashly.dev [`d05605cb`](https://github.com/DannyBen/bashly/commit/d05605cb) +- Compare [`v1.2.8..v1.2.9`](https://github.com/dannyben/bashly/compare/v1.2.8..v1.2.9) + + v1.2.8 - 2025-01-16 ---------------------------------------- From 966651b3e0c35bd8d14fb9ec8e771d672be82344 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Thu, 30 Jan 2025 05:06:35 +0000 Subject: [PATCH 2/8] rubocop --- lib/bashly/commands/generate.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/bashly/commands/generate.rb b/lib/bashly/commands/generate.rb index e5a1b8df..0cdb673f 100644 --- a/lib/bashly/commands/generate.rb +++ b/lib/bashly/commands/generate.rb @@ -3,7 +3,7 @@ module Bashly module Commands class Generate < Base - summary "Generate the bash script and required files" + summary 'Generate the bash script and required files' help "This command is also aliased as 'build'" usage 'bashly generate [options]' From d7a57e47549885f976bfe81d0c88f8a03c8d36af Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Sun, 9 Feb 2025 15:17:47 +0000 Subject: [PATCH 3/8] - Add `header_override` command option --- lib/bashly/config_validator.rb | 1 + lib/bashly/script/command.rb | 2 +- lib/bashly/views/command/usage.gtx | 10 +++++++--- 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/lib/bashly/config_validator.rb b/lib/bashly/config_validator.rb index aa5784c2..6888f5ac 100644 --- a/lib/bashly/config_validator.rb +++ b/lib/bashly/config_validator.rb @@ -186,6 +186,7 @@ def assert_command(key, value) assert_string "#{key}.name", value['name'] assert_optional_string "#{key}.help", value['help'] + assert_optional_string "#{key}.header_override", value['header_override'] assert_optional_string "#{key}.footer", value['footer'] assert_optional_string "#{key}.group", value['group'] assert_optional_string "#{key}.filename", value['filename'] diff --git a/lib/bashly/script/command.rb b/lib/bashly/script/command.rb index 01f425e7..af6c32d7 100644 --- a/lib/bashly/script/command.rb +++ b/lib/bashly/script/command.rb @@ -17,7 +17,7 @@ def option_keys alias args catch_all commands completions default dependencies environment_variables examples extensible expose filename filters flags - footer function group help name + footer function group help header_override name private variables version ] end diff --git a/lib/bashly/views/command/usage.gtx b/lib/bashly/views/command/usage.gtx index 49a7041a..1f2d7dfc 100644 --- a/lib/bashly/views/command/usage.gtx +++ b/lib/bashly/views/command/usage.gtx @@ -1,12 +1,16 @@ = view_marker > {{ function_name }}_usage() { -if summary == help +if summary == help && !header_override > printf "{{ caption_string.sanitize_for_print }}\n\n" else > if [[ -n $long_usage ]]; then - > printf "{{ full_name }}\n\n" - > printf "{{ help.wrap(78).indent(2).sanitize_for_print }}\n\n" + if header_override + = header_override.indent 4 + else + > printf "{{ full_name }}\n\n" + > printf "{{ help.wrap(78).indent(2).sanitize_for_print }}\n\n" + end > else > printf "{{ caption_string.sanitize_for_print }}\n\n" > fi From 2a8b5ded7878229c1165cd2054a8596ef80986c4 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Sat, 15 Feb 2025 06:02:22 +0000 Subject: [PATCH 4/8] - Rename `header_override` to `help_header_override` --- lib/bashly/config_validator.rb | 2 +- lib/bashly/script/command.rb | 2 +- lib/bashly/views/command/usage.gtx | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/lib/bashly/config_validator.rb b/lib/bashly/config_validator.rb index 6888f5ac..abb95986 100644 --- a/lib/bashly/config_validator.rb +++ b/lib/bashly/config_validator.rb @@ -186,7 +186,7 @@ def assert_command(key, value) assert_string "#{key}.name", value['name'] assert_optional_string "#{key}.help", value['help'] - assert_optional_string "#{key}.header_override", value['header_override'] + assert_optional_string "#{key}.help_header_override", value['help_header_override'] assert_optional_string "#{key}.footer", value['footer'] assert_optional_string "#{key}.group", value['group'] assert_optional_string "#{key}.filename", value['filename'] diff --git a/lib/bashly/script/command.rb b/lib/bashly/script/command.rb index af6c32d7..fa2f3072 100644 --- a/lib/bashly/script/command.rb +++ b/lib/bashly/script/command.rb @@ -17,7 +17,7 @@ def option_keys alias args catch_all commands completions default dependencies environment_variables examples extensible expose filename filters flags - footer function group help header_override name + footer function group help help_header_override name private variables version ] end diff --git a/lib/bashly/views/command/usage.gtx b/lib/bashly/views/command/usage.gtx index 1f2d7dfc..b87e9510 100644 --- a/lib/bashly/views/command/usage.gtx +++ b/lib/bashly/views/command/usage.gtx @@ -1,12 +1,12 @@ = view_marker > {{ function_name }}_usage() { -if summary == help && !header_override +if summary == help && !help_header_override > printf "{{ caption_string.sanitize_for_print }}\n\n" else > if [[ -n $long_usage ]]; then - if header_override - = header_override.indent 4 + if help_header_override + = help_header_override.indent 4 else > printf "{{ full_name }}\n\n" > printf "{{ help.wrap(78).indent(2).sanitize_for_print }}\n\n" From aa00c75100511ee76067ff2faa205716dee8e851 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Sat, 15 Feb 2025 09:22:19 +0000 Subject: [PATCH 5/8] - Add example for `help_header_override` --- examples/README.md | 1 + examples/help-header-override/.gitignore | 1 + examples/help-header-override/README.md | 121 ++++++++++++++++++ examples/help-header-override/src/bashly.yml | 34 +++++ .../help-header-override/src/root_command.sh | 5 + examples/help-header-override/test.sh | 12 ++ examples/render-mandoc/docs/download.1 | 2 +- examples/render-mandoc/docs/download.md | 2 +- spec/approvals/examples/help-header-override | 51 ++++++++ spec/approvals/examples/render-mandoc | 2 +- 10 files changed, 228 insertions(+), 3 deletions(-) create mode 100644 examples/help-header-override/.gitignore create mode 100644 examples/help-header-override/README.md create mode 100644 examples/help-header-override/src/bashly.yml create mode 100644 examples/help-header-override/src/root_command.sh create mode 100644 examples/help-header-override/test.sh create mode 100644 spec/approvals/examples/help-header-override diff --git a/examples/README.md b/examples/README.md index 7287792f..546f0abf 100644 --- a/examples/README.md +++ b/examples/README.md @@ -51,6 +51,7 @@ Each of these examples demonstrates one aspect or feature of bashly. - [custom-strings](custom-strings#readme) - configuring the script's error and usage texts - [custom-includes](custom-includes#readme) - adding and organizing your custom functions - [custom-script-header](custom-script-header#readme) - configuring a different script header +- [help-header-override](help-header-override#readme) - replacing the header of the help message - [footer](footer#readme) - adding a footer to the help message - [command-filenames](command-filenames#readme) - overriding filenames for your source scripts - [command-paths](command-paths#readme) - configuring nested paths for your source scripts diff --git a/examples/help-header-override/.gitignore b/examples/help-header-override/.gitignore new file mode 100644 index 00000000..d3a4c581 --- /dev/null +++ b/examples/help-header-override/.gitignore @@ -0,0 +1 @@ +download diff --git a/examples/help-header-override/README.md b/examples/help-header-override/README.md new file mode 100644 index 00000000..a4585178 --- /dev/null +++ b/examples/help-header-override/README.md @@ -0,0 +1,121 @@ +# Help Header Override Example + +Demonstrates how to fully replace the header in the output of `--help`. + +This is especially useful when incorporating ASCII art as your script's help +header. + +This example was generated with: + +```bash +$ bashly init --minimal +# ... now edit src/bashly.yml to match the example ... +$ bashly generate + +``` + +----- + +## `bashly.yml` + +````yaml +name: download +help: Sample minimal application without commands +version: 0.1.0 + +# Use bash code here directly or a function name that references code elsewhere. +help_header_override: | + echo + echo $' 888888b. 888 888 ' + echo $' 888 "88b 888 888 ' + echo $' 888 .88P 888 888 ' + echo $' 8888888K. 8888b. .d8888b 88888b. 888 888 888 ' + echo $' 888 "Y88b "88b 88K 888 "88b 888 888 888 ' + echo $' 888 888 .d888888 "Y8888b. 888 888 888 888 888 ' + echo $' 888 d88P 888 888 X88 888 888 888 Y88b 888 ' + echo $' 8888888P" "Y888888 88888P\' 888 888 888 "Y88888 ' + echo $' 888 ' + echo $' Y8b d88P ' + echo $' "Y88P" ' + echo + +args: +- name: source + help: URL to download from +- name: target + help: "Target filename (default: same as source)" + +flags: +- long: --force + short: -f + help: Overwrite existing files + +examples: +- download example.com +- download example.com ./output -f +```` + + + +## Output + +### `$ ./download` + +````shell +# This file is located at 'src/root_command.sh'. +# It contains the implementation for the 'download' command. +# The code you write here will be wrapped by a function named 'download_command()'. +# Feel free to edit this file; your changes will persist when regenerating. +args: none + + +```` + +### `$ ./download --help` + +````shell + + 888888b. 888 888 + 888 "88b 888 888 + 888 .88P 888 888 + 8888888K. 8888b. .d8888b 88888b. 888 888 888 + 888 "Y88b "88b 88K 888 "88b 888 888 888 + 888 888 .d888888 "Y8888b. 888 888 888 888 888 + 888 d88P 888 888 X88 888 888 888 Y88b 888 + 8888888P" "Y888888 88888P' 888 888 888 "Y88888 + 888 + Y8b d88P + "Y88P" + +Usage: + download [SOURCE] [TARGET] [OPTIONS] + download --help | -h + download --version | -v + +Options: + --force, -f + Overwrite existing files + + --help, -h + Show this help + + --version, -v + Show version number + +Arguments: + SOURCE + URL to download from + + TARGET + Target filename (default: same as source) + +Examples: + download example.com + download example.com ./output -f + + + +```` + + + diff --git a/examples/help-header-override/src/bashly.yml b/examples/help-header-override/src/bashly.yml new file mode 100644 index 00000000..bc4b9f99 --- /dev/null +++ b/examples/help-header-override/src/bashly.yml @@ -0,0 +1,34 @@ +name: download +help: Sample minimal application without commands +version: 0.1.0 + +# Use bash code here directly or a function name that references code elsewhere. +help_header_override: | + echo + echo $' 888888b. 888 888 ' + echo $' 888 "88b 888 888 ' + echo $' 888 .88P 888 888 ' + echo $' 8888888K. 8888b. .d8888b 88888b. 888 888 888 ' + echo $' 888 "Y88b "88b 88K 888 "88b 888 888 888 ' + echo $' 888 888 .d888888 "Y8888b. 888 888 888 888 888 ' + echo $' 888 d88P 888 888 X88 888 888 888 Y88b 888 ' + echo $' 8888888P" "Y888888 88888P\' 888 888 888 "Y88888 ' + echo $' 888 ' + echo $' Y8b d88P ' + echo $' "Y88P" ' + echo + +args: +- name: source + help: URL to download from +- name: target + help: "Target filename (default: same as source)" + +flags: +- long: --force + short: -f + help: Overwrite existing files + +examples: +- download example.com +- download example.com ./output -f diff --git a/examples/help-header-override/src/root_command.sh b/examples/help-header-override/src/root_command.sh new file mode 100644 index 00000000..28c47a20 --- /dev/null +++ b/examples/help-header-override/src/root_command.sh @@ -0,0 +1,5 @@ +echo "# This file is located at 'src/root_command.sh'." +echo "# It contains the implementation for the 'download' command." +echo "# The code you write here will be wrapped by a function named 'download_command()'." +echo "# Feel free to edit this file; your changes will persist when regenerating." +inspect_args diff --git a/examples/help-header-override/test.sh b/examples/help-header-override/test.sh new file mode 100644 index 00000000..36944cfe --- /dev/null +++ b/examples/help-header-override/test.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash + +rm -f src/*.sh + +set -x + +bashly generate + +### Try Me ### + +./download +./download --help diff --git a/examples/render-mandoc/docs/download.1 b/examples/render-mandoc/docs/download.1 index 09bf0f85..73817b48 100644 --- a/examples/render-mandoc/docs/download.1 +++ b/examples/render-mandoc/docs/download.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 3.2 .\" -.TH "download" "1" "January 2025" "Version 0.1.0" "Sample application" +.TH "download" "1" "February 2025" "Version 0.1.0" "Sample application" .SH NAME \f[B]download\f[R] \- Sample application .SH SYNOPSIS diff --git a/examples/render-mandoc/docs/download.md b/examples/render-mandoc/docs/download.md index 32d3df81..51ad923a 100644 --- a/examples/render-mandoc/docs/download.md +++ b/examples/render-mandoc/docs/download.md @@ -1,6 +1,6 @@ % download(1) Version 0.1.0 | Sample application % Lana Lang -% January 2025 +% February 2025 NAME ================================================== diff --git a/spec/approvals/examples/help-header-override b/spec/approvals/examples/help-header-override new file mode 100644 index 00000000..d747faad --- /dev/null +++ b/spec/approvals/examples/help-header-override @@ -0,0 +1,51 @@ ++ bashly generate +creating user files in src +created src/root_command.sh +created ./download +run ./download --help to test your bash script ++ ./download +# This file is located at 'src/root_command.sh'. +# It contains the implementation for the 'download' command. +# The code you write here will be wrapped by a function named 'download_command()'. +# Feel free to edit this file; your changes will persist when regenerating. +args: none ++ ./download --help + + 888888b. 888 888 + 888 "88b 888 888 + 888 .88P 888 888 + 8888888K. 8888b. .d8888b 88888b. 888 888 888 + 888 "Y88b "88b 88K 888 "88b 888 888 888 + 888 888 .d888888 "Y8888b. 888 888 888 888 888 + 888 d88P 888 888 X88 888 888 888 Y88b 888 + 8888888P" "Y888888 88888P' 888 888 888 "Y88888 + 888 + Y8b d88P + "Y88P" + +Usage: + download [SOURCE] [TARGET] [OPTIONS] + download --help | -h + download --version | -v + +Options: + --force, -f + Overwrite existing files + + --help, -h + Show this help + + --version, -v + Show version number + +Arguments: + SOURCE + URL to download from + + TARGET + Target filename (default: same as source) + +Examples: + download example.com + download example.com ./output -f + diff --git a/spec/approvals/examples/render-mandoc b/spec/approvals/examples/render-mandoc index 8fb99f35..bd70d174 100644 --- a/spec/approvals/examples/render-mandoc +++ b/spec/approvals/examples/render-mandoc @@ -44,4 +44,4 @@ ISSUE TRACKER AUTHORS Lana Lang. -Version 0.1.0 January 2025 download(1) +Version 0.1.0 February 2025 download(1) From 6677f4da767f184e16c58d4fce78689c183458e4 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Sat, 15 Feb 2025 09:56:21 +0000 Subject: [PATCH 6/8] - Update JSON schema with `help_header_override` --- schemas/bashly.json | 15 +++++++++++++++ support/schema/bashly.yml | 13 +++++++++++++ 2 files changed, 28 insertions(+) diff --git a/schemas/bashly.json b/schemas/bashly.json index 28514d62..0c0160fe 100644 --- a/schemas/bashly.json +++ b/schemas/bashly.json @@ -470,6 +470,15 @@ "URL to download from" ] }, + "help-header-override-property": { + "title": "help_header_override", + "description": "Bash code (or function call) that will be executed at the beginning of the help message\nhttps://bashly.dev/configuration/command/#help-header-override", + "type": "string", + "minLength": 1, + "examples": [ + "generate_ascii_art_logo" + ] + }, "args-property": { "title": "args", "description": "Arguments of the current script or sub-command\nhttps://bashly.dev/configuration/command/#args", @@ -847,6 +856,9 @@ "help": { "$ref": "#/definitions/help-property" }, + "help_header_override": { + "$ref": "#/definitions/help-header-override-property" + }, "args": { "$ref": "#/definitions/args-property" }, @@ -924,6 +936,9 @@ "help": { "$ref": "#/definitions/help-property" }, + "help_header_override": { + "$ref": "#/definitions/help-header-override-property" + }, "args": { "$ref": "#/definitions/args-property" }, diff --git a/support/schema/bashly.yml b/support/schema/bashly.yml index 1066053b..251f8aea 100644 --- a/support/schema/bashly.yml +++ b/support/schema/bashly.yml @@ -405,6 +405,15 @@ definitions: minLength: 1 examples: - URL to download from + help-header-override-property: + title: help_header_override + description: |- + Bash code (or function call) that will be executed at the beginning of the help message + https://bashly.dev/configuration/command/#help-header-override + type: string + minLength: 1 + examples: + - generate_ascii_art_logo args-property: title: args description: |- @@ -739,6 +748,8 @@ definitions: $ref: '#/definitions/sub-command-alias-property' help: $ref: '#/definitions/help-property' + help_header_override: + $ref: '#/definitions/help-header-override-property' args: $ref: '#/definitions/args-property' flags: @@ -787,6 +798,8 @@ properties: $ref: '#/definitions/name-property' help: $ref: '#/definitions/help-property' + help_header_override: + $ref: '#/definitions/help-header-override-property' args: $ref: '#/definitions/args-property' flags: From 4e50fe17edeee6c587140f448093a99a1907adc6 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Sat, 15 Feb 2025 10:18:22 +0000 Subject: [PATCH 7/8] - Update `bashly doc` with `command.help_header_override` --- lib/bashly/docs/command.yml | 14 ++++++++++++++ spec/approvals/cli/doc/full | 16 ++++++++++++++++ spec/approvals/cli/doc/index | 1 + 3 files changed, 31 insertions(+) diff --git a/lib/bashly/docs/command.yml b/lib/bashly/docs/command.yml index 4dd957ad..aea29eec 100644 --- a/lib/bashly/docs/command.yml +++ b/lib/bashly/docs/command.yml @@ -289,6 +289,20 @@ command.help: - name: images help: Manage images +command.help_header_override: + help: Provide an alternative bash code (or function call) that will be executed at the beginning of the help message. + + url: https://bashly.dev/configuration/command/#help_header_override + example: |- + name: font-explorer + help: Font manager utility + + help_header_override: | + echo '┏┓ ┏┓ ┓ ' + echo '┣ ┏┓┏┓╋ ┣ ┓┏┏┓┃┏┓┏┓┏┓┏┓' + echo '┻ ┗┛┛┗┗ ┗┛┛┗┣┛┗┗┛┛ ┗ ┛ ' + echo ' ┛ v1.0' + command.name: help: Specify the name of the command. This option is required. url: https://bashly.dev/configuration/command/#name diff --git a/spec/approvals/cli/doc/full b/spec/approvals/cli/doc/full index ac7784b6..ef77dcf9 100644 --- a/spec/approvals/cli/doc/full +++ b/spec/approvals/cli/doc/full @@ -443,6 +443,22 @@ command.help See https://bashly.dev/configuration/command/#help +command.help_header_override + + Provide an alternative bash code (or function call) that will be executed at + the beginning of the help message. + + name: font-explorer + help: Font manager utility + + help_header_override: | + echo '┏┓ ┏┓ ┓ ' + echo '┣ ┏┓┏┓╋ ┣ ┓┏┏┓┃┏┓┏┓┏┓┏┓' + echo '┻ ┗┛┛┗┗ ┗┛┛┗┣┛┗┗┛┛ ┗ ┛ ' + echo ' ┛ v1.0' + + See https://bashly.dev/configuration/command/#help_header_override + command.name Specify the name of the command. This option is required. diff --git a/spec/approvals/cli/doc/index b/spec/approvals/cli/doc/index index 4e300307..f2072735 100644 --- a/spec/approvals/cli/doc/index +++ b/spec/approvals/cli/doc/index @@ -25,6 +25,7 @@ command.footer command.function command.group command.help +command.help_header_override command.name command.private command.variables From 7e96d442e8176cb35948b64e109914419af73d72 Mon Sep 17 00:00:00 2001 From: Danny Ben Shitrit Date: Sat, 22 Feb 2025 06:20:06 +0000 Subject: [PATCH 8/8] version bump 1.2.10 --- Dockerfile | 2 +- lib/bashly/version.rb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index 202492e9..3eb01251 100644 --- a/Dockerfile +++ b/Dockerfile @@ -3,7 +3,7 @@ FROM dannyben/alpine-ruby:3.3.3 LABEL io.whalebrew.name=bashly ENV PS1="\n\n>> bashly \W \$ " -ENV BASHLY_VERSION=1.2.9 +ENV BASHLY_VERSION=1.2.10 WORKDIR /app diff --git a/lib/bashly/version.rb b/lib/bashly/version.rb index 3ca50e06..f90e4d26 100644 --- a/lib/bashly/version.rb +++ b/lib/bashly/version.rb @@ -1,3 +1,3 @@ module Bashly - VERSION = '1.2.9' + VERSION = '1.2.10' end