From bd3756df8364394fda20faba2dbcf587b0f70497 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Hohwiller?= Date: Fri, 7 Oct 2022 18:38:32 +0200 Subject: [PATCH] #751: improved function documentation --- documentation/functions.asciidoc | 155 ++++++++++++++++++------------- 1 file changed, 90 insertions(+), 65 deletions(-) diff --git a/documentation/functions.asciidoc b/documentation/functions.asciidoc index e370ac842..4b030deaf 100644 --- a/documentation/functions.asciidoc +++ b/documentation/functions.asciidoc @@ -5,102 +5,122 @@ toc::[] = Documentations of functions == Functions for testing flags -The functions for testing flags return a 0 if the corresponding flag is set in the form of a variable. +The functions for testing flags return `0` (true) if flag is set and `1` (false) otherwise. The name of the flag is part of the function name. === doIsBatch -This function returns a 0 if the variable "batch" is set. +Determines if `batch` mode is active. +This mode shall be used for non-interactive usage (e.g. in automated invocations) where no user is available for interactive feedback. +It can be enabled with `-b` or `--batch`. === doIsDebug -This function returns a 0 if the variable "debug" is set and the -q option is not specified. +Determines if `debug` mode is active. +This mode activates more verbose output for debugging. +It can be enabled with `-d` or `--debug`. === doIsForce -This function returns a 0 if the variable "force" is set. +Determines if `force` mode is active. +This mode enforces specific aspects such as xref:doDownload[downloading] cached resources again or to answer xref:doAskToContinue[questions to continue] automatically with `yes`. +It can be enabled with option `-f` or `--force`. === doIsQuiet -This function returns a 0 if the variable "quiet" is set. +Determines if `quiet` mode is active. +This mode reduces the output to a minimum so information messages are suppressed. +It can be enabled with option `-q` or `--quiet`. == Functions for input and output +Output functions like xref:doEcho[] support backslash-escaped characters, for example "\n" for new line. + === doAskToContinue -A message can be passed as the first parameter to the doAskToContinue function. -If this is not done, the standard message "Do you want to continue?" used. -If the variable force is set, the message is output and the function ends directly with the return value 0. -If neither the variable force nor the variable batch is set, the message is output in a loop and the input of yes, no or no input at all is awaited. -With "yes" or no specification at all, it ends the function with the return value 0, and with "no" it is checked whether return was passed as the second parameter. -If this is the case, the function ends with the return value 255, otherwise the entire program ends with the return value 255. +Display a question and ask the user if he wants to continue. +In xref:doIsForce[force] or xref:doIsBatch[batch] mode, it will continue automatically. + +|*Param*|*Name* |*Description*| +|`$1` |question|The question to display. Defaults to `Do you want to continue?`. +|`$2` |return |If the user does not want to continue, this function will exit immediately by default. However, if `return` is passed the function will return 255 and the called can handle the program flow. === doConfirmWarning -The doConfirmWarning function calls the doWarning function with the message passed to it, and then calls the doAskToContinue function with no parameters. +Passes all arguments to xref:doWarning[] to print as warning. +Then it calls xref:doAskToContinue[]. === doDebug -The doDebug function is called with arguments that are printed if the variable debug is set. -Backslash-escaped characters, for example "\n" for new line, are also allowed in the arguments. +Prints the given arguments as debug message with according coloring. +Debug messages will be printed in xref:doIsDebug[debug] mode. === doEcho -The doEcho function prints the arguments passed to it if the variable quiet is not set. -Backslash-escaped characters, for example "\n" for new line, are also allowed in the message. +Prints the given arguments as regular info message. +The message will be suppressed in xref:doIsQuiet[quiet] mode. === doEchoAttention -The doEchoAttention function returns the header ******** ATTENTION ******** followed by the message specified as a parameter. -Backslash-escaped characters, for example "\n" for new line, are also allowed in the message. +Like xref:doWarning[] but prefixes the message with an `ATTENTION` header. === doEchoInteraction -The doEchoInteraction function outputs the message passed as a parameter in light blue and appends a blank line, and allows backslash-escaped characters, for example "\n" for new line. +Prints the given arguments as interaction message with according coloring (in light blue). +An interaction message is an information or question the end-user should react to with interactive feedback. === doEchoOption -The doEchoOption function outputs the message passed as a parameter in light blue, and allows backslash-escaped characters, e.g. -"\n" for new line. +Prints the given arguments as option message with according coloring (in light blue). +An option message is an option the user can choose from. === doEchoStep -The doEchoStep function prints the message passed as a parameter with three asterisks before and after the message in purple, and allows backslash-escaped characters, for example "\n" for new line. +Prints the given arguments as step message with according coloring (in purple). +A step message informs about a step as part of a command or process that has been completed. === doError -The doError function prints the message passed to it in bright red. +Prints the given arguments as error message with according coloring (in bright red). +An error message informs the user that something went wrong. +The coloring should help to highlight such problems. === doFail -The doFail function is called with an error message as the first parameter and an exit code as the second parameter. -The function first calls the doEchoAttention function without parameter, followed by the specified error message and a message on how to proceed. -If a 0 is specified as the exit code, the function ends with exit code 1, otherwise with the specified exit code. -If no exit code is specified, the function terminates with exit code 255. +Prints an xref:doEchoAttention[ATTENTION] banner. +Then it prints the first argument followed by a generic text as xref:doError[error] message. +Then this function immediately exists the program with an error code. +The error code can be provided as second argument but `0` will be replaced with `1` and if omitted `255` is used. === doInfo -The doInfo function prints the message passed as a parameter in blue and appends an extra blank line, and allows backslash-escaped characters, for example "\n" for new line. +Prints the given arguments as info message with according coloring (in blue). +An information message is a more important message but not indicating any problem (like warning or error). === doLicenseAgreement -The doLicenseAgreement function checks whether the DEVON_HOME_DIR/.devon/.license.agreement file exists locally. -If the file exists, the function exits with the return value 0. -If the file does not exist, the function calls doLogo and then license information about devonfw-ide. -Then the website with the license conditions is called up or an error is output if the variable batch is set. -Now the question is asked in a loop until either "yes" or "no" is entered. -If "no" is entered, the function ends with a return value of 255. -If "yes" is entered, the license from the opened website is saved in the local file DEVON_HOME_DIR/.devon/.license.agreement stored and the function ends with return value 0. +Ensures that the end-user confirms the license agreement of `devonfw-ide` on the first usage on his machine. +If the user has already confirmed, this function will have no effect. +Otherwise it will xref:doLogo[print the logo] followed by the license information. +This contains a link that will also be opened automatically in the web-browser. +Then xref:doAskToContinue[] is used to let the user confirm the license agreement. +If the user does not confirm or runs in xref:doIsBatch[batch] mode this function will fail with an error message. +Otherwise, the user confirmation will be saved to `$DEVON_HOME_DIR/.devon/.license.agreement`. === doLogo -The doLogo function prints out the devon logo. +Prints out the devon logo with clipping if the width of the terminal is too small to prevent line-wrapping. === doQuestion -The doQuestion function outputs the message passed to it in light blue. +Passes arguments to xref:doEchoInteraction[]. === doResult -The function doResult outputs the message passed as the first parameter, depending on the second parameter as Succeeded for 0 or Failed for all other values. -If the second parameter is not specified, Failed (internal error missing exit code) is output. +Handles the result of a command. +Will print the operation (`$1`) as xref:doSuccess[success] message if exitCode (`$2`) is `0`. +Otherwise it will pass it to xref:doFail[]. + +|*Param*|*Name* |*Description*| +|`$1` |operation |The operation that failed or succeeded. +|`$2` |exitCode |`0` for sucess, otherwise the error code. === doSuccess -The doSuccess function outputs the message passed to it in green. +Prints the given arguments as success message with according coloring (in green). === doWarning -The doWarning function outputs the text "WARNING:" with the message passed in the parameter and allows backslash-escaped characters, for example "\n" for new line. +Prints the given arguments as warning message with according coloring (in orange). == Environment Checks +The functions for testing environments return `0` (true) if the operating-system matches and `1` (false) otherwise. + === doIsMacOs -The doIsMacOs function returns 0 if the operating system is detected as MacOs. -If not, a 255 is returned. +Checks if the operating system is detected as MacOs. === doIsWindows -The doIsWindows function returns 0 if the operating system is detected as Windows. -If not, a 255 is returned. +Checks if the operating system is detected as Windows. == Functions to verify requirements @@ -108,45 +128,50 @@ If not, a 255 is returned. Uses xref:doIsBatch[] to check whether the batch variable is set and, if set, issues an error message. === doRequireWsl -Checks whether WSL for Windows is installed and whether it is activated and issues a corresponding message via doFail if one of the two requirements is not met. +Checks whether Windows Subsystem for Linux (WSL) is installed and whether it is activated and issues a corresponding message via xref:doFail[] if one of the two requirements is not met. == Functions for generic command execution === doDevonCommand -The doDevonCommand function calls the doDevonCommandAndReturn function and passes it all the parameters. -If the return value of the doDevonCommandAndReturn function is not equal to 0, the script that called the doDevonCommand function is ended with the return value. +Calls xref:doDevonCommandAndReturn[] and passes all the parameters. +On success it calls xref:doUpdatePath[] to ensure the PATH is updated after an installation. +On failure it will xref:doAskToContinue[ask to continue] if not in xref:doIsBatch[batch] mode or exit immediately with the error code. === doDevonCommandAllWorkspaces -The doDevonCommandAllWorkspaces function is given a devon command as a parameter that is executed in all directories in the workspaces directory. -If other directories or the readme.txt file are found in the workspaces directory, a corresponding message is output. -If a directory change does not work, the function ends with the return value 1. +Iterates over all workspaces (sub-folders of `workspaces` folder) and executes the given commandlet in each of them. === doDevonCommandAndReturn -The doDevonCommandAndReturn function is passed a command from the devon environment with parameters as a parameter, i.e. -a command that must be installed under DEVON_IDE_HOME/scripts/command. -If no parameter is given, an error message is output using the doFail function. -If the specified command does not exist, an error message is also output using doFail. -If the command exists, it is checked whether it is executable and, if not so, set to executable. -Then the command is called with the options batch, force, debug and quiet, if set, and the specified parameters. -If the command encounters an error, an error message is output with the return value passed by the command. -Otherwise the function ends with the return value 0. +Runs the commandlet at `$DEVON_IDE_HOME/scripts/command/$1` with the further given arguments. +It will automatically pass mode options like xref:doIsBatch[batch] to the commandlet before other given arguments. +Further it xref:doError[prints an error message] if the commandlet was not successful. +It will return with the exit code of the commandlet that has been invoked. + +|*Param*|*Name* |*Description*| +|`$1` |commandlet |The devonfw-ide commandlet to call. E.g. `help` or `ide`. +|`$2`-$n|args |Any additional argument is passed to the specified commandlet. === doRunCommand -Takes 3 parameters: the command to be executed, a message to be printed and the directory in which the command is to be executed. -First, the function is checked whether the specified directory exists. -If the directory does not exist, it will take the current directory. -Then the command is executed and depending on the return value of the command, a message is output that starts with "Succeed" or "Failed". +Executes the given command (`$1`). +If a a third parameter (`$3`) is provided, it has to point to an existing directory where to command will be executed and the function will return back to the original directory afterwards. +It will use xref:doResult[] using the `message` (`$2`) to handle the result of the command execution (success or failure). + +|*Param*|*Name* |*Description*| +|`$1` |command |The command to execute including all its parameters. +|`$2` |message |Optional description of the command. Will fall back to "run command" followed by a simplification of the command (`$1`). +|`$3` |dir |Optional working directory where to execute the command. == Functions for IO operations (download, install, backup, extract, load, save) === doBackup -Takes a file or directory as the first parameter and the date after which the backup directory is named that is to be created in the /updates/backups subdirectory for the backup as the second parameter. +Takes a file or directory as the first parameter and the date after which the backup directory is named that is to be created in the `updates/backups` subdirectory for the backup as the second parameter. If the second parameter is not specified, the current date is used. If a single file is specified in the first parameter and such a file already exists in the backup directory, then a time stamp is added to the backup directory as an additional subdirectory. Then the backup directory is created and the files to be backed up are moved there. === doBrewInstall -TODO +Installs a tool using homebrew. +If homebrew is installed (`brew` command found), the desired tool will be installed using `brew install`. +Otherwise, the function will fail with an error message guiding the user to install homebrew. === doDownload Downloads an artifact from the internet.