isaacscript-common/dist/functions/log.js

Helper functions and features for IsaacScript mods.

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.getParentFunctionDescription = getParentFunctionDescription;
exports.log = log;
exports.logAndPrint = logAndPrint;
exports.logError = logError;
const types_1 = require("./types");
/**
 * Helper function to get the name and the line number of the current calling function.
 *
 * For this function to work properly, the "--luadebug" flag must be enabled. Otherwise, it will
 * always return undefined.
 *
 * @param levels Optional. The amount of levels to look backwards in the call stack. Default is 3
 *               (because the first level is this function, the second level is the calling
 *               function, and the third level is the parent of the calling function).
 */
function getParentFunctionDescription(
// We use 3 as a default because:
// - The first level is this function.
// - The second level is the calling function.
// - The third level is the parent of the calling function.
levels = 3) {
    // "debug" is not always defined like the Lua definitions imply.
    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
    if (debug !== undefined) {
        // The "--luadebug" launch flag is enabled.
        const debugTable = debug.getinfo(levels);
        if (debugTable !== undefined) {
            return `${debugTable.name}:${debugTable.linedefined}`;
        }
    }
    if (SandboxGetParentFunctionDescription !== undefined) {
        // The Racing+ sandbox is enabled.
        return SandboxGetParentFunctionDescription(levels);
    }
    return undefined;
}
/**
 * Helper function to avoid typing out `Isaac.DebugString()`.
 *
 * If you have the "--luadebug" launch flag turned on, then this function will also prepend the
 * function name and the line number before the string, like this:
 *
 * ```text
 * [INFO] - Lua Debug: saveToDisk:42494 - The save data manager wrote data to the "save#.dat" file.
 * ```
 *
 * Subsequently, it is recommended that you turn on the "--luadebug" launch flag when developing
 * your mod so that debugging becomes a little bit easier.
 *
 * @param msg The message to log.
 * @param includeParentFunction Optional. Whether to prefix the message with the function name and
 *                              line number, as shown in the above example. Default is true.
 */
function log(msg, includeParentFunction = true) {
    if ((0, types_1.isNumber)(msg)) {
        msg = msg.toString();
    }
    const parentFunctionDescription = includeParentFunction
        ? getParentFunctionDescription()
        : undefined;
    const debugMsg = parentFunctionDescription === undefined
        ? msg
        : `${parentFunctionDescription} - ${msg}`;
    Isaac.DebugString(debugMsg);
}
/**
 * Helper function to log a message to the "log.txt" file and to print it to the screen at the same
 * time.
 */
function logAndPrint(msg) {
    log(msg);
    print(msg);
}
/**
 * Helper function to log an error message and also print it to the console for better visibility.
 *
 * This is useful in situations where using the `error` function would be dangerous (since it
 * prevents all of the subsequent code in the callback from running).
 */
function logError(msg) {
    const errorMsg = `Error: ${msg}`;
    logAndPrint(errorMsg);
}