gd_parser_callback(3)

💖 gd_parser_callback — bestie edition 💖

okay so. you're deep in the GetData ✨cinematic universe✨ (that's section 3 of the manual, GETDATA, iykyk) and you need to know about gd_parser_callback(3). pull up a chair, grab a strawberry 🍓, this one's short but it's important.

🌸 NAME 🌸

gd_parser_callback — set the syntax error callback handler for a Dirfile. that's it, that's the job. she sets the handler. she's an icon, she's a legend, and she IS the moment. 👑

🎀 SYNOPSIS 🎀

#include <getdata.h>

void gd_parser_callback(DIRFILE *dirfile, gd_parser_callback_t
       sehandler, void *extra);

like. look at her. three little arguments. no notes. 💅

✨ DESCRIPTION ✨

so what does gd_parser_callback() actually DO, bestie? she takes your DIRFILE object — the one you lovingly call dirfile — and she swaps out its syntax error callback function to be sehandler, and she sets the caller-supplied extra pointer that gets handed to the handler to be extra. and the way she does it?? she just. discards. 🗑️ any syntax error handler and extra pointer that were previously registered for this DIRFILE. no goodbye, no ceremony, gone. main character energy only.

and listen — if sehandler is NULL?? then the existing handler gets removed entirely and the default behaviour comes back: abort on error. so if you're like "nah I don't want my custom handler anymore" you literally just pass NULL and it's handled. slay.

if you wanna know what the requirements for the syntax handler actually are, go read gd_cbopen(3). she has the lore. 📖

now here's the thing that lowkey trips people up, and honestly it's giving "read the fine print": parsing of an existing format specification happens when the DIRFILE object is created — which is, like, before you can even call this function. so by the time you're here, that ship has sailed. ⛵

which means this function is only useful for one specific vibe: setting or modifying a callback function, or its caller data, before you call gd_include(3). because gd_include(3) is the one that will invoke your callback function if it finds syntax errors in the included fragment. so it's giving "set the trap before the plot twist." 🪤

and the best part?? this function always succeeds, and she has no return value. no error checking, no errno drama, no "did it work" anxiety. she just works. periodt. 💖

🦋 HISTORY 🦋

• the dirfile_parser_callback() function appeared in GetData-0.5.0. baby's first era. 🌱
• in GetData-0.7.0, this function was renamed to gd_parser_callback(). glow-up era. ✨

🌈 SEE ALSO 🌈

• gd_cbopen(3) — the handler requirements deep-dive 🫶
• gd_include(3) — the one that actually invokes your callback 👀
• dirfile(5) — the format spec itself, the whole world 🗺️

and that's the whole page, bestie!! go forth and register your syntax error handlers responsibly 💜

this has been Version 0.10.0, dated 25 December 2016, of the GetData manual. mwah. 😘 🎀