📂 log

⚡ log::debug

Displays a debug message.

Inputs:

• $1: message as string:

  the debug messages to display

Example usage:

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

⚡ log::error

Displays an error message.

Inputs:

• $1: message as string:

  the error messages to display

Example usage:

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.

Inputs:

• $1: message as string:

  the trace messages to display

Example usage:

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

⚡ log::getCallStack

This function returns the current function stack.

Inputs:

• ${stackToSkip} as int:

  (optional) The number of stack to skip. For instance, a value of 1 will skip this function.

  (defaults to 1)

• ${stackToSkipAtEnd} as int:

  (optional) The number of stack to skip at the end.

  (defaults to 0)

• ${wrapWidth} as int:

  (optional) The width to wrap the call stack.

  (defaults to 0)

Returns:

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

Example usage:

log::getCallStack
echo "${REPLY}"
log::getCallStack stackToSkip=2 stackToSkipAtEnd=1 wrapWidth=80

For test purposes, you can set the GLOBAL_MOCK_STACK_FUNCTION_NAMES, GLOBAL_MOCK_STACK_SOURCE_FILES and GLOBAL_MOCK_STACK_LINE_NUMBERS variables to simulate a call stack.

⚡ log::getLevel

Get the current log level.

Returns:

• ${REPLY}: The current log level.

Example usage:

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

⚡ log::info

Displays an info message.

Inputs:

• $1: message as string:

  the info messages to display

Example usage:

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

Example usage:

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

Example usage:

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

⚡ log::printCallStack

This function prints the current function stack in the logs.

Inputs:

• ${stackToSkip} as int:

  (optional) The number of stack to skip. For instance, a value of 2 will skip this function and the first calling function.

  (defaults to 2)

• ${stackToSkipAtEnd} as int:

  (optional) The number of stack to skip at the end.

  (defaults to 0)

Example usage:

log::printCallStack
log::printCallStack stackToSkip=0

For test purposes, you can set the GLOBAL_MOCK_STACK_FUNCTION_NAMES, GLOBAL_MOCK_STACK_SOURCE_FILES and GLOBAL_MOCK_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.

Inputs:

• $1: path as string:

  the file path to display.

• ${maxLines} as int:

  (optional) Max lines to display, can be set to 0 to display all lines.

  (defaults to 0)

Example usage:

log::printFile "/my/file/path"
log::printFile "/my/file/path" maxLines=10

⚡ 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.

Inputs:

• $1: content variable name as string:

  The name of the variable containing the file content to print.

• ${maxLines} as int:

  (optional) Max lines to display, can be set to 0 to display all lines.

  (defaults to 0)

Example usage:

log::printFileString "myvar"
log::printFileString "myvar" maxLines=10

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.

Inputs:

• $1: content variable name as string:

  The variable name containing the content to print (can contain new lines).

Example usage:

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.

Inputs:

• $1: content as string:

  the content to log (can contain new lines)

• ${newLinePadString} as string:

  (optional) the string with which to prepend each wrapped line

  (defaults to “”)

Example usage:

log::printString "my line"
log::printString "my line" newLinePadString="  "

⚡ log::saveFile

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

Inputs:

• $1: path as string:

  The file path to save.

• ${suffix} as string:

  (optional) The suffix for the file to create.

  (defaults to “”)

• ${silent} as bool:

  (optional) if true, do not log the path of the saved file using log::printString

  (defaults to false)

Returns:

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

Example usage:

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::createSavedFilePath). Useful for debugging purposes, to save the state of a string during execution.

Inputs:

• $1: content variable name as string:

  The variable name of the content to save.

• ${suffix} as string:

  (optional) The suffix for the file to create.

  (defaults to “”)

• ${silent} as bool:

  (optional) if true, do not log the path of the saved file using log::printString

  (defaults to false)

Returns:

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

Example usage:

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

⚡ log::setLevel

Set the log level.

Inputs:

• $1: log level as string:

  The log level to set (or defaults to info), acceptable values are:

  • trace
  • debug
  • info
  • success
  • warning
  • error

• ${silent} as bool:

  (optional) true to silently switch log level, i.e. does not print a message

  (defaults to false)

Example usage:

log::setLevel debug
log::setLevel debug silent=true

⚡ log::success

Displays a success message.

Inputs:

• $1: message as string:

  the success messages to display

Example usage:

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

⚡ log::trace

Displays a trace message.

Inputs:

• $1: message as string:

  the trace messages to display

Example usage:

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

⚡ log::warning

Displays a warning.

Inputs:

• $1: message as string:

  the warning messages to display

Example usage:

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