JSON(3am)

💖 JSON(3am) 💖

ok so bestie, welcome to the json page from section 3 of the gawk extension modules manual — it's the gawk extension that lets you import from and export to JSON format. buckle up, it's actually so good. 🦋

---

✨ NAME ✨

json — the gawk extension to import from and export to JSON format. yes that's the whole vibe. periodt. 💅

---

🌸 SYNOPSIS 🌸

@load "json"

status = json::from_json(string, array)

encoded = json::to_json(array [, use_real_array])

# compatibility functions in json_compat.awk:
@include "json_compat"

status = json_fromJSON(string, array)

encoded = json_toJSON(array [, use_real_array])

---

🎀 DESCRIPTION 🎀

ok so here's the tea, bestie. JSON objects represent associations of names with values — what we're gonna call linear arrays (arrays with numeric indices) — plus subgroupings (nested associative arrays). and the way these objects map onto gawk's true multidimensional associative arrays? literally perfect. 💀✨ this extension gives you a mechanism to encode a gawk array as a JSON string and to decode a JSON object into a gawk array. two-way street, we love to see it.

the json extension adds two functions as follows:

🧚 json::from_json(string, array)

this function takes a string representing a JSON object and decodes it into the array argument. 🫶

heads up: the array is cleared first. like, wiped. gone. so don't be attached to whatever was in there.

the return status is one upon success or zero upon failure. and on top of that, gawk's ERRNO variable gets updated to (sort of) indicate what the problem was. it's giving "we tried our best to explain" energy.

🧚 json::to_json(array[, use_real_array])

this function takes an array argument and encodes the array contents as a JSON object in the returned string. the returned string will be empty if an error of some kind occurred 😭 and again, gawk's ERRNO variable is updated to (sort of) indicate what the problem was.

if the optional parameter use_real_array is not zero, then json::to_json() encodes arrays indexed from 1 to N as JSON linear arrays, instead of as associative arrays. this gives a better rendition into JSON — slay — at the expense of some additional CPU time to verify that the array is indeed indexed linearly. so it's a little trade-off, bestie. pay the CPU tax, get the prettier JSON. 💸

---

💀 BUGS 💀

ngl the mapping between gawk objects and JSON objects isn't perfect. it's giving "close enough" energy. in particular:

• JSON boolean objects map to 1 or 0, losing the type distinction. so like... was it true? was it 1? we'll never know. tragic.
• Typed regular expression constants in gawk are encoded as a string, with the regexp bracketed by @/ and /. for example: pattern:"@/[a-z]+[0-9]?/".

also, the json_compat.awk library file provides compatibility functions for the previous version of this extension, which did not take advantage of gawk's namespace facility. iykyk. 🌈

---

🔥 EXAMPLE 🔥

@load "filefuncs"
@load "json"
...
BEGIN {
     stat("/etc/passwd", data)
     statinfo = json::to_json(data)
     print statinfo
}

BEGIN {
     getline statinfo
     if (! json::from_json(statinfo, data))
          print "JSON import failed!" > "/dev/stderr"
          exit 1
     }

     # do something with the info
}

look at that. iconic. 👑

---

🌈 NOTES 🌈

this extension uses RapidJSON to parse a JSON document into a gawk array. this approximates the Document Object Model (DOM) paradigm. in the author's humble opinion, the SAX paradigm for parsing JSON does not match well with awk's design. so if you want SAX parsing of JSON — bestie, this isn't the place. 🙈

---

🦋 SEE ALSO 🦋

• JSON home page: https://www.json.org/
• Wikipedia: https://en.wikipedia.org/wiki/JSON
• RapidJSON home page: http://rapidjson.org/

---

👑 AUTHOR 👑

Arnold D. Robbins — we stan. 💜

---

📜 COPYING PERMISSIONS 📜

Copyright © 2017, the Free Software Foundation, Inc. Copyright © 2017, 2020, Arnold David Robbins.

Permission is granted to make and distribute verbatim copies of this manual page provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual page under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual page into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

---

and that's the whole page, bestie!! 🎀 this one came from the Free Software Foundation, dated Sep 07 2020, and it's the JSON(3am) page — now go forth and encode some arrays, you main character. 💅✨🫶