-
Notifications
You must be signed in to change notification settings - Fork 1
API Reference v1
This document is the API reference for the Project Init system v1.7.5
| Code | ||
|---|---|---|
| 0 | EXIT_SUCCESS | Used when a project is successfully initialized and the program has finished without fatal errors. |
| 1 | EXIT_FAILURE | Used when the program encounters any kind of error. |
| 5 | EXIT_CANCELLED | Used when the program is terminated by an interrupt signal, e.g. when cancelling by means of Ctrl+C, or when the user does not confirm the project initialization. |
Contains the number of the currently active init level. The start (entry point) of the Project Init system, i.e. the source root of the system itself, is defined as level 0 (zero). As the user progresses through the forms, each directory in which the system descends into represents a separate init level, for which a greater level number is assigned. This variable is automatically adjusted to always equal the number of the init level the system is currently in.
Contains the absolute path to the directory of the current active init level. As the user progresses through the forms of the various init levels, this variable is automatically adjusted to always point to the init level directory the system is currently in.
The path to the directory of the project type selected by the user. This global var holds one of the two results of the select_project_type() function.
The name of the project type selected by the user. This global var holds one of the two results of the select_project_type() function.
The identifier of the question for which form input is requested. This variable can be set before calling the read_user_input_selection() , read_user_input_text() or read_user_input_yes_no() function to make the form question that follows assignable by a unique identifier. Currently, this is only used during testing. When a value is set before calling any of the aforementioned functions, it instructs those functions to read the user-provided answer from a prepared internal data structure.
Since: 1.2.0
Holds the value computed and set by the make_hyperlink() function. The string value might contain terminal escape codes.
Since: 1.1.0
Indicates whether the loaded addons resource of the running Project Init system is a development version or a release version. This global variable is either true or false.
The path to the loaded addon resource directory. This is only set if an addon is available and loaded, otherwise it remains empty. It indicates the source root of the addon within the local filesystem, which may or may not be a temporary location. This variable must be regarded as read-only.
Since: 1.4.0
Holds the version identifier of the addons resources if applicable. This is the version as specified in the VERSION file of the addons resource directory. The format of the value of this variable is 'major.minor.patch', or '?.?.?' if the VERSION file contains an invalid format. If no VERSION file is found, this variable will be empty.
Indicates whether the running version of the Project Init system is a development version or a release version. This global variable is either true or false.
The name of the file which is generated for the legal text of the selected license. A new value can be set to this variable to change the file name.
Since: 1.6.0
Indicates whether the user has requested a quickstart. Is either true or false. This variable must be regarded as read-only.
Since: 1.4.0
The message to show when a project is successfully initialized. This text is shown in the terminal and in the desktop notification. A new value can be set to this variable to change the success message.
Since: 1.1.0
Indicates the path to the project source template directory used to initialize a new project. This variable is only set after project initialization process has started and the source template files have been copied to the project target directory by means of the project_init_copy() function. This variable must be regarded as read-only.
Since: 1.4.0
Holds the version identifier of the Project Init system. The format is 'major.minor.patch'.
Holds the property value set by the get_property() and get_boolean_property() functions.
Attributes: [constant]
The status code a Quickstart function should return in the case of a failed operation. This indicates to the system that the entire operation, which might consist of multiple chained functions, should be cancelled. A warning is shown to the user about the failed operation. Use QUICKSTART_STATUS_NOWARN instead to suppress that warning.
Since: 1.4.0
Attributes: [constant]
The status code a Quickstart function should return in the case of a failed operation, suppressing some warnings emitted by the system. This status code is the same as QUICKSTART_STATUS_FAILURE but gives the underlying function the opportunity to show its own warning messages to the user before returning. Please note that the system will still emit other warnings and errors not related to the returned status of the Quickstart function.
Since: 1.4.0
Attributes: [constant]
The status code a Quickstart function should return in the case of a successful operation.
Since: 1.4.0
Holds the name of the directory representing the next init level that was selected by the user. Please note that this is not the absolute path to the selected directory, but rather only the name of the directory within the filesystem. Represents the first return value of the select_next_level_directory() function.
Holds the display name of the directory that was selected by the user. This is not the directory name on the filesystem, but rather the name as it is shown to the user within the form, i.e. as specified by the accompanying 'name.txt' file. Represents the second return value of the select_next_level_directory() function.
Can be set to true in order to suppress the printing of a deprecation warning for the next call of any deprecated function. This variable is automatically reset to false by a deprecated function once it returns. Thus, code using deprecated functions must set this variable before each call if deprecation warnings should be suppressed for all of them. Please note that the automatic reset of the variable value only applies if the underlying deprecated function is called within the same shell environment.
Since: 1.3.0
The path of the current working directory of the user when he started Project Init. This variable must be regarded as read-only.
Since: 1.4.0
Used by the read_user_input_selection() function to determine the zero-based index of the item to use by default when a user does not provide an answer in the item selection prompt.
Since: 1.7.0
Used by the read_user_input_text() function to determine the text value to use by default when a user does not provide an answer in the text prompt.
Since: 1.7.0
Contains the boolean user answer of the yes/no question from the last call to the read_user_input_yes_no() function. This variable contains either true or false.
Contains the selection index of the user choice from the last call to the read_user_input_selection() function. Please note that this index is always zero-based, even when the selection numbers shown to the user within the form selections exhibit a different behaviour.
Contains the user-entered string from the last call to the read_user_input_text() function.
Holds the value loaded and set by the load_var_from_file() function. The string value might contain arbitrary characters, including special characters. It might be empty if no corresponding var file was found.
Since: 1.3.0
Adds the specified language standard version and its corresponding label to the list of supported language versions.
This function can be called by init code to specify that a particular project does support the given language standard. The arguments represent the plain version number (e.g. "17" for C++ version 17) and the corresponding label string (e.g. "C++17") used when such versions are displayed. If the specified version number is already supported, then the function call has no effect.
Arguments:
| $1 | The version number to add. This argument is mandatory. |
| $2 | The version label to add. This argument is mandatory. |
Globals:
| SUPPORTED_LANG_VERSIONS_IDS | The array holding all supported language version numbers. |
| SUPPORTED_LANG_VERSIONS_LABELS | The array holding all supported language version labels. |
Examples:
add_lang_version "99" "C99";
add_lang_version "17" "C++17";
add_lang_version "8" "Java8";Asserts that all directories given as arguments exist.
This function is supposed to be used in test suites.
Since: 1.2.0
Arguments:
| $@ | A series of directories to check. At least one directory must be specified. |
Returns:
| 0 | If all specified directories exist. |
| 1 | If at least one of the specified directories does not exist. |
Globals:
| ASSERT_FAIL_MISSING_DIRS | Will contain all directories that have failed this assertion. Is set by this function. |
Examples:
dirs=("myDirA" "myDirB" "myDirC");
assert_dirs_exist "${dirs[@]}";Asserts that all directories given as arguments do not exist.
This function is supposed to be used in test suites.
Since: 1.2.0
Arguments:
| $@ | A series of directories to check. At least one directory must be specified. |
Returns:
| 0 | If all specified directories do not exist. |
| 1 | If at least one of the specified directories does exist. |
Globals:
| ASSERT_FAIL_ADVERSE_DIRS | Will contain all directories that have failed this assertion. Is set by this function. |
Examples:
dirs=("myDirA" "myDirB" "myDirC");
assert_dirs_not_exist "${dirs[@]}";Asserts that the first specified argument is equal to the second argument.
This function is supposed to be used in test suites. Any encountered errors may be printed on stdout.
Since: 1.2.0
Arguments:
| $1 | The expected value of the assertion. This is a mandatory argument. |
| $2 | The actual value of the assertion. This is a mandatory argument. |
| $3 | The status code to be returned by this function if the two given values are not equal. This usually comes from the status code returned by the command which produced the actual value. |
Stdout:
An error message in the case that the actual value is not equal to the expected value, dumped to stdout.
Returns:
| 0 | If the specified arguments are equal. |
| 1 | If the specified arguments are not equal. |
Examples:
expected="A";
actual="$(echo A)";
assert_equal "$expected" "$actual" $?;Asserts that all files given as arguments exist.
This function is supposed to be used in test suites.
Since: 1.2.0
Arguments:
| $@ | A series of files to check. At least one file must be specified. |
Returns:
| 0 | If all specified files exist. |
| 1 | If at least one of the specified files does not exist. |
Globals:
| ASSERT_FAIL_MISSING_FILES | Will contain all files that have failed this assertion. Is set by this function. |
Examples:
files=("fileA.txt" "fileB.txt" "fileC.json");
assert_files_exist "${files[@]}";Asserts that all files given as arguments do not exist.
This function is supposed to be used in test suites.
Since: 1.2.0
Arguments:
| $@ | A series of files to check. At least one file must be specified. |
Returns:
| 0 | If all specified files do not exist. |
| 1 | If at least one of the specified files does exist. |
Globals:
| ASSERT_FAIL_ADVERSE_FILES | Will contain all files that have failed this assertion. Is set by this function. |
Examples:
files=("fileA.txt" "fileB.txt" "fileC.json");
assert_files_not_exist "${files[@]}";Clears all set language versions and their corresponding labels from the list of supported language standards.
Globals:
| SUPPORTED_LANG_VERSIONS_IDS | The array holding all supported language version numbers. |
| SUPPORTED_LANG_VERSIONS_LABELS | The array holding all supported language version labels. |
Copies a template resource to the destination path.
This function makes the template resource specified by the first argument available to the project target at the path specified by the second argument. The source and destination arguments are handled differently depending on the underlying application mode.
In the regular (form-based) application mode, if the source argument is relative, it is interpreted as being relative to the used project template source directory, i.e. the 'source' directory of the concrete project type selected by the user. The destination argument is interpreted as being relative to the project target directory. The underlying target project directory must already be created before calling this function. If the file in the project target directory does already exist, it will be replaced by the specified template resource.
In Quickstart mode, if the source argument is relative, it is interpreted as being relative to the source root of the addon and base resources. If an addon resource exists at the path of the source argument, it takes precedence over any existing base resource. The destination argument is interpreted as being relative to the underlying current working directory. If the file at the specified destination already exists, it is not overwritten and this function will cause the application to cancel the entire Quickstart operation.
An absolute source path is used as is. The destination path must never be absolute. Regardless of the underlying application mode, if the source path denotes a directory instead of a regular file, the directory is copied as is including the entire content and all previously mentioned conditions and behaviours still hold.
Since: 1.4.0
Arguments:
| $1 | The path to the resource to copy. Either an absolute or relative path. |
| $2 | The destination path to copy the resource to. The path must not be absolute. |
Returns:
| 0 | If the resource was successfully copied. |
| 1 | If the resource could not be found. |
| 2 | If the source resource exists but could not be copied. |
Examples:
copy_resource "copy/this/res" "to/this/path/in/my/project";Loads a shared template resource and copies it to the destination path.
This function searches for a shared source template resource specified by the first argument, loads it if it exists and copies it to the location in the project target directory specified by the second argument. The underlying target project directory must already be created before calling this function.
Addons resources are considered and can potentially override any shared template from the base resources. If the file in the project target directory, specified by the second argument, does already exist, it will be replaced by the specified shared template resource.
Since: 1.3.0
Arguments:
| $1 | The name of the shared resource to load and copy. This is the path of the file, relative to the 'share' directory. The path must not be absolute. |
| $2 | The destination file to copy the shared resource to. Must be a path to a file in the project target directory. The path must not be absolute. |
Returns:
| 0 | If the shared resource was successfully copied. |
| 1 | If the shared resource could not be found. |
| 2 | If the shared resource exists but could not be copied. |
Examples:
copy_shared "copy/this/shared/res" "to/this/path/in/my/project";Expands one or more namespace template directories to have the specified directory layout.
In many project source tree structures the concept of a namespace where various source code is placed in is represented by a directory layout that resembles that namespace. One namespace level/component is represented by a separate subdirectory within the source tree. This function can be used to automatically expand a placeholder directory in a project source template structure to match a given namespace layout. All files and subdirectories located within the template's namespace placeholder directory are moved to the expanded subdirectory of the lowermost namespace component.
The underlying target project directory must already be created before calling this function. At least two arguments must be specified. The first argument denotes the namespace layout to expand the target directories to. Namespace components are separated by slashes ('/'). All subsequent arguments denote the directories in the project template source tree that should be expanded to represent the given namespace. Multiple such directories can be specified in one function call at once for improved efficiency, but at least one must be specified. Each specified directory path must be relative to the root of the project source template directory. Arguments must never denote absolute paths.
The file cache holding the data about all present files in the project directory to be initialized is automatically updated by this function. This function may not be used in Quickstart mode.
Since: 1.5.0
Arguments:
| $1 | The namespace to use when expanding the specified template directories. Individual namespace levels are separated by '/' characters, however, a namespace must not start or end with a slash. This is a mandatory argument. |
| $@ | The namespace template directories to expand, relative to the project template source root directory. This is a mandatory argument. At least one directory must be provided by the caller. Any namespace template directory which does not exist in the template source is silently ignored. |
Examples:
# The following example expands 'ns_template_dir' in the source tree
# (as a subdirectory of 'src/main') to represent
# the 'raven/sample/stuff' namespace.
expand_namespace_directories "raven/sample/stuff" "src/main/ns_template_dir";
# Now the project template directory structure is:
# 'src/main/raven/sample/stuff'Prints a statement indicating a failed operation.
This function shows a failure message and prints all given error messages. The program will be terminated by this function with exit code indicated by the global variable $EXIT_FAILURE.
Arguments:
| $@ | Optional strings indicating all error messages. Each message is printed on its own line. |
Stdout:
Error information.
Finds all files to be processed by the project initialization operation.
This function searches for files eligible for variable substitution. The search is conducted in the project target directory and is done recursively. The paths to the found files are then cached for internal usage.
This function should be called every time the files in the project target directory are changed, i.e. files are added, moved, or deleted manually without the usage of the copy_resource() or copy_shared() functions. Changes of the file contents are irrelevant. Calling this function ensures that the internally used file cache is up-to-date after the project structure has changed. In Quickstart mode this function is not applicable as files should only be copied by the respective API functions.
Prompts the user to enter the name of the produced binary file name (without possible platform-dependent file extension).
The provided answer can be queried in source template files via the VAR_ARTIFACT_BINARY_NAME substitution variable. The associated shell global variable is set by this function.
Globals:
| FORM_QUESTION_ID | c.binary.name |
| var_artifact_binary_name | The name of the binary artifact. Is set by this function. |
| var_artifact_binary_name_upper | The name of the binary artifact in all upper-case. Is set by this function. |
Prompts the user to enter the C version to use for the project.
The provided answer can be queried in source template files via the VAR_C_VERSION_LABEL and VAR_C_VERSION substitution variables. The associated shell global variables are set by this function.
Globals:
| FORM_QUESTION_ID | c.version |
| var_c_version | The C version string. Is set by this function. |
| var_c_version_label | The C version label string. Is set by this function. |
Prompts the user to enter the name of the produced binary file name (without possible platform-dependent file extension).
The provided answer can be queried in source template files via the VAR_ARTIFACT_BINARY_NAME substitution variable. The associated shell global variable is set by this function.
Globals:
| FORM_QUESTION_ID | cpp.binary.name |
| var_artifact_binary_name | The name of the binary artifact. Is set by this function. |
| var_artifact_binary_name_upper | The name of the binary artifact in all upper-case. Is set by this function. |
Prompts the user to enter the namespace that is used by the project code.
The provided answer can be queried in source template files via the VAR_NAMESPACE substitution variable. The namespace value will be in dot notation. Additionally, there are more substitution variables defined as a result of using a namespace. For example, header include guards and the C++ source code namespace declaration have their own substitution variable. Those can be used to further involve an application namespace into the project's source files. The associated shell global variables are set by this function.
Globals:
| FORM_QUESTION_ID | cpp.namespace |
| var_namespace | The entire namespace in dot notation. Is set by this function. |
| var_namespace_0 | The first package name of the namespace. Is set by this function. |
| var_namespace_path | The entire namespace in path notation (with slashes). Is set by this function. |
| var_namespace_colon | The entire namespace in colon notation (with colons). Is set by this function. |
| var_namespace_header_guard | The namespace embedded in a header guard string. Is set by this function. |
| var_namespace_decl_begin | The namespace declaration start part as used in code. Is set by this function. |
| var_namespace_decl_end | The namespace declaration end part as used in code. Is set by this function. |
Prompts the user to enter the C++ version to use for the project.
The provided answer can be queried in source template files via the VAR_CPP_VERSION_LABEL and VAR_CPP_VERSION substitution variables. The associated shell global variables are set by this function.
Globals:
| FORM_QUESTION_ID | cpp.version |
| var_cpp_version | The C++ version string. Is set by this function. |
| var_cpp_version_label | The C++ version label string. Is set by this function. |
Prompts the user to enter whether he wants Docker integration.
Enabling Docker integration for a project means that a user can build and test the project inside a virtualized environment of a Docker container. This makes it easier, for example, to build a project from source because a user does not have to worry about the underlying toolchain. Integration with Docker is always optional.
This function will set the var_project_integration_docker_enabled global variable to either "1" or "0", depending on the user's choice. You may then handle this information in one of your custom process_files_lvl_*() functions.
The project source files responsible for the Docker integration should reside in a '.docker' directory inside the project source root. If the user chooses to disable Docker integration for a project, then that directory is automatically removed from the project during initialization.
Globals:
| FORM_QUESTION_ID | project.integration.docker |
| var_project_integration_docker_enabled | Indicates whether the user wants to enable Docker integration for the project or not. Is set to the string "1" if Docker integration should be enabled, otherwise it is set to "0". Is set by this function. |
Prompts the user to enter the namespace that is used by the project code.
The provided answer can be queried in source template files via the VAR_NAMESPACE_DECLARATION substitution variable. The namespace value will be in dot notation. The associated shell global variable is set by this function.
Globals:
| FORM_QUESTION_ID | java.namespace |
| var_namespace | The entire namespace in dot notation. Is set by this function. |
| var_namespace_trailing_sep | The namespace in dot notation, with a trailing dot at the end as the last character. Is set by this function. |
| var_namespace_path | The entire namespace in path notation (with slashes). Is set by this function. |
Prompts the user to enter the Java version to use for the project.
The provided answer can be queried in source template files via the VAR_JAVA_VERSION and VAR_JAVA_VERSION_LABEL substitution variables. Additionally, since the version identifier might differ when used inside a Maven POM, the VAR_JAVA_VERSION_POM substitution variable is also set. It should be used instead when setting the used Java version inside a POM. The associated shell global variables are set by this function.
Globals:
| FORM_QUESTION_ID | java.version |
| var_java_version | The Java version string. Is set by this function. |
| var_java_version_label | The Java version label string. Is set by this function. |
| var_java_version_pom | The Java version string as used in a project's POM. Is set by this function. |
Prompts the user to enter the Node.js version to use for the project.
The provided answer can be queried in source template files via the VAR_NODEJS_VERSION and VAR_NODEJS_VERSION_LABEL substitution variables. The associated shell global variables are set by this function.
Globals:
| FORM_QUESTION_ID | js.nodejs.version |
| var_nodejs_version | The Node.js version string. Is set by this function. |
| var_nodejs_version_label | The Node.js version label string. Is set by this function. |
Prompts the user to enter the name of the main package, potentially including any namespace packages, that is used by the project.
The provided answer can be queried in source template files via the VAR_NAMESPACE_DECLARATION substitution variable. The namespace value will be in dot notation. Additionally, there are more substitution variables defined for specific aspects of package declarations. For example, the first package name in a series of namespace package declarations (dot notation) can be accessed by the VAR_NAMESPACE_DECLARATION_0 substitution variable. The associated shell global variables are set by this function.
Globals:
| FORM_QUESTION_ID | python.package.name |
| var_namespace | The entire namespace in dot notation. Is set by this function. This is equivalent to the package name if no namespace package was defined. |
| var_namespace_0 | The first namespace package. Is set by this function. This is equivalent to the package name if no namespace package was defined. |
| var_namespace_path | The entire namespace in path notation (with slashes). Is set by this function. This is equivalent to the package name if no namespace package was defined. |
| var_package | The main package name of the project. Is set by this function. This is always the last package name, regardless how many namespace packages were defined. |
Prompts the user to enter whether he wants to deploy the project to PyPI.
Globals:
| FORM_QUESTION_ID | python.pypi.deployment |
| var_use_deploy | A boolean flag indicating whether to deploy project artifacts to PyPI. Is set by this function. |
Prompts the user to enter whether he wants to use a linter during the project development.
Globals:
| FORM_QUESTION_ID | python.use.linter |
| var_use_linter | A boolean flag indicating whether to use a linter. Is set by this function. |
Prompts the user to enter the Python version to use for the project.
The provided answer can be queried in source template files via the VAR_PYTHON_VERSION substitution variable. The associated shell global variable is set by this function.
Globals:
| FORM_QUESTION_ID | python.version |
| var_python_version | The Python version string. Is set by this function. |
Prompts the user to enter the name of the virtual environment to be used by the project.
The provided answer can be queried in source template files via the VAR_PROJECT_VIRTENV_NAME substitution variable. The associated shell global variable is set by this function.
Globals:
| FORM_QUESTION_ID | python.virtenv.name |
| var_project_virtenv_name | The name of the virtual environment. Is set by this function. |
Prompts the user to enter the R version to use for the project.
The provided answer can be queried in source template files via the VAR_R_VERSION and VAR_R_VERSION_LABEL substitution variables. The associated shell global variables are set by this function.
Globals:
| FORM_QUESTION_ID | r.version |
| var_r_version | The R version string. Is set by this function. |
| var_r_version_label | The R version label string. Is set by this function. |
Gets the boolean property value for the specified key.
This function queries the boolean value with the specified key in the global property store and writes the result to the PROPERTY_VALUE global variable. It can be used instead of get_property() if the queried property is known to represent a boolean. If a malformed value is encountered, then a warning is logged. This function guarantees that after it returns the PROPERTY_VALUE global variable is set to either 'true' or 'false'.
The default boolean value to use is an optional argument. If it is not specified and the given key does not exist, or the specified default value does not represent a valid boolean, then PROPERTY_VALUE is set to the string 'false'.
Arguments:
| $1 | The key of the boolean property to get. Must be specified. |
| $2 | The default boolean value to use when the specified key does not exist. This argument is optional. |
Returns:
| 0 | If the specified key was found in the available properties. |
| 1 | If the specified key was not found in the available properties. |
Globals:
| PROPERTY_VALUE | Will hold the boolean property value for the specified key once this function returns. Holds either the specified default value or the string "false" if no property with such key exists. |
Examples:
get_boolean_property "my.prop.key";
echo "The boolean value of 'my.prop.key' is '$PROPERTY_VALUE'";
get_boolean_property "my.prop.key" "true";
echo "The (default) boolean value of 'my.prop.key' is '$PROPERTY_VALUE'";Gets the property value for the specified key.
This function queries the value with the specified key in the global property store and writes the result to the PROPERTY_VALUE global variable. The default value to use is an optional argument. If it is not specified and the given key does not exist, then PROPERTY_VALUE is set to an empty string.
Arguments:
| $1 | The key of the property to get. Must be specified. |
| $2 | The default value to use when the specified key does not exist. This argument is optional. |
Returns:
| 0 | If the specified key was found in the available properties. |
| 1 | If the specified key was not found in the available properties. |
Globals:
| PROPERTY_VALUE | Will hold the property value for the specified key once this function returns. Holds either the specified default value or an empty string if no property with such key exists. |
Examples:
get_property "my.prop.key";
echo "The value of 'my.prop.key' is '$PROPERTY_VALUE'";
get_property "my.prop.key" "My Default Value";
echo "The (default) value of 'my.prop.key' is '$PROPERTY_VALUE'";Loads the variable value with the specified key from the corresponding var file.
The argument represents the variable key for which a var file might exist in the current init level directory.
This function only loads the variable value from its corresponding file. It does not assign that (global) variable the loaded value. The assignment has to be done manually if necessary.
The loaded variable value is dumped to stdout. If no variable file can be found in the currently active init level directory, then the upper init levels are searched in reversed order, until the root init level is reached. If the root init level was reached and no suitable file can be found, then an empty string is dumped to stdout by this function.
Deprecated: Since 1.3.0 this function is deprecated. Use load_var_from_file() instead.
Arguments:
| $1 | The key of the substitution variable to load. |
Stdout:
The string value of the variable with the specified key, or an empty string if the corresponding var file does not exist.
Globals:
| CURRENT_LVL_PATH | The absolute path to the currently active init level directory. |
Examples:
var_my_key="$(load_var MY_KEY)";Loads the variable value with the specified key from the corresponding substitution variable file.
The argument to this function represents the key of the substitution variable for which a var file should be loaded. The key can be specified in the complete format, i.e. with a 'VAR_'-prefix, or without that prefix. The variable key argument is case insensitive.
The loaded variable value is assigned to the VAR_FILE_VALUE global variable. Usually, this is then subsequently used to assign the actual global substitution variable (see example below).
Variable files located in init levels always take precedence over equivalent variable files in shared var directories. Generally, the content of the first found applicable variable file is used. The search order depends on the currently active init level when this function is called. If no variable file can be found in the currently active init level directory, then the upper init levels are searched in reversed order, until the root init level is reached. Please note that all variable files within init levels must be placed in 'var' subdirectories of the underlying init level directories. If the root init level is reached and no suitable file can be found, then shared variable directories are searched. If still no applicable variable file is found, then the VAR_FILE_VALUE global variable is set to an empty string.
Shared variable files may be overridden by addons resources.
Since: 1.3.0
Arguments:
| $1 | The key of the substitution variable for which the value from a var file should be loaded. This is a mandatory argument. |
Returns:
| 0 | If a substitution variable value file was found. |
| 1 | If no substitution variable file was found. |
Globals:
| VAR_FILE_VALUE | Holds the string value of the found substitution variable file. Might be empty if no var file was found. Is set by this function. |
| CURRENT_LVL_PATH | The absolute path to the currently active init level directory. |
Examples:
load_var_from_file "MY_KEY";
var_my_key="$VAR_FILE_VALUE";Prints an ERROR level statement on stdout.
All given error strings are logged on one line.
Arguments:
| $* | An arbitrary number of string messages to log |
Stdout:
An ERROR level statement.
Prints an INFO level statement on stdout.
All given info strings are logged on one line.
Arguments:
| $* | An arbitrary number of string messages to log |
Stdout:
An INFO level statement.
Prints a WARNING level statement on stdout.
All given warning strings are logged on one line.
Arguments:
| $* | An arbitrary number of string messages to log |
Stdout:
A WARNING level statement.
Creates a hyperlink from the specified URL.
This function can be used to create a clickable hyperlink leading to a web resource. The hyperlink might be embedded in a series of terminal escape codes if this is an activated feature, in which case the specified label is used as the display string for the created hyperlink. If the corresponding feature is disabled, the provided URL might be used as is in the computed value. Please note that this function does not check whether the underlying terminal emulator in use supports displaying clickable labeled hyperlinks. The result of this function is not printed directly but instead stored in the HYPERLINK_VALUE global variable.
Since: 1.1.0
Arguments:
| $1 | The URL of the hyperlink. This is a mandatory argument. |
| $2 | The label of the hyperlink. This argument is optional. |
Returns:
| 0 | If the hypelink was successfully created. |
| 1 | If an error occurred. |
Globals:
| HYPERLINK_VALUE | Holds the string value of the created hyperlink. Is set by this function. |
Examples:
make_hyperlink "http://www.example.com" "Example Link";
logI "Please see this $HYPERLINK_VALUE";Proceeds to the next applicable init level and sources its init.sh script.
This function should be called when the next init level is ready to be loaded. The directory name for the next init level, relative to the currently active init level directory, should be passed as an argument to this function. If that argument is omitted, the first directory containing an init.sh script will be automatically used as the next init level. If no such directory can be found inside the currently active init level directory, then this function will terminate the program by means of the failure() function.
The global variables CURRENT_LVL_PATH, CURRENT_LVL_NUMBER are changed accordingly to reflect the changed init level. Additionally, for each immersion into the next init level, a supplementary global variable $SCRIPT_LVL_*_BASE is declared by this function to point to the corresponding init level directory, where the '*' corresponds to the init level number.
Arguments:
| $1 | The directory containing the init.sh script for the next init level. This argument is optional although it should always be specified. |
Globals:
| CURRENT_LVL_PATH | The absolute path to the currently active init level directory. Will be set to the next init level. |
| CURRENT_LVL_NUMBER | The number of the current active init level. Will be incremented by one to reflect the changed init level. |
| SCRIPT_LVL_*_BASE | Will be set to the next init level directory path, according to the corresponding init level number (*). |
Examples:
proceed_next_level "my_level_dir";Copies all project source template files to the project target directory.
This function copies all files in the Project Init source directory to the Project Init target directory indicated by the $var_project_dir variable. The project template source directory must exist and not be empty.
The file cache for the project target files, which is represented by the $CACHE_ALL_FILES global variable, is populated with the paths to the copied files in the target directory as a result of this operation.
The path to the project source template files can be optionally specified as an argument to this function.
Arguments:
| $1 | The absolute path to the project source template directory. This argument is optional. If not specified directly, then the directory is assumed to be "$CURRENT_LVL_PATH/source", i.e. the "source" directory in the lowermost init level |
Globals:
| var_project_dir | The path to the project directory to which the files will be copied (target). |
| var_project_name | The name of the project to initialize. |
| CACHE_ALL_FILES | The variable in which the paths to all copied files are saved. |
| CURRENT_LVL_PATH | The path to the current init level dir. Used when no path arg is specified |
Processes the copyright information for created project files.
This function can only be used in Quickstart mode. Based on the given license name, this function will process and replace the copyright-related substitution variables in all files generated by the Quickstart process up to this point. Only files with an appropriate file extension in their name are considered for processing. The special license name argument 'None' will cause all copyright header substitution variables to be removed.
Since: 1.6.0
Arguments:
| $1 | The canonical name of the license for which to handle copyright headers. May be specified as 'None' to remove copyright headers. |
Returns:
| 0 | In the case of success. |
| nz | In the case of any failures. |
Examples:
project_init_copyright_headers "Apache License 2.0";Finish function for the Project Init system.
Performs lifecycle checks, shows warnings and success messages and handles the shutdown state of the Project Init system. This function does not exit the underlying process in the case of a successful operation, in which case it returns with $EXIT_SUCCESS. However, in the case of an encountered error, this function might exit the process by means of the failure() function.
WARNING:
This API function should NOT be called by an addon. An addon is part of an already initialized lifecycle. This API function is only intended to be used for providers of specialised Project Init implementations, e.g. providers with a specialised main form implementation. Normal users and organisations wishing to adapt and extend the default Project Init implementation should do so by using the addon mechanism. Normally, there is no need for an external consumer of Project Init to provide his own lifecycle or main form implementation. Only use this function if you know what you are doing.
Returns:
| 0 | In the case of a successful finish procedure. |
Processes the license and copyright information for the project to be initialized.
This function copies to the project target directory all relevant files with regard to legal information, such as license text files. Furthermore, it is also responsible for setting up copyright boilerplate text in code source files. As part of this process, the corresponding variables are replaced by the correct values.
The file extensions of all project source code files for which copyright information should be set must be specified as arguments to this function. Otherwise copyright substitution variables are not replaced by their corresponding boilerplate text.
Arguments:
| $@ | A series of file extensions representing the project source files in which license and copyright information should be processed. |
Globals:
| var_project_dir | The path to the project directory to which the files will be copied (target). |
| var_project_license | The name of the license applied to the target project. |
| var_project_license_dir | The absolute path to the license template source directory where all license and copyright information is stored for the concrete license type. |
Examples:
project_init_license "java" "xml" "js";Processes the project source template files copied to the project target directory.
This function replaces some generally applicable substitution variables and then proceeds to call the process_files_lvl_*() functions in their corresponding init level order.
Globals:
| var_project_* | Various global variables holding general project information. |
| CURRENT_LVL_NUMBER | The number of the current active init level. |
Primary processing function for the quickstart mode.
This function handles the execution of one or more requested Quickstart functions. This is the default implementation for handling Quickstarts. In the case of an encountered error, this function might exit the process by means of the failure() function. All return values from called Quickstart functions are handled by this function.
WARNING:
This API function should NOT be called by an addon. An addon is part of an already initialized lifecycle. This API function is only intended to be used for providers of specialised Project Init implementations, e.g. providers with a specialised main form implementation. Normal users and organisations wishing to adapt and extend the default Project Init implementation should do so by using the addon mechanism. Normally, there is no need for an external consumer of Project Init to provide his own lifecycle or main form implementation. Only use this function if you know what you are doing.
Startup function for the Project Init system.
Initializes the state of the Project Init system, processes the given arguments, loads configurations and potentially addons resources. This function either brings the system to a state in which a regular form-based init process or Quickstart function can be run, or it exits the process by means of the failure() function. The general contract of the Project Init lifecycle applies. When this function returns normally, the startup procedure has succeeded and the caller can proceed with the desired action. The global variable PROJECT_INIT_QUICKSTART_REQUESTED will indicate whether the init system is running in Quickstart mode or regular form-based mode, however, the caller is in principle free to ignore the request as he sees fit. The provided implementation for processing Quickstart requests can be launched by calling the project_init_process_quickstart() function. When running in regular form-based mode, it is the responsibility of the caller to provide a suitable implementation of the main form and launch it after this function returns. Once the Project Init system is initialized, a caller must ensure he calls the project_init_finish() function as the shutdown procedure. Anything which needs to be handled in between the startup and shutdown procedure is implementation-specific.
WARNING:
This API function should NOT be called by an addon. An addon is part of an already initialized lifecycle. This API function is only intended to be used for providers of specialised Project Init implementations, e.g. providers with a specialised main form implementation. Normal users and organisations wishing to adapt and extend the default Project Init implementation should do so by using the addon mechanism. Normally, there is no need for an external consumer of Project Init to provide his own lifecycle or main form implementation. Only use this function if you know what you are doing.
Arguments:
| $@ | The arguments to Project Init. |
Globals:
| PROJECT_INIT_QUICKSTART_REQUESTED | A boolean value indicating whether the given arguments resulted in a request to run a Quickstart function. Is either true or false. Is set by this function. |
Shows the specified strings as numbered selection items and lets the user select one of them.
This function can be used to present a pick list to the user and get the index of the selected item. The chosen index will be saved in the USER_INPUT_ENTERED_INDEX global variable. The saved index is zero-based and represents a numeric type.
The entered input of the user is checked for validity. In the case of an invalid input, such as an out of range selection number, this function will let the user reenter his answer until he provides a valid input or otherwise cancels the program.
A special case for the selection item is the occurrence of the "None" string. If the last specified item equals "None", then if the user chooses that item the USER_INPUT_ENTERED_INDEX variable will be set to an empty string.
Since 1.7.0 a caller can use the USER_INPUT_DEFAULT_INDEX variable to specify a default item for the case in which the user does not enter anything when prompted and simply hits enter.
Arguments:
| $@ | A series of selection items. |
Stdout:
A selection list is printed.
Returns:
| 0 | In the case of a valid item selection made by the user. |
| 1 | In the case of a default item selection due to the user having hit enter. |
Globals:
| USER_INPUT_ENTERED_INDEX | Will be set by this function to contain the zero-based index of the item selected by the user, or the default index if specified. |
| USER_INPUT_DEFAULT_INDEX | Can be set by the caller to contain the zero-based index of the item which should be selected by default if the user does not enter anything when prompted. |
Examples:
my_list=("Item A" "Item B" "Item C");
logI "Choose an item out of the list:";
USER_INPUT_DEFAULT_INDEX=1; # Default to "Item B"
read_user_input_selection "${my_list[@]}";
index=$USER_INPUT_ENTERED_INDEX;
logI "Selected Item: ${my_list[index]}";Shows a prompt to the user and lets him enter arbitrary text.
This function can be used to get text input from the user. The entered text will be saved in the USER_INPUT_ENTERED_TEXT global variable. The saved text can be potentially empty if the user simply presses enter without actually entering any text.
If this function is called with no arguments, then the entered input of the user is not checked for any kind of validity or pattern. If the acceptable text should be constrained further, then this can be done by specifying an input validation function as the first argument. Such a validation function, if provided, will be called by this function after the user has submitted his answer. The user input is provided to the validation function as the first argument. The validation function should then validate the user input according to the underlying use case and return either 0 (zero) if the input is deemed valid, or non-zero if the input is deemed invalid. In the case of an invalid input, the user is prompted again to provide a new input. This process repeats until a valid input is provided by the user or the program is terminated or cancelled. It is recommended that a validation function logs some information in the case of a detected invalid input such that a user is informed about the cause of the invalidity.
Since 1.7.0 a caller can use the USER_INPUT_DEFAULT_TEXT variable to specify a default value for the case in which the user does not enter anything when prompted and simply hits enter. When the default value applies, a validation function is not used and the USER_INPUT_ENTERED_TEXT variable is assigned the default value as is.
Arguments:
| $1 | The input validation function to use. This is an optional argument. |
Returns:
| 0 | In the case of a valid text input. |
| 1 | In the case of a default text value due to non-provided input by the user. |
Globals:
| USER_INPUT_ENTERED_TEXT | Will be set by this function to contain the text entered by the user, or the default value if specified. |
| USER_INPUT_DEFAULT_TEXT | Can be set by the caller to contain the text value which should be assigned by default if the user does not enter anything when prompted. |
Examples:
function _my_validation_name() {
local input="$1";
if [[ "$input" != "Hans" && "$input" != "Franz" ]]; then
logI "Only 'Hans' and 'Franz' are allowed names";
return 1;
fi
return 0;
}
logI "What's your name?";
USER_INPUT_DEFAULT_TEXT="Hans";
read_user_input_text;
name="$USER_INPUT_ENTERED_TEXT";
logI "Hi ${name}! Nice to meet you.";
logI "What's the name of the other person?";
read_user_input_text _my_validation_name;
other_name="$USER_INPUT_ENTERED_TEXT";
logI "So, the other person's name is ${other_name}.";Shows a prompt to the user and lets him answer a yes/no question.
This function can be used to get a boolean input from the user. The entered text will be processed as a boolean and then saved in the USER_INPUT_ENTERED_BOOL global variable. The saved value will represent the type bool.
The entered input of the user is checked for validity, i.e. whether the entered text represents or can be converted to a valid boolean. If the entered input is invalid, then this function will let the user reenter his answer until he provides a valid input or otherwise cancels the program.
Supported text values for the boolean value of true: "true", "yes", "y", "1"
Supported text values for the boolean value of false: "false", "no", "n", "0"
All accepted text input is case insensitive.
For the case where the user does not enter anything and simply presses enter, a default answer can be specified as the first argument to this function.
Arguments:
| $1 | The default value to use if the user does not enter anything. Must respresent a valid answer. This argument is optional. |
Returns:
| 0 | In the case of a valid text input. |
Globals:
| USER_INPUT_ENTERED_BOOL | Will be set by this function to contain the boolean value corresponding to the entered text by the user. |
Examples:
logI "Do you like cheese? (Y/n)";
read_user_input_yes_no true;
answer=$USER_INPUT_ENTERED_BOOL;
if [[ $answer == true ]]; then
logI "You said that you like cheese.";
else
logI "You said that you do not like cheese.";
fiRemoves the specified language standard from the list of supported language versions.
This function can be called by init code to specify that a particular project does not support the given language standard. The argument represents the plain version number, e.g. "17" for C++ version 17. If the specified version number is not currently supported anyway, then the function call has no effect.
Arguments:
| $1 | The version number to remove. This argument is mandatory. |
Globals:
| SUPPORTED_LANG_VERSIONS_IDS | The array holding all supported language version numbers. |
| SUPPORTED_LANG_VERSIONS_LABELS | The array holding all supported language version labels. |
Examples:
remove_lang_version "17";Replaces all occurrences of the specified variable with the specified value.
This function will go through every file listed in the $CACHE_ALL_FILES global variable, find all occurrences of the substitution variable and replace them with the specified value. The variable key can be specified in its full canonical form or in an abbreviated form without the "VAR_"-prefix.
The variable value can be any arbitrary string, including an empty string. Using an empty string will effectively remove the variable from the file (replacing it with nothing). If the variable key corresponds to the only characters on the respective line, then that entire line is removed from the underlying file.
If only the variable key is specified, then this function will try to load the variable value from the corresponding var file by means of the load_var_from_file() function. If such a file does not exist, then the variable value is set to the empty string, thus potentially removing the entire line containing the variable from the underlying source file. Therefore, if a variable should be explicitly replaced by an empty string, regardless of any var file, then the value argument ($2) must be specified as an empty string.
Besides the key and value, a third argument can be passed to this function. That argument represents the file ending by which all present files in the $CACHE_ALL_FILES global variable will be filtered by. That way, it is possible to replace the same variable with different values in different files. Only one file ending can be specified in each function call. A full file name (e.g. Readme.txt) may also be used as such an argument.
Arguments:
| $1 | The name of the variable to replace. The "VAR_" prefix is optional and can be omitted. This argument is mandatory. |
| $2 | The value that the variable will be replaced by. Can be an empty string. This argument is optional. |
| $3 | The file extension or file name to match files against. Only files which are matched are processed by this function. This argument is optional. |
Globals:
| CACHE_ALL_FILES | The entries of all files that will be processed by this function. |
Examples:
replace_var "MY_KEY";
replace_var "MY_KEY" "";
replace_var "MY_KEY" "This will be the var value";
replace_var "VAR_TEST" "value only in .java files" "java";Prompts the user to select the next init directory.
This function searches for subordinate init level directories under the currently active init level directory and lets the user select the next init level directory into which to descend. The path to the currently active init level is taken from the CURRENT_LVL_PATH global variable. At least one subordinate init level directory must exist at the time this function is called, otherwise the program is terminated by means of the failure() function.
The found init level directories are presented to the user by a call to the read_user_input_selection() function. The result of that operation is handled by this function, which sets the global variables SELECTED_NEXT_LEVEL_DIR and SELECTED_NEXT_LEVEL_DIR_NAME to indicate the user selection. Please note that this function does not show any questions to the user. It only displays the selection of init level directories. Any appropriate questions must be handled by the caller prior to calling this function. The result of this function can then be used, for example, as an argument to the proceed_next_level() function to perform the actual descent into the next init level.
Globals:
| SELECTED_NEXT_LEVEL_DIR | The name of the directory of the init level selected by the user. This is the name of the directory in the filesystem. Is set by this function. |
| SELECTED_NEXT_LEVEL_DIR_NAME | The display name of the directory of the init level selected by the user. This is the name as defined by the 'name.txt' file of the selected init directory. Is set by this function. |
| CURRENT_LVL_PATH | The path to the active init level directory are the time this function is called. Is used to search for subordinate init level directories under this path. |
Examples:
logI "Select the next init level directory:";
select_next_level_directory;
selected_dir="$SELECTED_NEXT_LEVEL_DIR";
selected_dir_name="$SELECTED_NEXT_LEVEL_DIR_NAME";
logI "You have selected '$selected_dir_name' which is directory '$selected_dir'";
proceed_next_level "$selected_dir";Shows the form question for the project type selection.
This function lets the user select one out of the available project types for the previously chosen programming language and sets the FORM_PROJECT_TYPE_NAME and FORM_PROJECT_TYPE_DIR global variables to reflect the user choice.
Arguments:
| $1 | The ID of the project language to be used. This arg represents the name of the language subdirectory where the project type subdirectories are located. |
| $2 | The human readable name of the language to be used. |
Returns:
| 0 | In the case of a valid project type selection. |
| 1 | If this function is called while in Quickstart mode. |
Globals:
| FORM_PROJECT_TYPE_NAME | The name selected out of the project type list displayed to the user. |
| FORM_PROJECT_TYPE_DIR | The path to the directory of the selected project type. |
| FORM_QUESTION_ID | project.type |
Examples:
select_project_type "js" "JavaScript";
selected_name="$FORM_PROJECT_TYPE_NAME";
selected_dir="$FORM_PROJECT_TYPE_DIR";Executes a functionality test run for the specified Quickstart function.
The first mandatory argument to this function is the argument which would be passed to the main program if the specified Quickstart function should be used. This also includes the Quickstart-specific '@'-prefix. The second argument is optional and denotes the file for the test parameters to use during the test run. Since Quickstart functions do not necessarily prompt for user input, this is optional. However, if the underlying Quickstart function makes use of any of the read_user_input_*() API functions, then test parameters must be specified to provide the corresponding inputs during the test run. If the test parameter file is specified, it must contain valid test run parameters. The file must be properties-formatted and each test parameter corresponds to one property line.
This function is supposed to be used in test suites. It is only defined while in test mode.
Since: 1.4.0
Arguments:
| $1 | The Quickstart name to test. This has to be specified like the argument given to the main program when using the Quickstart function. This is a mandatory argument. |
| $2 | A file containing the test run parameters. It is presumed that the file is located relative to the 'tests/resources' directory. This is an optional argument. |
Returns:
| 0 | If the test run has finished successfully, without any errors or warnings. |
| nz | In the case of a test failure due to any reason. |
Examples:
# Inside the test case file 'tests/test_func_quickstart_example.sh'
function test_functionality() {
# Run and test the Quickstart function 'quickstart_example_fn()'
test_functionality_quickstart @example_fn;
return $?;
# Or:
# Run and test the Quickstart function with the given parameters
# in the 'tests/resources/test_quickstart.properties' file
test_functionality_quickstart @example_fn "test_quickstart.properties";
return $?;
}Executes a functionality test run with the specified test parameters.
This function is supposed to be used in test suites. It is only defined while in test mode. The specified file must contain the test run parameters. The file must be properties-formatted and each test parameter corresponds to one property line.
Since: 1.2.0
Arguments:
| $1 | A file containing the test run parameters. It is presumed that the file is located relative to the 'tests/resources' directory. This is a mandatory argument. |
Returns:
| 0 | If the test run has finished successfully, without any errors or warnings. |
| nz | In the case of a test failure due to any reason. |
Examples:
# Inside the test case file 'tests/test_func_example.sh'
function test_functionality() {
# Execute a test run with the parameters specified
# in the 'tests/resources/test_example.properties' file
test_functionality_with "test_example.properties";
return $?;
}Adds a warning to the project initialization summary.
This function adds the given warning message to the list of warnings shown at the end after a project has been successfully initialized. Only one string can be given to this function per call. Each message will be shown on a separate line.
Arguments:
| $1 | A string message to log |