Skip to content

Commit

Permalink
✨ self extend to create extensions
Browse files Browse the repository at this point in the history
  • Loading branch information
jcaillon committed Dec 3, 2024
1 parent 1bc6f91 commit f76d21a
Show file tree
Hide file tree
Showing 15 changed files with 173 additions and 76 deletions.
3 changes: 2 additions & 1 deletion .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
{
// https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html
"bashIde.globPattern": "**/@(core|main|lib-!(valet)|self-*)",
"bashIde.includeAllWorkspaceSymbols": true
"bashIde.includeAllWorkspaceSymbols": true,
"terminal.integrated.wordSeparators": " ()[]{}',\"`─‘’“”|⌜⌝"
}
8 changes: 7 additions & 1 deletion docs/content/docs/002.installation/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,11 @@ Finally, call `valet` to get started with the example commands!
2. Add this directory to your PATH so you can call `valet` from your terminal.
3. Call `valet` to get started with the example commands!

## ⚙️ Extra config for your terminal

- **Nerd font**: Valet can make use of [Nerd fonts][nerdFontsLink] to display icons in the logs and interactive sessions. You can download any nerd font from [here][nerdFontsLink], install it, and configure your terminal to use that font.
- **Word separator**: Valet usually prints important values between ⌜quotes⌝ using the UTF8 top left and top right corners (respectively U+231C and U+231D). You can add these two characters as word separators in your terminal for quick double click selection: `⌜⌝`.

## 🪟 Use Valet on windows

It is recommended to use Git bash, installed with [Git for Windows][git-for-windows-link] and [Windows terminal][windows-terminal-link] as your terminal program. You can also use Valet with any Linux distribution and [Windows Subsystem for Linux][wsl-installation-link] (WSL).
Expand Down Expand Up @@ -79,4 +84,5 @@ Alternatively, use `docker run --rm -it noyacode/valet` to pull and run the imag
[selfInstallCommandUsageLink]: https://github.com/jcaillon/valet/blob/latest/tests.d/1106-self-update/results.approved.md
[docker]: https://www.docker.com/
[podman]: https://podman.io/
[valetImageTagsLink]: https://github.com/jcaillon/valet/pkgs/container/valet
[valetImageTagsLink]: https://github.com/jcaillon/valet/pkgs/container/valet
[nerdFontsLink]: https://www.nerdfonts.com/font-downloads
2 changes: 1 addition & 1 deletion docs/content/docs/500.working-on-bash/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ You can open your `~/.valet.d` directory as a workspace on vscode.

### Autocompletion on Valet library functions

You can use the Valet [vscode snippets](https://github.com/jcaillon/valet/blob/latest/extras/.vscode/valet.code-snippets) which should be generated locally using the `valet self document` command.
You can use the Valet [vscode snippets](https://github.com/jcaillon/valet/blob/latest/extras/valet.code-snippets) which should be generated locally using the `valet self document` command.

Then:

Expand Down
3 changes: 2 additions & 1 deletion extras/.vscode/settings.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
{
// https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html
"bashIde.globPattern": "**/@(lib-*|src/*.sh)",
"bashIde.includeAllWorkspaceSymbols": true
"bashIde.includeAllWorkspaceSymbols": true,
"terminal.integrated.wordSeparators": " ()[]{}',\"`─‘’“”|⌜⌝"
}
File renamed without changes.
16 changes: 8 additions & 8 deletions tests.d/1102-self-build/results.approved.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Exit code: `0`
```plaintext
CMD_ALL_COMMANDS=$'self\nhelp\nself build\nself config\nself document\nself export\nself extend\nself mock1\nself mock2\nself mock3\nself mock4\nself release\nself setup\nself test\nself uninstall\nself update'
CMD_ALL_COMMANDS_ARRAY=0 "help" 1 "self build" 2 "self config" 3 "self document" 4 "self export" 5 "self extend" 6 "self mock1" 7 "self mock2" 8 "self mock3" 9 "self mock4" 10 "self release" 11 "self setup" 12 "self test" 13 "self uninstall" 14 "self update"
CMD_ALL_COMMAND_SELECTION_ITEMS_ARRAY=0 "help Show the help of this program or of a specific command." 1 "self build Index all the commands and libraries present in the valet user directory and installation directory." 2 "self config Open the configuration file of Valet with your default editor." 3 "self document Generate the documentation and code snippets for all the library functions of Valet." 4 "self extend Extends Valet by downloading a new application or library in the user directory." 5 "self test Test your valet custom commands." 6 "self update Update valet and its extensions to the latest releases."
CMD_ALL_COMMAND_SELECTION_ITEMS_ARRAY=0 "help Show the help of this program or of a specific command." 1 "self build Index all the commands and libraries present in the valet user directory and installation directory." 2 "self config Open the configuration file of Valet with your default editor." 3 "self document Generate the documentation and code snippets for all the library functions of Valet." 4 "self extend Extends Valet by creating or downloading a new extension in the user directory." 5 "self test Test your valet custom commands." 6 "self update Update valet and its extensions to the latest releases."
CMD_ALL_FUNCTIONS=$'this\nshowCommandHelp\nselfBuild\nselfConfig\nselfDocument\nselfExport\nselfExtend\nselfUpdate\nselfMock1\nselfMock2\nselfMock3\nselfMock4\nselfRelease\nselfSetup\nselfTest\nselfUninstall'
CMD_ALL_FUNCTIONS_ARRAY=0 "this" 1 "showCommandHelp" 2 "selfBuild" 3 "selfConfig" 4 "selfDocument" 5 "selfExport" 6 "selfExtend" 7 "selfUpdate" 8 "selfMock1" 9 "selfMock2" 10 "selfMock3" 11 "selfMock4" 12 "selfRelease" 13 "selfSetup" 14 "selfTest" 15 "selfUninstall"
CMD_ALL_MENU_COMMANDS_ARRAY=0 "self"
Expand All @@ -21,7 +21,7 @@ CMD_ARGS_LAST_IS_ARRAY_selfMock2='true'
CMD_ARGS_LAST_IS_ARRAY_selfMock4='false'
CMD_ARGS_LAST_IS_ARRAY_showCommandHelp='true'
CMD_ARGS_LAST_IS_ARRAY_this='true'
CMD_ARGS_NAME_selfExtend=0 "repositoryUri"
CMD_ARGS_NAME_selfExtend=0 "extensionUri"
CMD_ARGS_NAME_selfMock1=0 "action"
CMD_ARGS_NAME_selfMock2=0 "firstArg" 1 "more"
CMD_ARGS_NAME_selfMock4=0 "firstArg" 1 "secondArg"
Expand All @@ -33,19 +33,19 @@ CMD_ARGS_NB_OPTIONAL_selfMock2='0'
CMD_ARGS_NB_OPTIONAL_selfMock4='0'
CMD_ARGS_NB_OPTIONAL_showCommandHelp='1'
CMD_ARGS_NB_OPTIONAL_this='1'
CMD_ARGUMENTS_DESCRIPTION_selfExtend=0 $'The URL of the repository to download and install in Valet.\n\nUsually a GitHub or GitLab repository URL such as `https://github.com/jcaillon/valet-devops-toolbox.git`.\n\nIf the repository is private, you can pass the URL with the username and password like this:\n`https://username:[email protected]/group/project.git`.'
CMD_ARGUMENTS_DESCRIPTION_selfExtend=0 $'The URI of the extension to install or create.\n\n1. If you want to create a new extension, this argument should be the name of your\n new extension (e.g. `my-new-extension`).\n2. If you want to setup an existing directory as an extension, this argument should be `.`.\n3. If you want to download an extension, this argument should be the URL of the repository.\n Usually a GitHub or GitLab repository URL such as `https://github.com/jcaillon/valet-devops-toolbox.git`.\n\n> If the repository is private, you can pass the URL with the username and password like this:\n> `https://username:[email protected]/group/project.git`.'
CMD_ARGUMENTS_DESCRIPTION_selfMock1=0 $'The action to perform.\nOne of the following options:\n\n- error\n- fail\n- fail2\n- exit\n- unknown-command\n- create-temp-files\n- logging-level\n- wait-indefinitely\n- show-help\n- print-raw-and-file\n'
CMD_ARGUMENTS_DESCRIPTION_selfMock2=0 "First argument." 1 "Will be an an array of strings."
CMD_ARGUMENTS_DESCRIPTION_selfMock4=0 "First argument." 1 $'Second argument.\n'
CMD_ARGUMENTS_DESCRIPTION_showCommandHelp=0 $'The name of the command to show the help for.\nIf not provided, show the help for the program.'
CMD_ARGUMENTS_DESCRIPTION_this=0 $'The command or sub commands to execute.\nSee the commands section for more information.'
CMD_ARGUMENTS_NAME_selfExtend=0 "repositoryUri"
CMD_ARGUMENTS_NAME_selfExtend=0 "extensionUri"
CMD_ARGUMENTS_NAME_selfMock1=0 "action"
CMD_ARGUMENTS_NAME_selfMock2=0 "firstArg" 1 "more..."
CMD_ARGUMENTS_NAME_selfMock4=0 "firstArg" 1 "secondArg"
CMD_ARGUMENTS_NAME_showCommandHelp=0 "commands?..."
CMD_ARGUMENTS_NAME_this=0 "commands?..."
CMD_COMMANDS_DESCRIPTION_this=0 "Show the help of this program or of a specific command." 1 "Index all the commands and libraries present in the valet user directory and installation directory." 2 "Open the configuration file of Valet with your default editor." 3 "Generate the documentation and code snippets for all the library functions of Valet." 4 "Returns a string that can be evaluated to have Valet functions in bash." 5 "Extends Valet by downloading a new application or library in the user directory." 6 "A command that only for testing valet core functions." 7 "A command that only for testing valet core functions." 8 "A command that only for testing valet core functions." 9 "A command that only for testing valet core functions." 10 "Release a new version of valet." 11 "The command run after the installation of Valet to setup the tool." 12 "Test your valet custom commands." 13 "A command to uninstall Valet." 14 "Update valet and its extensions to the latest releases."
CMD_COMMANDS_DESCRIPTION_this=0 "Show the help of this program or of a specific command." 1 "Index all the commands and libraries present in the valet user directory and installation directory." 2 "Open the configuration file of Valet with your default editor." 3 "Generate the documentation and code snippets for all the library functions of Valet." 4 "Returns a string that can be evaluated to have Valet functions in bash." 5 "Extends Valet by creating or downloading a new extension in the user directory." 6 "A command that only for testing valet core functions." 7 "A command that only for testing valet core functions." 8 "A command that only for testing valet core functions." 9 "A command that only for testing valet core functions." 10 "Release a new version of valet." 11 "The command run after the installation of Valet to setup the tool." 12 "Test your valet custom commands." 13 "A command to uninstall Valet." 14 "Update valet and its extensions to the latest releases."
CMD_COMMANDS_NAME_this=0 "help" 1 "self build" 2 "self config" 3 "self document" 4 "self export" 5 "self extend" 6 "self mock1" 7 "self mock2" 8 "self mock3" 9 "self mock4" 10 "self release" 11 "self setup" 12 "self test" 13 "self uninstall" 14 "self update"
CMD_COMMAND_selfBuild='self build'
CMD_COMMAND_selfConfig='self config'
Expand All @@ -68,7 +68,7 @@ CMD_DESCRIPTION_selfBuild=$'Index all the command and libraries present in the v
CMD_DESCRIPTION_selfConfig=$'Open the configuration file of Valet with your default editor.\n\nThis allows you to set advanced options for Valet.'
CMD_DESCRIPTION_selfDocument=$'Generate the documentation and code snippets for all the library functions of Valet.\n\nIt will parse all the library files and generate:\n\n- A markdown file with the documentation.\n- A bash file with the prototype of each function.\n- A vscode snippet file for each function.'
CMD_DESCRIPTION_selfExport=$'If you want to use Valet functions directly in bash, you can use this command like this:\n\n```bash\neval "$(valet self export 2>/dev/null)"\n```\n\nThis will export all the necessary functions and variables to use the Valet log library by default.\n\nYou can optionally export all the functions if needed.'
CMD_DESCRIPTION_selfExtend=$'Extends Valet by downloading a new application or library in the user directory.\n\n- Applications usually add new commands to Valet.\n- Libraries usually add new callable functions to Valet.\n\nThis command will download the given repository and install it in the Valet user directory.\nIf a `extension.setup.sh` script is present in the repository root directory, it will be executed.\n\nFor GitHub and GitLab repositories, this command will:\n\n1. If git is installed, clone the repository for the given reference (version option).\n2. Otherwise, download source tarball for the given reference and extract it.\n\nOnce an extension is installed, you can use the `valet self update` command to update it.'
CMD_DESCRIPTION_selfExtend=$'Extends Valet by creating or downloading a new extension in the user directory.\nExtensions can add new commands or functions to Valet.\n\nThis command will either:\n\n- Create and setup a new extension directory under the valet user directory,\n- setup an existing directory as a valet extension,\n- or download the given extension (repository) and install it in the Valet user directory.\n\nFor downloaded extensions, all GIT repositories are supported.\nFor the specific cases of GitHub and GitLab repositories, this command will:\n\n1. If git is installed, clone the repository for the given reference (version option).\n2. If git is not installed, download source tarball for the given reference and extract it.\n\nFor downloaded extensions, if a `extension.setup.sh` script is present in the repository root directory,\nit will be executed. This gives the extension the opportunity to setup itself.\n\nOnce an extension is installed, you can use the `valet self update` command to update it.'
CMD_DESCRIPTION_selfMock1='A command that only for testing valet core functions.'
CMD_DESCRIPTION_selfMock2=$'An example of description.\n\nYou can put any text here, it will be wrapped to fit the terminal width.\n\nYou can highlight some text as well.'
CMD_DESCRIPTION_selfMock3=$'Before starting this command, valet will check if sudo is available.\n\nIf so, it will require the user to enter the sudo password and use sudo inside the command\n'
Expand Down Expand Up @@ -255,7 +255,7 @@ CMD_SHORT_DESCRIPTION_selfBuild='Index all the commands and libraries present in
CMD_SHORT_DESCRIPTION_selfConfig='Open the configuration file of Valet with your default editor.'
CMD_SHORT_DESCRIPTION_selfDocument='Generate the documentation and code snippets for all the library functions of Valet.'
CMD_SHORT_DESCRIPTION_selfExport='Returns a string that can be evaluated to have Valet functions in bash.'
CMD_SHORT_DESCRIPTION_selfExtend='Extends Valet by downloading a new application or library in the user directory.'
CMD_SHORT_DESCRIPTION_selfExtend='Extends Valet by creating or downloading a new extension in the user directory.'
CMD_SHORT_DESCRIPTION_selfMock1='A command that only for testing valet core functions.'
CMD_SHORT_DESCRIPTION_selfMock2='A command that only for testing valet core functions.'
CMD_SHORT_DESCRIPTION_selfMock3='A command that only for testing valet core functions.'
Expand Down Expand Up @@ -328,7 +328,7 @@ help Show the help of this program or of a specific command.
self build Index all the commands and libraries present in the valet user directory and installation directory.
self config Open the configuration file of Valet with your default editor.
self document Generate the documentation and code snippets for all the library functions of Valet.
self extend Extends Valet by downloading a new application or library in the user directory.
self extend Extends Valet by creating or downloading a new extension in the user directory.
self test Test your valet custom commands.
self update Update valet and its extensions to the latest releases.
Expand Down
6 changes: 3 additions & 3 deletions tests.d/1103-self-release/results.approved.md
Original file line number Diff line number Diff line change
Expand Up @@ -226,8 +226,8 @@ INFO The documentation has been generated in ⌜$GLOBAL_VALET_HOME/extras/li
▶ called io::writeToFile $GLOBAL_VALET_HOME/extras/lib-valet
▶ called io::writeToFile $GLOBAL_VALET_HOME/extras/lib-valet
INFO The prototype script has been generated in ⌜$GLOBAL_VALET_HOME/extras/lib-valet⌝.
▶ called io::writeToFile $GLOBAL_VALET_HOME/extras/.vscode/valet.code-snippets
INFO The vscode snippets have been generated in ⌜$GLOBAL_VALET_HOME/extras/.vscode/valet.code-snippets⌝.
▶ called io::writeToFile $GLOBAL_VALET_HOME/extras/valet.code-snippets
INFO The vscode snippets have been generated in ⌜$GLOBAL_VALET_HOME/extras/valet.code-snippets⌝.
▶ called io::invoke rm -f $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/array.md
▶ called io::invoke rm -f $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/codes.md
▶ called io::invoke rm -f $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/core.md
Expand Down Expand Up @@ -256,7 +256,7 @@ INFO The vscode snippets have been generated in ⌜$GLOBAL_VALET_HOME/extras
▶ called io::invoke cp $GLOBAL_VALET_HOME/.vscode/extensions.json $GLOBAL_VALET_HOME/extras/extensions.json
▶ called io::invoke git add $GLOBAL_VALET_HOME/docs/static/config.md
▶ called io::invoke git add $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/array.md $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/codes.md $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/core.md $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/fsfs.md $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/interactive.md $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/io.md $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/kurl.md $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/log.md $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/profiler.md $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/string.md $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/system.md $GLOBAL_VALET_HOME/docs/content/docs/300.libraries/test.md
▶ called io::invoke git add $GLOBAL_VALET_HOME/extras/base.code-snippets $GLOBAL_VALET_HOME/extras/lib-valet $GLOBAL_VALET_HOME/extras/lib-valet.md
▶ called io::invoke git add $GLOBAL_VALET_HOME/extras/base.code-snippets $GLOBAL_VALET_HOME/extras/lib-valet $GLOBAL_VALET_HOME/extras/lib-valet.md $GLOBAL_VALET_HOME/extras/valet.code-snippets
▶ called io::invoke git commit -m :memo: updating the documentation
SUCCESS The documentation update has been committed.
▶ called io::invoke sed -E -i s/VALET_RELEASED_VERSION="[0-9]+\.[^"]+"/VALET_RELEASED_VERSION="1.2.3"/ $GLOBAL_VALET_HOME/valet.d/commands.d/self-install.sh
Expand Down
21 changes: 19 additions & 2 deletions tests.d/1106-self-install/test
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,24 @@ function main() {




echo "================================================"
echo "Create extension: test-extension1."
echo "================================================"

valet self extend test-extension1

echo "================================================"
echo "Setup extension directory: test-extension2."
echo "================================================"

mkdir -p ~/.valet.d/test-extension2
pushd ~/.valet.d/test-extension2 &>/dev/null
valet self extend .
popd &>/dev/null



echo "================================================"
echo "Updating Valet: --skip-extensions."
echo "================================================"
Expand Down Expand Up @@ -219,5 +237,4 @@ function main() {

main

eval "$(valet self export -a)"
log::success "Self install test passed."
echo "Self install test passed."
4 changes: 2 additions & 2 deletions tests.d/1107-self-document/01.self-document.sh
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ function testSelfDocument() {
echo "→ cat ${directory}/lib-valet"
io::cat "${directory}/lib-valet"
echo
echo "→ cat ${directory}/.vscode/valet.code-snippets"
io::cat "${directory}/.vscode/valet.code-snippets"
echo "→ cat ${directory}/valet.code-snippets"
io::cat "${directory}/valet.code-snippets"

test::endTest "Testing selfDocument" 0
}
Expand Down
Loading

0 comments on commit f76d21a

Please sign in to comment.