KJSON_ARRAY_OPEN(3)

💖 KJSON_ARRAY_OPEN(3) — the kcgijson array-scope page, bestie edition 💖

okay so this is from the Library Functions Manual for KJSON_ARRAY_OPEN(3), and it lives in the library "libkcgijson" 💅 yes that's libkcgijson, say it with your chest.

---

✨ NAME ✨

kjson_array_open, kjson_arrayp_open — open an array scope for kcgijson 🎀

---

🌸 LIBRARY 🌸

library "libkcgijson" — that's the one, no cap 🫶

---

🦋 SYNOPSIS 🦋

#include <sys/types.h>
#include <stdarg.h>
#include <stdint.h>
#include <kcgi.h>
#include <kcgijson.h>

enum kcgi_err
kjson_array_open(struct kjsonreq *req);

enum kcgi_err
kjson_arrayp_open(struct kjsonreq *req, const char *name);

like, includes first, then the two functions, both returning enum kcgi_err — got it? iconic. ⭐

---

💜 DESCRIPTION 💜

so basically you're opening an array scope in a context req that was initialised with khtml_open(3). that's the whole vibe. 🌈

scopes get closed with kjson_array_close(3) or kjson_close(3) — you can't just leave them open forever, that's not the energy we're going for 😭

array scopes may be filled in with un-named values, like when you use kjson_putstring(3) 🍓

okay and here's the distinction, because it matters:

• the kjson_array_open() form is for array scopes
• the kjson_arrayp_open() form is for objects

and the cute part: passing a NULL value to name for kjson_arrayp_open() is equivalent to calling kjson_array_open(). literally the same thing, they're twins 💀

---

🔥 RETURN VALUES 🔥

returns an enum kcgi_err indicating the error state. here's the whole roster, no skipping:

• KCGI_OK — success!! not an error!! we love to see it 👑
• KCGI_ENOMEM — internal memory allocation failure, and yes that includes reaching the maximum number of possible JSON scopes. so like, too many scopes = sad. 😭
• KCGI_HUP — the output connection has been terminated. for FastCGI connections, the current connection should be released with khttp_free(3) and the parse loop reentered. 🫶
• KCGI_FORM — the connection is still expecting headers with khttp_head(3). this indicates that khttp_body(3) did not return with success or was not invoked. for FastCGI connections, the current connection should be released with khttp_free(3) and the parse loop reentered. (yes, same drill as above 💅)
• KCGI_SYSTEM — internal system error writing to the output stream. 💀
• KCGI_WRITER — the incorrect form was used for the current scope, for example, an array-type write within an object. like, wrong vibe for the wrong place, bestie 🙈

fr fr read those last two FastCGI ones carefully — release with khttp_free(3) and reenter the parse loop. that's not optional flavour text, that's instructions.

---

🧚 EXAMPLES 🧚

the following outputs a simple JSON document. it assumes r is a struct kreq pointer. and for brevity, it does not do any error checking — which, okay, fair for a demo, but you know better, right? 😌

khttp_head(r, kresps[KRESP_STATUS],
  "%s", khttps[KHTTP_200]);
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
  "%s", kmimetypes[KMIME_APP_JSON]);
khttp_body(r);
kjson_open(&req, r);
kjson_array_open(&req);
kjson_putstring(&req, "bar");
kjson_putstring(&req, "baz");
kjson_close(&req);

look at that. headers, body, open, open array, two strings, close. ate and left no crumbs 🍓✨

---

⭐ SEE ALSO ⭐

kcgijson(3) — go read that one too, iykyk 🌸

---

🎀 AUTHORS 🎀

written by Kristaps Dzonsons <kristaps@bsd.lv>. thank you king 🫶👑

---

and that's the page!! this version came from Debian, with the date placeholder $Mdocdate$, and the man page title is KJSON_ARRAY_OPEN(3) — mwah, go write some JSON arrays bestie 💖🦋💅