GOLF(2gg)

👑 GOLF(2gg) — the trace-run page, bestie edition ✨

okay so we're in the GOLF(2gg) manual, Development section, and today's main character is trace-run. she's a debugging girlie and she's literally about to change your whole tracing life. no cap. 💅

---

🎀 NAME 🎀

trace-run — it's giving (debugging) ✨

---

🌸 PURPOSE 🌸

Emit trace. that's it, that's the whole job. she emits, she traces, she slays. 🦋

---

💖 SYNTAX 💖

trace-run [ <format>, <variable> [ , ... ] ]

look at her. so simple. so iconic. 👑

---

✨ DESCRIPTION ✨

so here's the tea: trace-run takes your <format> string, formats up a tracing message using it plus a lil list of <variable>s, and then writes the whole result into the current process' trace file. periodt. 💌

and listen — you can totally call trace-run with no clauses at all, and in that case it just records a location (file name + line number) into the trace file. which is lowkey perfect when all you wanna know is "did the execution even pass through this code, or was it ghosting me". 👻

but if trace-run does have any other clauses? then the <format> string is mandatory and there has to be at least one <variable>. yes, even if you're just tracing a plain string literal — you still gotta use "%s" as the format. the rules are the rules, bestie. 😭

for tracing to actually do anything, tracing has to be enabled — see the --debug and --trace options in gg. and if you're wondering where your trace files even live, go check the directories section. iykyk 🫶

🧚 FORMAT 🧚

the <format> string must be a literal, no funny business. your <variable>s follow <format>, separated by commas, in the exact same order as the placeholders. and here's the part where you gotta be careful: if you use any placeholder that isn't in the list below, or your variable types don't match the corresponding placeholder's type in <format>, your program will error out. 💀 not a vibe. (see trace-run for an example of usage)

here's the full placeholder menu, bestie — memorize her:

• %s for a string
• %c for a number displayed as a character,
• %<number>s for a string output with a width of at least <number> (any excess filled with spaces to the left),
• %ld for a number (use "lo" for displaying in octal notation and "lx" for hexadecimal notation).
• %<number>ld for a number output with a width of at least <number> (any excess filled with spaces to the left). Use "lo" for displaying in octal notation and "lx" for hexadecimal notation.

now watch her work, here's an example of the format placeholders in action:

%% /my-request public
    @Hi
    trace-run "%s it's %ld degrees outside, or with minimum width: %20s it's %20ld outside", "yes", 90, "yes", 90
%%

create and make the application:

sudo mgrg -i -u $(whoami) test
gg --trace --debug

run it:

gg -r --req="/my-request" --exec

the output is:

Hi

and to find the location of the trace file:

gg -t 1

the line in the trace file that your trace-run spits out would be similar to:

2024-08-01-17-13-55 (my_request.golf:4)| my_request yes it's 90 degrees outside, or with minimum width:                  yes it's                   90 outside

she ate that fr fr 🔥

---

💜 EXAMPLES 💜

// Trace information
trace-run "Program wrote %ld bytes into file %s", num_bytes, file_name

// Trace that program execution passed through here
trace-run

first one = the girlies who wanna know stuff. second one = the girlies who just wanna know if. both valid. both iconic. 🌈

---

🦋 SEE ALSO 🦋

• Debugging
• debugging
• trace-run
• See all documentation

go read them, bestie, they're all part of the same little friend group 🫶

---

and that's the whole page, my love 💖 this was the $VERSION version, dated $DATE, and yes she's still out here living under the name GOLF(2gg) ✨ mwah, go trace something pretty 🎀💅