@lundstrong/rbxts-transform-debug v1.0.0-rc.4
rbxts-transform-debug
A debugging transformer for roblox-ts. Contains helper functions for debugging roblox-ts code with debug information attached.
How it works
Say we have this example code:
import { $dbg, $print } from "rbxts-transform-debug";
export function makeHello(name: string) {
return $dbg(`Hello from ${name}!`);
}
const x = 42;
$dbg(10 > 20);
$dbg(x);
$print(makeHello("Vorlias"))
The emit would be:
local function makeHello(name)
return (function(value)
print("[src/shared/module.ts:4] `Hello from ${name}!` =", value)
return value
end)("Hello from " .. name .. "!")
end
local x = 42
print("[src/shared/module.ts:8] 10 > 20 =", 10 > 20)
print("[src/shared/module.ts:9] x =", x)
print("[src/shared/module.ts:10]", makeHello("Vorlias"))
If this code was ran, our output would give:
[src/shared/module.ts:8] 10 > 20 = false
[src/shared/module.ts:9] x = 42
[src/shared/module.ts:2] `Hello from ${name}!` = Hello from Vorlias!
[src/shared/module.ts:10] Hello from Vorlias!
Macros
$dbg
Based on rust's dbg! macro.
Will print out the expression + it's value prefixed by a file name + line number. If it is a complex expression (e.g. a right hand side expression) this will be done via an IIFE, otherwise a regular print statement.
Simple:
const x = 10;
$dbg(x);
print("[source.ts:2] x =", 10)
IIFE:
function test() {
return 10;
}
const value = $dbg(test());
local function test()
return 10
end
local value = (function(value)
print("[source.ts:4] test() =", value)
return value
end)(test())
$print
Same as print
, but will prefix the print with the file name + line number. Also controlled by the below settings as to whether or not it's emitted.
$print("Hello, World!");
print("[source.ts:1]", "Hello, World!");
$warn
Same as warn
, but will prefix the warning with the file name + line number. Also controlled by the below settings. Also controlled by the below settings as to whether or not it's emitted.
$warn("Hello, World!");
warn("[source.ts:1]", "Hello, World!");
Configuration
environmentRequires
Object
An object of environment variable names mapped to either the required value, or true
(if you want to only chekc that it's set)
The purpose of this is to conditionally render the $dbg
calls as the debug statements only if environment variables match your set conditions.
enabled
Boolean (Defaults to true
)
Whether or not this transformer actually emits the $dbg
as debug statements at all. If false
, it will just return the expressions themselves.
scope
String? (defaults to undefined
)
Adds a scope to the start of any logging to the Roblox Console. If undefined, this feature will not be enabled.
showSourcePath
Boolean (Defaults to true
)
Whether or not the transformer should show the file path + line number of where the logging was from.