#!/usr/bin/env bash
# ------------------------------------------------------------------------------
# Copyright (c) 2013-2026 Geoffray Levasseur <fatalerrors@geoffray-levasseur.org>
# Protected by the BSD3 license. Please read bellow for details.
#
# * Redistribution and use in source and binary forms,
# * with or without modification, are permitted provided
# * that the following conditions are met:
# *
# *   Redistributions of source code must retain the above
# *   copyright notice, this list of conditions and the
# *   following disclaimer.
# *
# *   Redistributions in binary form must reproduce the above
# *   copyright notice, this list of conditions and the following
# *   disclaimer in the documentation and/or other materials
# *   provided with the distribution.
# *
# *   Neither the name of the copyright holder nor the names
# *   of any other contributors may be used to endorse or
# *   promote products derived from this software without
# *   specific prior written permission.
# *
# * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
# * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
# * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
# * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
# * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
# * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
# * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
# * OF SUCH DAMAGE.
# ------------------------------------------------------------------------------

# Private helpers of profile.d/fun.sh, loaded by the module itself.

# Convert a number of milliseconds into a seconds string usable by sleep
# (1500 -> 1.500), in pure bash (no awk fork per call).
# Usage: _fun_ms_to_s <ms>
_fun_ms_to_s()
{
    printf '%d.%03d' $(( $1 / 1000 )) $(( $1 % 1000 ))
}
export -f _fun_ms_to_s

# Fail with a message unless a terminal is available: the demos wait for a key
# read from /dev/tty to stop.
# Usage: _fun_need_tty <command-name>
_fun_need_tty()
{
    if ! { : </dev/tty; } 2>/dev/null; then
        disp E "$1: a terminal is required (it runs until a key is pressed)."
        return 1
    fi
}
export -f _fun_need_tty

# Wait for a key press, then stop the background job $1 and its children.
# The job runs as "( ... ) &"; with job control (interactive shell) it is the
# leader of its own process group, which is signalled as a whole. Without job
# control that group does not exist, so its direct children (the pipeline) are
# killed first, then the subshell. SIGINT is trapped meanwhile so that Ctrl-C
# stops the job like a key press instead of aborting the caller and leaving it
# running. The wait is a polling loop of short timed reads: a blocking read is
# restarted by bash after a trapped signal and would never notice the Ctrl-C.
# Usage: _fun_stop_on_key <pid>
_fun_stop_on_key()
{
    local pid=$1 old_int interrupted=0
    old_int=$(trap -p INT)
    trap 'interrupted=1' INT
    while (( ! interrupted )); do
        IFS= read -r -n 1 -s -t 0.3 _ </dev/tty && break
        # Status above 128 is just the timeout; anything else (such as end of
        # input on the terminal) ends the wait.
        (( $? > 128 )) || break
    done
    kill -- -"$pid" 2>/dev/null || {
        pkill -P "$pid" 2>/dev/null
        kill "$pid" 2>/dev/null
    }
    wait "$pid" 2>/dev/null
    trap - INT
    _trap_restore "$old_int"
    return 0
}
export -f _fun_stop_on_key