📝 updating the documentation

docs/content/docs/300.libraries/array.md

@@ -102,7 +102,7 @@ It uses pure bash.
 
 - $1: **array name** _as string_:
       The global variable name of the array.
-- $2: **value** _as any:
+- $2: **value** _as any_:
       The value to check.
 
 Returns:
@@ -146,7 +146,7 @@ printf '%s\n' "${myArray[@]}"
 
 ## array::sortWithCriteria
 
-Sorts an array using mulitple criteria.
+Sorts an array using multiple criteria.
 Excepts multiple arrays. The first array is the one to sort.
 The other arrays are used as criteria. Criteria are used in the order they are given.
 Each criteria array must have the same size as the array to sort.
@@ -178,4 +178,4 @@ printf '%s\n' "${RETURNED_ARRAY[@]}"
 
 
 
-> Documentation generated for the version 0.26.6 (2024-11-24).
+> Documentation generated for the version 0.27.285 (2024-12-05).

docs/content/docs/300.libraries/codes.md

@@ -34,4 +34,4 @@ Ascii graphics:
 
 
 
-> Documentation generated for the version 0.26.6 (2024-11-24).
+> Documentation generated for the version 0.27.285 (2024-12-05).

docs/content/docs/300.libraries/core.md

@@ -27,6 +27,17 @@ core::checkParseResults "${help:-}" "${parsingErrors:-}" "myFunctionName"
 ```
 
 
+## core::deleteUserCommands
+
+Delete the user 'commands' file from the valet user directory.
+
+You probably want to reload the user commands afterward using `core::reloadUserCommands`.
+
+```bash
+core::deleteUserCommands
+```
+
+
 ## core::fail
 
 Displays an error message and then exit the program with error.
@@ -219,4 +230,4 @@ specify the included file for spellcheck.
 
 
 
-> Documentation generated for the version 0.26.6 (2024-11-24).
+> Documentation generated for the version 0.27.285 (2024-12-05).

docs/content/docs/300.libraries/curl.md

@@ -0,0 +1,67 @@
+---
+title: 📂 curl
+cascade:
+  type: docs
+url: /docs/libraries/curl
+---
+
+## curl::toFile
+
+This function is a wrapper around curl.
+It allows you to check the http status code and return 1 if it is not acceptable.
+It io::invokes curl with the following options (do not repeat them): -sSL -w "%{response_code}" -o ${2}.
+
+- $1: **fail** _as bool_:
+      true/false to indicate if the function should fail in case the execution fails
+- $2: **acceptable codes** _as string_:
+      list of http status codes that are acceptable, comma separated
+      (defaults to 200,201,202,204,301,304,308 if left empty)
+- $3: **path** _as string_:
+      the file in which to save the output of curl
+- $@: **curl arguments** _as any_:
+      options for curl
+
+Returns:
+
+- $?:
+  - 0 if the http status code is acceptable
+  - 1 otherwise
+- `RETURNED_VALUE`: the content of stderr
+- `RETURNED_VALUE2`: the http status code
+
+```bash
+curl::toFile "true" "200,201" "/filePath" "https://example.com" || core::fail "The curl command failed."
+```
+
+
+## curl::toVar
+
+This function is a wrapper around curl.
+It allows you to check the http status code and return 1 if it is not acceptable.
+It io::invokes curl with the following options (do not repeat them): -sSL -w "%{response_code}" -o "tempfile".
+
+- $1: **fail** _as bool_:
+      true/false to indicate if the function should fail in case the execution fails
+- $2: **acceptable codes** _as string_:
+      list of http status codes that are acceptable, comma separated
+      (defaults to 200,201,202,204,301,304,308 if left empty)
+- $@: **curl arguments** _as any_:
+      options for curl
+
+Returns:
+
+- $?:
+  - 0 if the http status code is acceptable
+  - 1 otherwise
+- `RETURNED_VALUE`: the content of the request
+- `RETURNED_VALUE2`: the content of stderr
+- `RETURNED_VALUE3`: the http status code
+
+```bash
+curl::toVar false 200,201 https://example.com || core::fail "The curl command failed."
+```
+
+
+
+
+> Documentation generated for the version 0.27.285 (2024-12-05).

docs/content/docs/300.libraries/fsfs.md

@@ -45,4 +45,4 @@ log::info "You selected: ⌜${RETURNED_VALUE}⌝ (index: ⌜${RETURNED_VALUE2}
 
 
 
-> Documentation generated for the version 0.26.6 (2024-11-24).
+> Documentation generated for the version 0.27.285 (2024-12-05).

docs/content/docs/300.libraries/interactive.md

@@ -414,11 +414,11 @@ Wait for a key press (single key).
 You can pass additional parameters to the read command (e.g. to wait for a set amount of time).
 
 It uses the read builtin command with the option `-e` to use readline behind the scene.
-This means we can detect more key combinations but all keys needs to be binded first...
+This means we can detect more key combinations but all keys needs to be bound first...
 Special keys (CTRL+, ALT+, F1-F12, arrows, etc.) are intercepted using binding.
 
 You must call `interactive::rebindKeymap` and `interactive::sttyInit` before using this function.
-You must also redefine the function `interactiveOnKeyBindingPress` to react to a binded key press.
+You must also redefine the function `interactiveOnKeyBindingPress` to react to a bound key press.
 See @interactive::testWaitForKeyPress for an implementation example.
 
 - $@: **read parameters** _as any_:
@@ -442,4 +442,4 @@ interactive::waitForKeyPress -t 0.1
 
 
 
-> Documentation generated for the version 0.26.6 (2024-11-24).
+> Documentation generated for the version 0.27.285 (2024-12-05).

docs/content/docs/300.libraries/io.md

@@ -59,6 +59,42 @@ io::cleanupTempFiles
 shellcheck disable=SC2016
 
 
+## io::convertFromWindowsPath
+
+Convert a Windows path to a unix path.
+
+- $1: **path** _as string_:
+      the path to convert
+
+Returns:
+
+- `RETURNED_VALUE`: The unix path.
+
+```bash
+io::convertFromWindowsPath "C:\path\to\file"
+```
+
+> Handles paths starting with `X:\`.
+
+
+## io::convertToWindowsPath
+
+Convert a unix path to a Windows path.
+
+- $1: **path** _as string_:
+      the path to convert
+
+Returns:
+
+- `RETURNED_VALUE`: The Windows path.
+
+```bash
+io::convertToWindowsPath "/path/to/file"
+```
+
+> Handles paths starting with `/mnt/x/` or `/x/`.
+
+
 ## io::countArgs
 
 Returns the number of arguments passed.
@@ -82,6 +118,22 @@ io::countArgs 1 2 3
 ```
 
 
+## io::createDirectoryIfNeeded
+
+Create the directory tree if needed.
+
+- $1: **path** _as string_:
+      The directory path to create.
+
+Returns:
+
+- `RETURNED_VALUE`: The absolute path to the directory.
+
+```bash
+io::createDirectoryIfNeeded "/my/directory"
+```
+
+
 ## io::createFilePathIfNeeded
 
 Make sure that the given file path exists.
@@ -99,6 +151,40 @@ io::createFilePathIfNeeded "myFile"
 ```
 
 
+## io::createLink
+
+Create a soft or hard link (original ← link).
+
+Reminder:
+
+- A soft (symbolic) link is a new file that contains a reference to another file or directory in the
+  form of an absolute or relative path.
+- A hard link is a directory entry that associates a new pathname with an existing
+  file (inode + data block) on a file system.
+
+This function allows to create a symbolic link on Windows as well as on Unix.
+
+- $1: **linked path** _as string_:
+      the path to link to (the original file)
+- $2: **link path** _as string_:
+      the path where to create the link
+- $3: hard link _as boolean_:
+      (optional) true to create a hard link, false to create a symbolic link
+      (defaults to false)
+- $4: force _as boolean_:
+      (optional) true to overwrite the link or file if it already exists.
+      Otherwise, the function will fail on an existing link.
+      (defaults to true)
+
+```bash
+io::createLink "/path/to/link" "/path/to/linked"
+io::createLink "/path/to/link" "/path/to/linked" true
+```
+
+> On unix, the function uses the `ln` command.
+> On Windows, the function uses `powershell` (and optionally ls to check the existing link).
+
+
 ## io::createTempDirectory
 
 Creates a temporary directory.
@@ -324,7 +410,7 @@ stderrFilePath="${RETURNED_VALUE2}"
 >   `io::invokef5 false 0 false '' mycommand && myvar="${RETURNED_VALUE}"`
 >   than doing:
 >   `myvar="$(mycommand)".`
-> - On linux, it is slighly faster (but it might be slower if you don't have SSD?).
+> - On linux, it is slightly faster (but it might be slower if you don't have SSD?).
 > - On linux, you can use a tmpfs directory for massive gains over subshells.
 
 
@@ -518,6 +604,105 @@ local myFileAbsolutePath="${RETURNED_VALUE}"
 > This is a pure bash alternative to `realpath` or `readlink`.
 
 
+## io::windowsCreateTempDirectory
+
+Create a temporary directory on Windows and return the path both for Windows and Unix.
+
+This is useful for creating temporary directories that can be used in both Windows and Unix.
+
+Returns:
+
+- `RETURNED_VALUE`: The Windows path.
+- `RETURNED_VALUE2`: The Unix path.
+
+```bash
+io::windowsCreateTempDirectory
+```
+
+> Directories created this way are automatically cleaned up by the io::cleanupTempFiles
+> function when valet ends.
+
+
+## io::windowsCreateTempFile
+
+Create a temporary file on Windows and return the path both for Windows and Unix.
+
+This is useful for creating temporary files that can be used in both Windows and Unix.
+
+Returns:
+
+- `RETURNED_VALUE`: The Windows path.
+- `RETURNED_VALUE2`: The Unix path.
+
+```bash
+io::windowsCreateTempFile
+```
+
+> Files created this way are automatically cleaned up by the io::cleanupTempFiles
+> function when valet ends.
+
+
+## io::windowsPowershellBatchEnd
+
+This function will run all the commands that were batched with `io::windowsPowershellBatchStart`.
+
+Returns:
+
+- $?
+  - 0 if the command was successful
+  - 1 otherwise.
+- `RETURNED_VALUE`: The content of stdout.
+- `RETURNED_VALUE2`: The content of stderr.
+
+```bash
+io::windowsPowershellBatchStart
+io::windowsRunInPowershell "Write-Host \"Hello\""
+io::windowsRunInPowershell "Write-Host \"World\""
+io::windowsPowershellBatchEnd
+```
+
+
+## io::windowsPowershellBatchStart
+
+After running this function, all commands that should be executed by
+`io::windowsRunInPowershell` will be added to a batch that will only be played
+when `io::windowsPowershellBatchEnd` is called.
+
+This is a convenient way to run multiple commands in a single PowerShell session.
+It makes up for the fact that running a new PowerShell session for each command is slow.
+
+```bash
+io::windowsPowershellBatchStart
+io::windowsRunInPowershell "Write-Host \"Hello\""
+io::windowsRunInPowershell "Write-Host \"World\""
+io::windowsPowershellBatchEnd
+```
+
+
+## io::windowsRunInPowershell
+
+Runs a PowerShell command.
+This is mostly useful on Windows.
+
+- $1: **command** _as string_:
+      the command to run.
+- $2: run as administrator _as boolean_:
+      (optional) whether to run the command as administrator.
+      (defaults to false).
+
+Returns:
+
+- $?
+  - 0 if the command was successful
+  - 1 otherwise.
+- `RETURNED_VALUE`: The content of stdout.
+- `RETURNED_VALUE2`: The content of stderr.
+
+```bash
+io::windowsRunInPowershell "Write-Host \"Press any key:\"; Write-Host -Object ('The key that was pressed was: {0}' -f [System.Console]::ReadKey().Key.ToString());"
+```
+
+
 
 
-> Documentation generated for the version 0.26.6 (2024-11-24).
+> Documentation generated for the version 0.27.285 (2024-12-05).

docs/content/docs/300.libraries/log.md

@@ -238,4 +238,4 @@ log::warning "This is a warning message."
 
 
 
-> Documentation generated for the version 0.26.6 (2024-11-24).
+> Documentation generated for the version 0.27.285 (2024-12-05).

docs/content/docs/300.libraries/profiler.md

@@ -30,4 +30,4 @@ profiler::enable "${HOME}/valet-profiler-${BASHPID}.txt"
 
 
 
-> Documentation generated for the version 0.26.6 (2024-11-24).
+> Documentation generated for the version 0.27.285 (2024-12-05).