✨ support alternative cmd defintion block

.vscode/valet.code-snippets

@@ -1,4 +1,87 @@
 {
+	"new command alt": {
+		"prefix": "new command alt",
+		"description": "A new command alternative definition for Valet",
+		"scope": "",
+		"body": [
+			"##<<VALET_COMMAND",
+			"# command: command",
+			"# function: functionName",
+			"# shortDescription: A short sentence.",
+			"# description: |-",
+			"#   A long description that can use ⌜quotes⌝.",
+			"# sudo: false",
+			"# hideInMenu: false",
+			"# arguments:",
+			"# - name: firstArg",
+			"#   description: |-",
+			"#     First argument.",
+			"# - name: more...",
+			"#   description: |-",
+			"#     Will be an an array of strings.",
+			"# options:",
+			"# - name: -o, --option1",
+			"#   description: |-",
+			"#     First option.",
+			"#   noEnvironmentVariable: true",
+			"# - name: -2, --this-is-option2 <level>",
+			"#   description: |-",
+			"#     An option with a value.",
+			"#   noEnvironmentVariable: false",
+			"# examples:",
+			"# - name: command -o -2 value1 arg1 more1 more2",
+			"#   description: |-",
+			"#     Call command with option1, option2 and some arguments.",
+			"##VALET_COMMAND"
+		]
+	},
+	"new command": {
+		"prefix": "new command",
+		"description": "A new command definition for Valet",
+		"scope": "",
+		"body": [
+			": \"---",
+			"command: command",
+			"function: functionName",
+			"shortDescription: A short sentence.",
+			"description: |-",
+			"  A long description that can use ⌜quotes⌝.",
+			"sudo: false",
+			"hideInMenu: false",
+			"arguments:",
+			"- name: firstArg",
+			"  description: |-",
+			"    First argument.",
+			"- name: more...",
+			"  description: |-",
+			"    Will be an an array of strings.",
+			"options:",
+			"- name: -o, --option1",
+			"  description: |-",
+			"    First option.",
+			"  noEnvironmentVariable: true",
+			"- name: -2, --this-is-option2 <level>",
+			"  description: |-",
+			"    An option with a value.",
+			"  noEnvironmentVariable: false",
+			"examples:",
+			"- name: command -o -2 value1 arg1 more1 more2",
+			"  description: |-",
+			"    Call command with option1, option2 and some arguments.",
+			": \"---"
+		]
+	},
+	"comment section": {
+		"prefix": "comment section",
+		"description": "",
+		"scope": "",
+		"body": [
+			"#===============================================================",
+			"# >>> $1",
+			"#===============================================================",
+			"$0"
+		]
+	},
 	"quote": {
 		"prefix": "quote",
 		"description": "",

docs/content/docs/020.new-commands/_index.md

@@ -86,6 +86,18 @@ If your new command name contains one or more spaces, you are defining a sub com
 
 For more examples, take a look at the [showcase command definitions][showcase-commands].
 
+Alternatively, you can add a new command definition using bash comments and the following format:
+
+```bash
+##<<VALET_COMMAND
+# command: hello-world
+# function: helloWorld
+# shortDescription: A dummy command.
+# description: |-
+#   This command says hello world.
+##VALET_COMMAND
+```
+
 ### ✒️ Implement your command
 
 Once the command properties are set, the next step is to implement the command function.

docs/content/docs/800.roadmap/_index.md

@@ -23,7 +23,6 @@ This page lists the features that I would like to implement in Valet. They come
 - Reimplement usage of main::sortCommands / main::addLastChoice.
 - Implement regex replace in pure bash.
 - Betters checks in self build!
-- Support alternative single comments `### VALET COMMAND` instead of multiline comments for command declaration (see we can have help in autocompletion).
 - A command can declare dependencies to auto check if some tools are installed before running the command.
 - Add test:: and also add a snippet to create a new function.
 - add valet in brew

tests.d/1101-self-build-utils/resources/extract-command-yamls-test-file

@@ -10,6 +10,10 @@ array:
 
 echo "Hello, World!"
 
+##<<VALET_COMMAND
+# yep!
+##VALET_COMMAND
+
 : "---
 And another one!
 ---"

tests.d/1101-self-build-utils/results.approved.md

@@ -16,6 +16,9 @@ INFO     content:
    4 ░   - item2
    5 ░   - item3
    6 ░ 
+INFO     content:
+   1 ░ yep!
+   2 ░ 
 INFO     content:
    1 ░ And another one!
    2 ░ 

tests.d/1103-self-release/results.approved.md

@@ -31,7 +31,7 @@ INFO     The tag message is:
    6 ░ - 🐞 fix
    7 ░ 
 INFO     The new version of valet is: 2.0.0.
-SUCCESS  The new version has been released, check: ⌜https://github.com/jcaillon/valet/releases/latest⌝.
+SUCCESS  The new version has been released, check: https://github.com/jcaillon/valet/releases/latest.
 ```
 
 ### Testing selfRelease, minor version
@@ -452,6 +452,6 @@ DEBUG    The artifact has been created at ⌜valet.tar.gz⌝ with:
 
 INFO     Uploading the artifact ⌜valet.tar.gz⌝ to ⌜https://uploads.github.com/repos/jcaillon/valet/releases/xxxx/assets⌝.
 ▶ called kurl::toVar true  -X POST -H Authorization: token token -H Content-Type: application/tar+gzip --data-binary @valet.tar.gz https://uploads.github.com/repos/jcaillon/valet/releases/xxxx/assets?name=valet.tar.gz
-SUCCESS  The new version has been released, check: ⌜https://github.com/jcaillon/valet/releases/latest⌝.
+SUCCESS  The new version has been released, check: https://github.com/jcaillon/valet/releases/latest.
 ```
 

tests.d/1104-self-setup/results.approved.md

@@ -58,7 +58,7 @@ INFO     As a reminder, you can modify the configuration done during this set up
 - replaying the command ⌜valet self setup⌝,
 - running the command ⌜valet self config⌝.
 INFO     Run ⌜valet --help⌝ to get started.
-INFO     You can create your own commands and have them available in valet, please check ⌜https://jcaillon.github.io/valet/docs/new-commands/⌝ to do so.
+INFO     You can create your own commands and have them available in valet, please check https://jcaillon.github.io/valet/docs/new-commands/ to do so.
 ```
 
 ### Testing selfSetup 2
@@ -115,6 +115,6 @@ CININFO    II  CDE As a reminder, you can modify the configuration done during t
 - replaying the command CHI⌜valet self setup⌝CDE,
 - running the command CHI⌜valet self config⌝CDE.
 CININFO    II  CDE Run CHI⌜valet --help⌝CDE to get started.
-CININFO    II  CDE You can create your own commands and have them available in valet, please check CHI⌜https://jcaillon.github.io/valet/docs/new-commands/⌝CDE to do so.
+CININFO    II  CDE You can create your own commands and have them available in valet, please check https://jcaillon.github.io/valet/docs/new-commands/ to do so.
 ```
 

valet

@@ -6,79 +6,79 @@ if [[ ${BASH_VERSINFO[0]:-0} -lt 5 ]]; then
   exit 1
 fi
 
-: "---
-command: valet
-function: this
-author: github.com/jcaillon
-shortDescription: Your personal assistant in the terminal!
-description: |-
-  Valet helps you browse, understand and execute your custom bash commands.
-
-  Online documentation is available at https://jcaillon.github.io/valet/.
-
-  You can call valet without any commands to start an interactive session.
-
-  ⌜Exit codes:⌝
-
-  - 0: everything went well
-  - 1+: an error occured
-
-  ⌜Create your own commands:⌝
-
-  You can create your own commands and have them available in valet, please check https://jcaillon.github.io/valet/docs/new-commands/ or the examples under examples.d to do so.
-  Valet looks for commands in the valet user directory, which default to ~/.valet.d and can be overwritten using an environment variable (see below).
-  Once you have created your new command script, run the ⌜valet self build⌝ command to update the valet menu.
-
-  ⌜Configuration through environment variables:⌝
-
-  In addition to the environment variables defined for each options, you can define environment variables to configure valet.
-
-  These variables are conviently defined in the valet user config file, located by default at ~/.config/valet/config (the path to this file can be configured using the VALET_CONFIG_FILE environment variable).
-
-  You can run ⌜valet self config⌝ to open the configuration file with your default editor (the file will get created if it does not yet exist).
-
-  ⌜Developer notes:⌝
-
-  You can enable debug mode with profiling for valet by setting the environment variable VALET_CONFIG_STARTUP_PROFILING to true (it will output to ~/valet-profiler-{PID}.txt).
-arguments:
-- name: commands?...
-  description: |-
-    The command or sub commands to execute.
-    See the commands section for more information.
-options:
-- name: -x, --profiling
-  description: |-
-    Turn on profiling (with debug mode) before running the required command.
-    It will output to ~/valet-profiler-{PID}-command.txt.
-    This is useful to debug your command and understand what takes a long time to execute.
-    The profiler log will be cleanup to only keep lines relevant for your command script. You can disable this behavior by setting the environment variable VALET_CONFIG_KEEP_ALL_PROFILER_LINES to true.
-- name: -l, --log-level, --log <level>
-  description: |-
-    Set the log level of valet (defaults to info).
-    Possible values are: trace, debug, success, info, success, warning, error.
-- name: -v, --verbose
-  description: |-
-    Output verbose information.
-    This is the equivalent of setting the log level to debug.
-- name: -w, --very-verbose
-  description: |-
-    Output very verbose information.
-    This is the equivalent of setting the log level to trace.
-- name: -i, --force-interactive-mode
-  description: |-
-    Enter interactive mode for commands even if arguments are not required or provided.
-- name: --version
-  description: |-
-    Display the current version of valet.
-  noEnvironmentVariable: true
-examples:
-- name: --help
-  description: |-
-    Displays this help text.
-- name: -v a-command and-sub-command
-  description: |-
-    Active ⌜verbose⌝ mode and run the command ⌜a-command⌝ with the sub command ⌜and-sub-command⌝.
----"
+##<<VALET_COMMAND
+# command: valet
+# function: this
+# author: github.com/jcaillon
+# shortDescription: Your personal assistant in the terminal!
+# description: |-
+#   Valet helps you browse, understand and execute your custom bash commands.
+#
+#   Online documentation is available at https://jcaillon.github.io/valet/.
+#
+#   You can call valet without any commands to start an interactive session.
+#
+#   ⌜Exit codes:⌝
+#
+#   - 0: everything went well
+#   - 1+: an error occured
+#
+#   ⌜Create your own commands:⌝
+#
+#   You can create your own commands and have them available in valet, please check https://jcaillon.github.io/valet/docs/new-commands/ or the examples under examples.d to do so.
+#   Valet looks for commands in the valet user directory, which default to ~/.valet.d and can be overwritten using an environment variable (see below).
+#   Once you have created your new command script, run the ⌜valet self build⌝ command to update the valet menu.
+#
+#   ⌜Configuration through environment variables:⌝
+#
+#   In addition to the environment variables defined for each options, you can define environment variables to configure valet.
+#
+#   These variables are conviently defined in the valet user config file, located by default at ~/.config/valet/config (the path to this file can be configured using the VALET_CONFIG_FILE environment variable).
+#
+#   You can run ⌜valet self config⌝ to open the configuration file with your default editor (the file will get created if it does not yet exist).
+#
+#   ⌜Developer notes:⌝
+#
+#   You can enable debug mode with profiling for valet by setting the environment variable VALET_CONFIG_STARTUP_PROFILING to true (it will output to ~/valet-profiler-{PID}.txt).
+# arguments:
+# - name: commands?...
+#   description: |-
+#     The command or sub commands to execute.
+#     See the commands section for more information.
+# options:
+# - name: -x, --profiling
+#   description: |-
+#     Turn on profiling (with debug mode) before running the required command.
+#     It will output to ~/valet-profiler-{PID}-command.txt.
+#     This is useful to debug your command and understand what takes a long time to execute.
+#     The profiler log will be cleanup to only keep lines relevant for your command script. You can disable this behavior by setting the environment variable VALET_CONFIG_KEEP_ALL_PROFILER_LINES to true.
+# - name: -l, --log-level, --log <level>
+#   description: |-
+#     Set the log level of valet (defaults to info).
+#     Possible values are: trace, debug, success, info, success, warning, error.
+# - name: -v, --verbose
+#   description: |-
+#     Output verbose information.
+#     This is the equivalent of setting the log level to debug.
+# - name: -w, --very-verbose
+#   description: |-
+#     Output very verbose information.
+#     This is the equivalent of setting the log level to trace.
+# - name: -i, --force-interactive-mode
+#   description: |-
+#     Enter interactive mode for commands even if arguments are not required or provided.
+# - name: --version
+#   description: |-
+#     Display the current version of valet.
+#   noEnvironmentVariable: true
+# examples:
+# - name: --help
+#   description: |-
+#     Displays this help text.
+# - name: -v a-command and-sub-command
+#   description: |-
+#     Active ⌜verbose⌝ mode and run the command ⌜a-command⌝ with the sub command ⌜and-sub-command⌝.
+##VALET_COMMAND
 
 #===============================================================
 # >>> Include core/utils

valet.d/commands.d/self-build-utils

@@ -17,27 +17,38 @@ function extractCommandYamls() {
 
   local firstLine=": \"---"
   local lastLine="---\""
+  local firstLineAlt="##<<VALET_COMMAND"
+  local lastLineAlt="##VALET_COMMAND"
 
   declare -a contentArray
 
   local line content
-  local -i firstLineMatched=0 lastLineMatched=1
+  local -i firstLineMatched=0 lastLineMatched=1 indentation=0
   while IFS= read -r line || [[ -n ${line:-} ]]; do
     if [[ firstLineMatched -eq 0 ]]; then
-      if [[ ${line} == "${firstLine}" ]]; then
+      if [[ ${line} == "${firstLine}" || ${line} == "${firstLineAlt}" ]]; then
         firstLineMatched=1
         lastLineMatched=0
         content=""
+        if [[ ${line} == "${firstLineAlt}" ]]; then
+          indentation=2
+        else
+          indentation=0
+        fi
         continue
       fi
     elif [[ lastLineMatched -eq 0 ]]; then
-      if [[ ${line} == "${lastLine}" ]]; then
+      if [[ ${line} == "${lastLine}" || ${line} == "${lastLineAlt}" ]]; then
         lastLineMatched=1
         firstLineMatched=0
         contentArray+=("${content}")
         continue
       fi
-      content+="${line}"$'\n'
+      if ((indentation > 0)); then
+        content+="${line:indentation}"$'\n'
+      else
+        content+="${line}"$'\n'
+      fi
     fi
   done <"${file}"
 

valet.d/commands.d/self-release.sh

@@ -83,7 +83,7 @@ function selfRelease() {
     uploadArtifact "${uploadUrl}"
   fi
 
-  log::success "The new version has been released, check: ⌜https://github.com/jcaillon/valet/releases/latest⌝."
+  log::success "The new version has been released, check: https://github.com/jcaillon/valet/releases/latest."
 
   return 0
 }

valet.d/commands.d/self-setup.sh

@@ -90,5 +90,5 @@ function selfSetup() {
   # tell the user about what's next todo
   log::info "As a reminder, you can modify the configuration done during this set up by either:"$'\n'"- replaying the command ⌜valet self setup⌝,"$'\n'"- running the command ⌜valet self config⌝."
   log::info "Run ⌜valet --help⌝ to get started."
-  log::info "You can create your own commands and have them available in valet, please check ⌜https://jcaillon.github.io/valet/docs/new-commands/⌝ to do so."
+  log::info "You can create your own commands and have them available in valet, please check https://jcaillon.github.io/valet/docs/new-commands/ to do so."
 }

valet.d/main

@@ -187,7 +187,7 @@ function main::getHelpText() {
 
   local -i helpWidth
   helpWidth="${maxColumns}"
-  if [[ helpWidth -gt ${GLOBAL_COLUMNS} ]]; then helpWidth=${GLOBAL_COLUMNS}; fi
+  if (( helpWidth > GLOBAL_COLUMNS )); then helpWidth=${GLOBAL_COLUMNS}; fi
 
   if [[ ${type} == "function" ]]; then
     # case of a function; we will get the description from CMD_ vars directly

valet.d/version

@@ -1 +1 @@
-0.18.290
+0.18.298