#751 Documentation of functions

documentation/functions.asciidoc

@@ -0,0 +1,202 @@
+:toc:
+toc::[]
+
+== 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 name of the flag is part of the function name.
+
+=== doIsBatch
+This function returns a 0 if the variable "batch" is set.
+
+=== doIsDebug
+This function returns a 0 if the variable "debug" is set and the -q option is not specified.
+
+=== doIsForce
+This function returns a 0 if the variable "force" is set.
+
+=== doIsQuiet
+This function returns a 0 if the variable "quiet" is set.
+
+== Functions for input and output
+
+=== 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.
+
+=== doConfirmWarning
+The doConfirmWarning function calls the doWarning function with the message passed to it, and then calls the doAskToContinue function with no parameters.
+
+=== 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.
+
+=== 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.
+
+=== 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.
+
+=== 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.
+
+=== 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.
+
+=== doError
+The doError function prints the message passed to it in bright red.
+
+=== 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.
+
+=== 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.
+
+=== 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.
+
+=== doLogo
+The doLogo function prints out the devon logo.
+
+=== doQuestion
+The doQuestion function outputs the message passed to it in light blue.
+
+=== 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.
+
+=== doSuccess
+The doSuccess function outputs the message passed to it 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.
+
+== Environment Checks
+
+=== doIsMacOs
+The doIsMacOs function returns 0 if the operating system is detected as MacOs. If not, a 255 is returned.
+
+=== doIsWindows
+The doIsWindows function returns 0 if the operating system is detected as Windows. If not, a 255 is returned.
+
+== Functions for Maven
+
+=== doArrayContainsItemWithPrefix
+to do
+
+=== doMavenArchetype
+to do
+
+=== doMavenGetLatestVersion
+to do
+
+=== doUpgradeMavenArtifact
+to do 
+
+= doBackup
+A file or directory is transferred to the doBackup function 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.
+
+= doConfigureWorkspace
+to do
+
+= doCreateIdeScript
+to do
+
+= 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.
+
+= 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.
+
+= 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.
+
+= 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.
+
+= doDownload
+to do
+
+= doDownloadInternal
+The function doDownloadInternal is given the URL as the first parameter, a temporary name for the file to be downloaded as the second, and the target directory in which the file is to be stored as the third parameter. Optionally, the name of the downloaded file can be given as a fourth parameter. If this does not happen, the name is determined from the URL. If the file exists and the force option was not specified, the function ends with a corresponding message and the return value 255. Otherwise the file is downloaded and, if successful, moved to the target directory.
+
+= doExtendPath
+A directory is passed to the doExtendPath function as a parameter. The function then checks whether the "bin" subdirectory exists in the transferred directory. If the directory exists, the PATH variable is extended by this "bin" directory. Otherwise the PATH variable is expanded with the passed directory.
+
+= doExtract
+The doExtract function is given the file to be extracted and possibly a path to where it should be extracted. Then the right tool is selected based on the file extension and the file is unzipped.
+
+= doGetExtension
+The doGetExtension function is given a file name as a parameter, including the path, and returns the file extension as the result.
+
+= doGetFirstExistingPath
+The doGetFirstExistingPath function takes a list of directories as a parameter and then checks in the specified order until one of the specified directories exists. This directory is then output and the function ends with the return value 0. If none of the passed directories exist, the function ends with the return value 1.
+
+= doGetFirstExistingPathOrFail
+The doGetFirstExistingPathOrFail function takes a list of directories as a parameter and then checks in the
+specified sequence until one of the specified directories exists. This directory is then output and the function ends with the return value 0. If none of the directories passed exist, the doFail function is called with a corresponding message.
+
+= doGetNextVersion
+A version number is passed to the function doGetNextVersion as an argument and the next version number is generated from this by incrementing the last digit by one and outputs it.
+
+= doGitPullOrClone
+The doGitPullOrClone function is given the target path and the URL or URL#branch as parameters. If the directory is a Git repository, it is tested whether remote repositories are configured and, if so, a git pull is performed. If not, a corresponding message is output and the function is ended with a return value of 1. If the directory is not a Git repository and no URL was specified, the function is aborted with a doFail message. However, if a URL was specified, the specified directory is created, changed to the directory and the repository of the specified URL is cloned into the specified directory. If the branch was also specified in the URL, a checkout is carried out on this branch.
+
+= doInstall
+The url of the software to be installed, the target directory in which the software is to be stored and the name of the software are given as parameters to the doInstall function. The function then downloads the software via doDownload into the download directory of the registered user, unpacks the software into the updates/extracted directory and then finally moves the software into the DEVON_IDE_HOME/software/"name of the software" directory.
+
+Additional parameters can also be passed to the function:
+
+* The version parameter ensures that a specific version of the software is installed.
+
+* If a "-" is passed to the function as the url, the settings from the Git repository ide-mirrors are used to download the correct software, e.g. depending on the operating system.
+
+* You can specify your own repository using the repository parameter or the DEVON_SOFTWARE_REPOSITORY variable. This ensures that the package to be installed is loaded from there.
+
+* If software is required that needs to be installed instead of just being unpacked and moved to the IDE_DEVON_HOME/software directory, you can set the directory for the installation software to DEVON_IDE_HOME/updates/install as the target directory. Following the doInstall call in the commandlet, the installation of the software can then be initiated.
+
+* If parameters five through nine (edition, code, os, arch, and ext) are specified, they are passed directly to the doDownload function.
+
+= doIsDevVersion
+The doIsDevVersion function checks whether one of the two values "dev-SNAPSHOT" or "0-SNAPSHOT" was passed to it as a parameter. If this is the case, it ends with the return value 0 otherwise 1.
+
+= doIsIgnoredFolder
+The function doIsIgnoredFolder checks whether the directory that is passed to it as a parameter corresponds to the directory target, eclipse-target, node_modules, .git, or .svn and returns the return code 0 otherwise 255.
+
+= doIsInstallerExtension
+The doIsInstallerExtension function checks whether the file extension of the file specified in the parameter is an executable file, i.e. .exe .msi .pkg or .bat. If so, the function returns 0, otherwise 255.
+
+= doIsPackageJsonContainingScript
+The function doIsPackageJsonContainingScript checks whether the module passed with the first parameter is contained in the package package.json. If so, then it ends with the return value 0 otherwise with a message and the return value 255.
+
+= doMoveGlobSafe
+The doMoveGlobSafe function moves the file specified as the second parameter after checking whether it exists to the target specified in parameter one and outputs the performed action via doEcho.
+
+= doOpen
+The doOpen function opens the URL passed to it in the browser window or calls the specified program under Windows and MacOS.
+
+= doParseOption
+The doParseOption function checks whether the parameter passed to it is one of the options -b, -f, -d or -q and accordingly sets the associated variable batch, force, debug or quiet and terminates the function with the return value 0. If -- is passed , a variable is set that prevents further calls of this function and ends with the return value 0. If none of these options are passed, the return value is 255.
+
+= doReplaceExtracted
+The doReplaceExtracted function prepares to move an unpacked archive (specified in the first parameter). The current date is defined as the name for the backup directory of the currently installed software. Then it is checked whether the target directory (specified in the second parameter) corresponds to DEVON_IDE_HOME. If it does not correspond to DEVON_IDE_HOME, the function doReplaceExtractedSkipSingleFolder is called and the parameters archive directory, target directory, backup directory and the specification that all files in the archive directory are to be processed are passed. If the target directory is DEVON_IDE_HOME, which corresponds to the complete devonfw IDE installation, then all files and directories, except the workspaces directory, are passed in a loop to the doReplaceExtractedFile function as the first parameter, the second parameter specifies the target directory with the corresponding subdirectory names and the third Parameter is the backup directory. Attention: for one installation package the function doReplaceExtractedSkipSingleFolder is called, while in the other case the function doReplaceExtractedFile is called in a loop.
+
+= doReplaceExtractedFile
+The doReplaceExtractedFile function is called with the three parameters path of the file or directory to be moved, the target directory and a backup directory. The function creates missing directories, makes a backup from the target directory to the backup directory. Then the files specified in the first parameter are moved to the target directory.
+
+= doReplaceExtractedSkipSingleFolder
+The parameters source directory, target directory, backup directory and possibly a list of files and directories via shell file name expansion (globbing) are passed to the doReplaceExtractedSkipSingleFolder function. The first three parameters are taken directly into variables and removed from the list of passed parameters with the shift so that the last specification can be viewed as a whole. If the last parameter is a single directory and, on MacOS, not a directory with a name like *.app, it is taken as the source directory. Then the function doReplaceExtractedFile is called with the saved parameters, with source directory, target directory and backup directory.
+
+= doRequireNotBatch
+The doRequireNotBatch function uses doIsBatch to check whether the batch variable is set and, if set, issues the error message "Cannot proceed in batch mode as interactive installation is required. Please rerun without batch option.".
+
+= doRequireWsl
+The function 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.
+
+= doRunCommand
+The doRunCommand function can be given 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".
+
+= doRunConfigurator
+The doRunConfigurator function transfers all jar files in the DEVON_IDE_HOME/scripts/lib directory separated by ":" as a class path to the Java command and executes the Java program specified as a parameter.
+
+= doUnzip
+The doUnzip function checks if an unzip program is installed, and if not, installs the program. The file specified in the first parameter is then unpacked into the directory specified in the second parameter.
+
+= doVersionCompare
+Two version numbers are passed to the doVersionCompare function as parameters. If the versions are equal, the function returns 0, if the first version is higher than the second, returns 1, and if the second version is higher than the first, the function returns 2.
+