Skip to content

Commit

Permalink
devonfw#751: improved function documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@hohwille
hohwille committed Oct 7, 2022
1 parent e7c4e33 commit bd3756d
Showing 1 changed file with 90 additions and 65 deletions.
155 changes: 90 additions & 65 deletions documentation/functions.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,148 +5,173 @@ 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

=== doRequireNotBatch
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.
Expand Down

0 comments on commit bd3756d

Please sign in to comment.