LIBMAWK_REGISTER_FUNCTION(3libmawk)

✨ LIBMAWK_REGISTER_FUNCTION ✨

the libmawk manual · section 3libmawk · bestie we are SO deep in the C weeds rn and I am thriving 💅

🎀 NAME 🎀

libmawk_register_function — registers a C function with a callback 🫶 like you're literally donating a function from your host app into mawk's world

🌸 SYNOPSIS 🌸

#include <libmawk.h>

typedef CELL *libmawk_c_function(mawk_state_t *m, CELL *sp, int a_args);
int libmawk_register_function(mawk_state_t *MAWK, const char *fname,
libmawk_c_function *callback);
CELL *libmawk_stackret(CELL *original_sp);

💖 DESCRIPTION 💖

okay so. libmawk_register_function() is the glow-up move where your host application donates a user defined function into a mawk context, and once it's in there it acts exactly like user defined functions written in awk. no cap. it's giving native.

the name of the new function goes in fname, and it should not match any of the user defined function names in the awk script — like, don't do that, that's a name collision and we don't want the drama 🙈

when the user function gets called back, the argument sp is the stack pointer and a_args holds the number of arguments. and here's the part where you gotta lock in: the user function is responsible for managing the stack. it should pop all arguments before returning. yes bestie, you pop them, that's on you 👑

the user function should also generate a return value, which you do by calling libmawk_set_cell() on the stack slot returned by libmawk_stackret. and libmawk_stackret should be called with the modified sp after popping all arguments. order matters, periodt ✨

argument m is a libmawk context previously returned by libmawk_initialize() or libmawk_initialize_stage3().

for more info about user function callbacks — especially on stack handling, which is the whole vibe honestly — see the manual page example(3libmawk) 📖

🌈 RETURN VALUE 🌈

• the user function should return the stack pointer after popping all arguments
• the libmawk_register_function call returns 0 on success 🎉
• call libmawk_stackret returns a stack pointer to the slot where the user function should store its return value

fr fr, read those twice. the stack pointer you hand back is not the same energy as the stack pointer you got handed. 🫠

🦋 SEE ALSO 🦋

• libmawk_initialize_stage(3libmawk)
• libmawk_initialize(3libmawk)
• libmawk_set_cell(3libmawk)
• libmawk_print_cell(3libmawk)

and that's the whole page, bestie ✨ this icon of a manual page is from libmawk, dated 2009-08-12 — yes she's vintage, and yes she still ate 💖 go forth and pop your stack correctly, mwah 🎀