📂 log

log::debug

Displays a debug message.

• $@: message as string: the debug messages to display

log::debug "This is a debug message."

log::error

Displays an error message.

• $@: message as string: the error messages to display

log::error "This is an error message."

You probably want to exit immediately after an error and should consider using core::fail function instead.

log::errorTrace

Displays an error trace message. This is a trace message that is always displayed, independently of the log level. It can be used before a fatal error to display useful information.

• $@: message as string: the trace messages to display

log::errorTrace "This is a debug message."

log::getCallStack

This function returns the current function stack.

• $1: Stack to skip as int: (optional) Can be set using the variable _OPTION_STACK_TO_SKIP. The number of stack to skip. (defaults to 1 which skips this function)
• $2: Stack to skip at end as int: (optional) Can be set using the variable _OPTION_STACK_TO_SKIP_AT_END. The number of stack to skip at the end. (defaults to 0)
• ${_OPTION_WRAP_WIDTH} as int: (optional) The width to wrap the call stack. (defaults to the terminal width)

Returns:

• ${RETURNED_VALUE}: The call stack as a string.

log::getCallStack
echo "${RETURNED_VALUE}"

For test purposes, you can set the GLOBAL_STACK_FUNCTION_NAMES, GLOBAL_STACK_SOURCE_FILES and GLOBAL_STACK_LINE_NUMBERS variables to simulate a call stack.

log::getLevel

Get the current log level.

Returns:

• ${RETURNED_VALUE}: The current log level.

log::getLevel
printf '%s\n' "The log level is ⌜${RETURNED_VALUE}⌝."

log::info

Displays an info message.

• $@: message as string: the info messages to display

log::info "This is an info message."

log::isDebugEnabled

Check if the debug mode is enabled.

Returns:

• $?:
  • 0 if debug mode is enabled (log level is debug)
  • 1 if disabled

if log::isDebugEnabled; then printf '%s\n' "Debug mode is active."; fi

log::isTraceEnabled

Check if the trace mode is enabled.

Returns:

• $?:
  • 0 if trace mode is enabled (log level is trace)
  • 1 if disabled

if log::isTraceEnabled; then printf '%s\n' "Debug mode is active."; fi

log::print

Display a log message.

• $1: color name as string: The color name to use for the severity (TRACE, DEBUG…).
• $2: icon as string: The icon to display in the log message (utf8 character from nerd icons).
• $3: severity as string: The severity to display (max 7 chars for the default log pattern).
• $@: message as string: The message to log.

log::print "SUCCESS" $'\uf14a' "OK" "This is a success message."

log::printCallStack

This function prints the current function stack in the logs.

• $1: Stack to skip as int: (optional) Can be set using the variable _OPTION_STACK_TO_SKIP. The number of stack to skip. (defaults to 2 which skips this function and the first calling function which is usually the onError function)
• $2: Stack to skip at end as int: (optional) Can be set using the variable _OPTION_STACK_TO_SKIP_AT_END. The number of stack to skip at the end. (defaults to 0)

log::printCallStack
log::printCallStack 0

For test purposes, you can set the GLOBAL_STACK_FUNCTION_NAMES, GLOBAL_STACK_SOURCE_FILES and GLOBAL_STACK_LINE_NUMBERS variables to simulate a call stack.

log::printFile

Display a file content with line numbers in the logs. The file content will be aligned with the current log output and hard wrapped if necessary.

• $1: path as string: the file path to display.
• $2: max lines as int: (optional) Can be set using the variable _OPTION_MAX_LINES. Max lines to display, can be set to 0 to display all lines. (defaults to 0)

log::printFile "/my/file/path"

log::printFileString

Display a file content with line numbers in the logs. The file content will be aligned with the current log output and hard wrapped if necessary.

• $1: content variable name as string: The name of the variable containing the file content to print.
• $2: max lines as int: (optional) Can be set using the variable _OPTION_MAX_LINES. Max lines to display, can be set to 0 to display all lines. (defaults to 0)

log::printFileString "myvar"

This function is not at all suited for large strings, print the content to a file instead.

log::printRaw

Display something in the log stream. Does not check the log level.

• $1: content variable name as string: The variable name containing the content to print (can contain new lines).

log::printRaw "my line"

log::printString

Display a string in the log. The string will be aligned with the current log output and hard wrapped if necessary. Does not check the log level.

• $1: content as string: the content to log (can contain new lines)
• $2: new line pad string as string: (optional) the string with which to prepend each wrapped line (empty by default)

log::printString "my line"

log::saveFile

Save the given file by copying it to a new file in the user local state directory (using core::createNewStateFilePath). Useful for debugging purposes, to save the state of a file during execution.

• $1: path as string: The file path to save.
• $2: suffix as string: The suffix to add to the file name.
• $3: log path as bool: (optional) if true, log the path of the saved file using log::printString (defaults to true)

Returns:

• ${RETURNED_VALUE}: The path to the saved file.

log::saveFile "/my/file/path" "suffix" "important result file"

log::saveFileString

Save the given string to a new file in the user local state directory (using core::createNewStateFilePath). Useful for debugging purposes, to save the state of a string during execution.

• $1: content variable name as string: The variable name of the content to save.
• $2: suffix as string: The suffix to add to the file name.
• $3: log path as bool: (optional) if true, log the path of the saved file using log::printString (defaults to true)

Returns:

• ${RETURNED_VALUE}: The path to the saved file.

log::saveFileString "my content" "suffix" "important result file"

log::setLevel

Set the log level.

• $1: log level as string: The log level to set (or defaults to info), acceptable values are:
  • trace
  • debug
  • info
  • success
  • warning
  • error
• $2: silent as bool: (optional) true to silently switch log level, i.e. does not print a message (defaults to false)

log::setLevel debug
log::setLevel debug true

log::success

Displays a success message.

• $@: message as string: the success messages to display

log::success "This is a success message."

log::trace

Displays a trace message.

• $@: message as string: the trace messages to display

log::trace "This is a trace message."

log::warning

Displays a warning.

• $@: message as string: the warning messages to display

log::warning "This is a warning message."