KHTTP_TEMPLATEX(3)

💖 khttp_templatex(3) — Library Functions Manual, bestie edition 💖

okay so bestie, welcome to the khttp_templatex(3) page from the Library Functions Manual 💅 this one is all about khttp_templatex, khttp_templatex_buf, and khttp_templatex_fd — the template-filling glow-up for kcgi. It lives in library “libkcgi”. slay.

---

✨ NAME ✨

khttp_templatex, khttp_templatex_buf, khttp_templatex_fd — emit filled-in templates for kcgi 🎀

📚 LIBRARY 📚

library “libkcgi” — that's the squad, no cap 🫶

🧾 SYNOPSIS 🧾

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

enum kcgi_err
khttp_templatex(const struct ktemplate *t, const char *filename,
    const struct ktemplatex *x, void *arg);

enum kcgi_err
khttp_templatex_buf(const struct ktemplate *t, const char *buf,
    size_t sz, const struct ktemplatex *x, void *arg);

enum kcgi_err
khttp_templatex_fd(const struct ktemplate *t, int fd,
    const char *filename, const struct ktemplatex *x, void *arg);

🌸 DESCRIPTION 🌸

okay so these functions modify input by replacing keys in a template. This generalises the khttp_template(3) family of functions with generic writing functions. All functions accept a template t consisting of the following fields:

• const char *const *key — an array of keys to be replaced in the template 🔑
• size_t keysz — the number of keys in t->key
• void *arg — an optional argument passed to t->cb
• int (*cb)(size_t index, void *arg) — the callback function invoked when a key at position index, which is always less than t->keysz, is found in t->key. The optional arg is passed the function. The function must return zero on failure, non-zero on success 💖

They further accept an extension x consisting of the following:

• writer — a writing function for writing input that does not match key sequences. If it is invoked and the return value is not KCGI_OK, templating stops and the return value is returned to the caller.
• fbk — a fall-back function invoked if a key sequences was not found in the c->key array. This accepts the key sequence, length of the sequence, and arg. If NULL, key sequences not found are passed to writer.

If t is NULL, the input is passed through to x->writer without any processing 🫡

Otherwise, the input is passed to x->writer until a key sequence is encountered matching a key in t->key. The callback t->cb is then invoked instead of printing the key sequence. If there are multiple matching keys in t->key, only one is used (which is not yet fixed). If the key sequence is not found in t->key, it is passed to x->fbk, if not NULL, or passed directly to x->writer otherwise.

bestie, quick vibe check: if there are multiple matching keys in t->key, only one is used — and which one is not yet fixed 😭 that's literally what the page says.

The different input types are khttpx_template(), which reads input from the file filename; khttpx_template_buf(), which reads from a binary buffer buf of length sz; and khttpx_template_fd(), which reads from a file descriptor fd with optional file-name fname used only for logging purposes. (yes, those are the spellings on the page 🙈)

🎀 SYNTAX 🎀

Each substring of the input beginning and ending with a pair of “at” signs, @@key@@, is called a "key sequence". Zero-length keys @@@@ are allowed and match empty template keys. If the @@ pair is escaped with a single backslash, \@@, the backslash is removed and it's emitted as @@.

A key sequence may not contain an escaped pair: this is parsed as a backslash followed by the trailing pair.

🔥 RETURN VALUES 🔥

These return an enum kcgi_err indicating the error state:

• KCGI_OK — no error occurred.
• KCGI_ENOMEM — memory allocation failed.
• KCGI_SYSTEM — a system call failed. For example, writing to the output stream failed, or khttp_template() failed to open(2) filename.
• KCGI_FORM — t->cb returned 0.

If the x->writer function returns anything but KCGI_OK, the return code is passed as the return value.

🧪 EXAMPLES 🧪

The following simple example takes a buffer buf and applies the replacement template of two values, writing it to the current context req. It stores the result in the given buffer out.

static int writer(size_t idx, void *arg)
{
  struct kcgi_buf *p = arg;
  if (idx == 0)
    kcgi_buf_puts(p, "foo-value");
  else if (idx == 1)
    kcgi_buf_puts(p, "bar-value");
  return 1;
}

enum kcgi_err format(struct kcgi_buf *out)
{
  const char *const keys[] = { "foo", "bar" };
  struct ktemplate t = {
    .key = keys,
    .keysz = 2,
    .arg = out,
    .cb = writer
  };
  struct ktemplatex x = {
    .writer = kcgi_buf_write,
    .fbk = NULL
  };
  const char *in = "foo=@@foo@@, bar=@@bar@@";

  memset(out, 0, sizeof(struct kcgi_buf));
  return khttp_templatex_buf
    (&t, in, strlen(in), &x, out);
}

The function will produce "foo=foo-value, bar=bar-value" ✨

👀 SEE ALSO 👀

• kcgi(3)
• khttp_body(3)
• khttp_parse(3)
• khttp_template(3)
• khttp_write(3)

👑 AUTHORS 👑

Written by Kristaps Dzonsons <kristaps@bsd.lv>. icon behavior fr fr 👑

---

xoxo, Debian says hiii 🌸 — $Mdocdate$ — KHTTP_TEMPLATEX(3) 💅