✨ added time::getSecondsToMicroseconds

Author: jcaillon

commands.d/self-test-utils

@@ -84,12 +84,15 @@ function selfTestUtils_setupValetForConsistency() {
 
   # shellcheck disable=SC2317
   function time::getProgramElapsedMicroseconds() {
-    if [[ -z ${_FAKE_TIME:-} ]]; then
-      _FAKE_TIME=0
-      _TIME_FACTOR=1
+    if [[ -z ${GLOBAL_FAKE_TIME:-} ]]; then
+      GLOBAL_FAKE_TIME=0
+      GLOBAL_FAKE_TIME_INCREMENT=1000000
+      GLOBAL_FAKE_TIME_INCREMENT_INCREMENT=1000000
+      REPLY=0
+      return 0
     fi
-    ((_FAKE_TIME=_FAKE_TIME+ 1000000 * _TIME_FACTOR, _TIME_FACTOR++))
-    REPLY="${_FAKE_TIME}"
+    ((GLOBAL_FAKE_TIME += GLOBAL_FAKE_TIME_INCREMENT, GLOBAL_FAKE_TIME_INCREMENT += GLOBAL_FAKE_TIME_INCREMENT_INCREMENT))
+    REPLY="${GLOBAL_FAKE_TIME}"
   }
 
   # define it so we can check if it has elements when printing the reply values of a function

docs/content/_index.md

@@ -5,6 +5,8 @@ keywords:
   - valet
   - bash
   - script
+  - sh
+  - shell
   - windows
   - search
   - string
@@ -27,6 +29,17 @@ keywords:
   - bashly
   - options-parser
   - jcaillon
+  - test
+  - testing
+  - approval-tests
+  - ci/cd
+  - production
+  - automation
+  - robust
+  - ble
+  - prompt
+  - list
+  - autocompletion
   - framework
 description: With Valet, you can setup and execute tests, code interactive experiences for your users, navigate and execute your scripts (called commands) from a searchable menu interface, and more! It provides libraries of functions that can be sourced to solve standard programming needs such as string, array or file manipulation, prompting the user, and so on...
 params:

libraries.d/core

@@ -476,17 +476,33 @@ function core::createSavedFilePath() {
 # - Set the correct traps.
 # - Initialize specific temporary files/directories location.
 # - Reset the elapsed time to 0.
+# - Reset the background processes.
 #
 # ```bash
 # core::initSubshell
 # ```
 function core::initSubshell() {
-  trap::registerSubshell
-  fs::setupSubshellTempFileGlobalVariable
+  if ((BASH_SUBSHELL == 0)); then
+    core::fail "This function should only be called in a subshell."
+  fi
+
+  # in case we are in a subshell called within a bash::catchErrors, we reset errexit and not longer catch errors
+  unset -v GLOBAL_ERROR_TRAP_TRY_MODE_ENABLED
+  set -o errexit
+
+  # reset the background processes
+  # shellcheck disable=SC2034
+  declare -g -A \
+    GLOBAL_BACKGROUND_PROCESSES=() \
+    GLOBAL_BACKGROUND_PROCESSES_LOGS=()
+
   # shellcheck disable=SC2034
   declare -g \
     GLOBAL_PROGRAM_STARTED_AT_SECOND="${EPOCHREALTIME%%[.,]*}" \
     GLOBAL_PROGRAM_STARTED_AT_MICROSECOND="${EPOCHREALTIME##*[.,]}"
+
+  trap::registerSubshell
+  fs::setupSubshellTempFileGlobalVariable
 }
 
 # ## core::dump

libraries.d/core-lib

@@ -40,9 +40,6 @@ function fs::setupTempFileGlobalVariable() {
 # of a subshell. We keep everything under a new directory named with the process ID;
 # the dir gets cleanup when the main process ends.
 function fs::setupSubshellTempFileGlobalVariable() {
-  if ((BASH_SUBSHELL == 0)); then
-    core::fail "This function should only be called in a subshell."
-  fi
   TMPDIR="${GLOBAL_TEMPORARY_DIRECTORY}/job-${BASHPID}"
   mkdir -p "${TMPDIR}" 1>/dev/null
   unset -v VALET_CONFIG_RUNTIME_DIRECTORY VALET_CONFIG_TEMP_DIRECTORY XDG_RUNTIME_DIR

libraries.d/core-traps

@@ -424,10 +424,11 @@ function trap::killBackgroundProcesses() {
     fi
   done
 
-  # send SIGHUP to all background processes to terminate them
+  # send SIGINT and SIGHUP to all background processes to terminate them
   for coprocName in "${!GLOBAL_BACKGROUND_PROCESSES[@]}"; do
     coprocPid="${GLOBAL_BACKGROUND_PROCESSES[${coprocName}]:-}"
     log::debug "Killing background process ${coprocName} with PID ${coprocPid}."
+    kill -INT "${coprocPid}" &>/dev/null || :
     kill -HUP "${coprocPid}" &>/dev/null || :
   done
 
@@ -483,17 +484,6 @@ function trap::killBackgroundProcesses() {
 # > - coproc and jobs will not get SIGHUP when the main process ends and they will continue to execute
 # >   until killed or until they check that the main process is dead.
 function trap::registerSubshell() {
-  if ((BASH_SUBSHELL == 0)); then
-    core::fail "This function should only be called in a subshell."
-  fi
-
-  # in case we are in a subshell called within a bash::catchErrors, we reset errexit and not longer catch errors
-  unset -v GLOBAL_ERROR_TRAP_TRY_MODE_ENABLED
-  set -o errexit
-
-  # reset the background processes
-  declare -g -A GLOBAL_BACKGROUND_PROCESSES=() GLOBAL_BACKGROUND_PROCESSES_LOGS=()
-
   trap '_TRAP_SUBSHELL_EXIT_REASON=ERROR trap::onErrorInternal' ERR
   trap trap::onSubshellExitInternal EXIT
   # Register CTRL+C SIGINT (interrupt) and CTRL+\ QUIT (interrupt with a coredump) event handler

libraries.d/lib-coproc

@@ -197,7 +197,7 @@ function coproc::runInParallel() {
 #
 # - Run a main command (mainCommand) that is run once at the start of the coproc.
 # - Loop until the main thread or the coproc exits. Inside the loop, the coproc can receive messages
-#   from the main thread. In the loop, more commands are run:
+#   from the main thread, and more commands are run:
 #   - A loop command (loopCommand) is run at the beginning of each iteration of the loop.
 #   - An on message command (onMessageCommand) is run when a message is received from the main thread.
 # - Finally, it runs an end command (endCommand) once at the end of the coproc.
@@ -268,7 +268,7 @@ function coproc::run() {
   shift 1
   eval "local a= ${*@Q}"
 
-  if [[ -v "GLOBAL_BACKGROUND_PROCESSES[${coprocVarName}]" ]]; then
+  if [[ -v "GLOBAL_BACKGROUND_PROCESSES[${coprocVarName}]" ]] && coproc::isRunning "${coprocVarName}"; then
     core::fail "The coproc ⌜${coprocVarName}⌝ is already running."
   fi
 
@@ -414,6 +414,8 @@ function coproc::sendMessage() {
 #
 # - $1: **coproc variable name** _as string_:
 #       The variable name to use for the coproc.
+# - $@: read parameters _as any_:
+#       The arguments to pass to the read command (e.g. -t for timeout).
 #
 # Returns:
 #
@@ -429,10 +431,11 @@ function coproc::sendMessage() {
 # ```
 function coproc::receiveMessage() {
   local coprocVarName="${1?"The function ⌜${FUNCNAME:-?}⌝ requires more than $# arguments."}"
+  shift 1
 
   REPLY=""
   if eval "local coprocFd=\${${coprocVarName}[0]:-}" && [[ -n ${coprocFd} ]]; then
-    if { IFS=$'\0' read -rd $'\0' -u "${coprocFd}" REPLY; } 2>/dev/null; then
+    if { IFS=$'\0' read "$@" -rd $'\0' -u "${coprocFd}" REPLY; } 2>/dev/null; then
       return 0
     fi
   fi

libraries.d/lib-terminal

@@ -451,7 +451,7 @@ function terminal::testWaitForChar() {
 # to be set using `terminal::setRawMode`.
 #
 #
-# - $@: **read parameters** _as any_:
+# - $@: read parameters _as any_:
 #       additional parameters to pass to the read command
 #
 # Returns:
@@ -535,7 +535,7 @@ function terminal::waitForChar() {
 # You must call `terminal::rebindKeymap` and `terminal::setRawMode` before using this function.
 # You should use `tui::start` instead of using this function directly.
 #
-# - $@: **read parameters** _as any_:
+# - $@: read parameters _as any_:
 #       additional parameters to pass to the read command
 #
 # Returns:

libraries.d/lib-test

@@ -538,6 +538,35 @@ function test::setTerminalInputs() {
   TEST_TERMINAL_INPUTS=("${@}")
 }
 
+# ## test::setProgramElapsedFunction (private)
+#
+# Sets properties for the mocked `time::getProgramElapsedMicroseconds` function.
+#
+# - $1: **current value** _as int_:
+#       The current elapsed time in microseconds.
+# - ${increment} _as int_:
+#       The increment to add to the elapsed time at each call.
+# - ${incrementIncrement} _as int_:
+#       The increment to add to the increment at each call.
+#
+# ```bash
+# test::setProgramElapsedFunction currentValue=0 increment=1000000 incrementIncrement=1000000
+# ```
+# shellcheck disable=SC2034
+function test::setProgramElapsedFunction() {
+  local \
+    currentValue="${1:-0}" \
+    increment="1000000" \
+    incrementIncrement="1000000" \
+    IFS=$' '
+  shift 1
+  eval "local a= ${*@Q}"
+
+  GLOBAL_FAKE_TIME="${currentValue}"
+  GLOBAL_FAKE_TIME_INCREMENT="${increment}"
+  GLOBAL_FAKE_TIME_INCREMENT_INCREMENT="${incrementIncrement}"
+}
+
 # ## test::setTestCallStack (private)
 #
 # This function is used to set the call stack for the tests.

libraries.d/lib-time

@@ -211,3 +211,85 @@ function time::getMicrosecondsToSeconds() {
     printf -v REPLY "0.%s" "${REPLY:0:${precision}}"
   fi
 }
+
+# ## time::getSecondsToMicroseconds
+#
+# Convert a seconds float to microseconds integer.
+# e.g. 1.234567 → 1234567
+#
+# - $1: **seconds** _as float_:
+#       the seconds to convert
+#
+# Returns:
+#
+# - ${REPLY}: The microseconds (integer number).
+#
+# ```bash
+# time::getSecondsToMicroseconds 1.234567
+# echo "${REPLY}"
+# ```
+function time::getSecondsToMicroseconds() {
+  local seconds="${1?"The function ⌜${FUNCNAME:-?}⌝ requires more than $# arguments."}"
+
+  local integerPart="${seconds%%.*}"
+  local decimalPart="${seconds#*.}"
+  if [[ ${integerPart} == "${seconds}" ]]; then
+    decimalPart="0"
+  fi
+  printf -v decimalPart "%-06s" "${decimalPart}"
+  decimalPart="${decimalPart// /0}"
+  REPLY="$((integerPart * 1000000 + 10#${decimalPart:0:6}))"
+}
+
+# ## time::isTimeElapsed
+#
+# Check if a given time in microseconds has elapsed since the last call
+# to this function.
+#
+# - $1: **microseconds** _as int_:
+#       the microseconds to check
+# - ${timerName} _as int_:
+#       A variable name that will be used to store the last time this function was called.
+#       Defaults to the name of the calling function.
+#       Can be set to a fixed value if you call this function from different functions
+#       and want to share the same timer.
+#       (defaults to "${FUNCNAME[1]}")
+#
+# Returns:
+#
+# - 0 if the time has elapsed
+# - 1 if the time has not yet elapsed
+#
+# ```bash
+# if time::isTimeElapsed 500000; then
+#   echo "500ms has elapsed since the last call to this function"
+# fi
+# ```
+function time::isTimeElapsed() {
+  local \
+    microseconds="${1?"The function ⌜${FUNCNAME:-?}⌝ requires more than $# arguments."}" \
+    timerName="${FUNCNAME[1]:-main}" \
+    IFS=" "
+  shift 1
+  eval "local a= ${*@Q}"
+
+  timerName="${timerName//[^a-zA-Z0-9_]/_}"
+
+  local REPLY
+  time::getProgramElapsedMicroseconds
+
+  if [[ ! -v _TIME_IS_TIME_ELAPSED_${timerName} ]]; then
+    # initialize the variable to 0 if it does not exist
+    declare -g "_TIME_IS_TIME_ELAPSED_${timerName}=${REPLY}"
+    return 1
+  fi
+
+  local -n lastTime="_TIME_IS_TIME_ELAPSED_${timerName}"
+
+  if ((REPLY - lastTime >= microseconds)); then
+    lastTime="${REPLY}"
+    return 0
+  fi
+
+  return 1
+}