Bags & JSON

The bag nested under a key, or none when the key is missing or holds something that is not a bag.

if bagBag(newBag(), "stats") == none { print("unset") }

The list of bags stored under a key, or an empty list when the key is missing or holds something else — so a for loop over it is always safe.

print(count(bagBags(newBag(), "rows")))

The flag stored under a key, or none when the key is missing or holds something that is not a flag.

if bagFlag(newBag(), "alive") == none { print("unset") }

The flag under a key, or the fallback when the key is missing or holds something else. Never none — the right shape for a condition.

if bagFlagOr(newBag(), "alive", false) { print("up") }

True when the bag has a field under that key, whatever its type.

if bagHas(newBag(), "hp") { print("set") }

Adds to a number field in place, treating a missing or non-number field as 0 first — the per-row tally. Faults on overflow.

bagInc(newBag(), "kills", 1)

Every field name in the bag, in the order they were first put — walk it with for to see what a bag holds.

for k in bagKeys(newBag()) { print(k) }

An empty list of bags, ready to append rows into. Lists are immutable as ever: append answers a new list, so write table = append(table, row).

let table = bagList()  print(count(bagList()), count(table))

The number stored under a key, or none when the key is missing or holds something that is not a number.

if bagNumber(newBag(), "hp") == none { print("unset") }

The number under a key, or the fallback when the key is missing or holds something else. Never none — the right shape for a readout.

print(bagNumberOr(newBag(), "hp", 0))

The list of numbers stored under a key, or an empty list when the key is missing or holds something else — so a for loop over it is always safe.

print(count(bagNumbers(newBag(), "prices")))

A new bag already holding one number field — the short way to start one.

A new bag already holding one text field — the short way to start one.

A new bag already holding one flag field — the short way to start one.

let b = bagOf("hp", 30)  print(b)
let b = bagOf("name", "guard")  print(b)
let b = bagOf("alive", true)  print(b)

Sets one field on a bag, replacing what was under the key. A bag holds up to 512 fields; past that this refuses rather than growing without end.

bagPut(newBag(), "hp", 30)
bagPut(newBag(), "name", "guard")
bagPut(newBag(), "alive", true)
bagPut(newBag(), "spot", myTile())
bagPut(newBag(), "stats", newBag())
bagPut(newBag(), "prices", range(0, 3))
bagPut(newBag(), "names", split("a,b", ","))
bagPut(newBag(), "route", path(myTile()))
bagPut(newBag(), "rows", bagList())

Removes one field from a bag. Removing a field that is not there does nothing, so it is safe to tidy unconditionally.

bagRemove(newBag(), "stale")

How many fields the bag holds right now.

print("fields", bagSize(newBag()))

The text stored under a key, or none when the key is missing or holds something that is not text.

if bagText(newBag(), "name") == none { print("unset") }

The text under a key, or the fallback when the key is missing or holds something else. Never none — the right shape for a readout.

print(bagTextOr(newBag(), "name", "?"))

The list of texts stored under a key, or an empty list when the key is missing or holds something else — so a for loop over it is always safe.

print(count(bagTexts(newBag(), "names")))

The tile stored under a key, or none when the key is missing or holds something that is not a tile.

if bagTile(newBag(), "spot") == none { print("unset") }

The list of tiles stored under a key, or an empty list when the key is missing or holds something else — so a for loop over it is always safe.

print(count(bagTiles(newBag(), "route")))

Empties a bag of every field, keeping the bag itself — every variable holding it now sees it empty.

bagWipe(newBag())

The rows whose field equals a value, in their original order, the input unchanged. A row without the field never matches.

print(count(bagsWhere(bagList(), "hp", 30)))
print(count(bagsWhere(bagList(), "name", "guard")))
print(count(bagsWhere(bagList(), "alive", true)))

The rows whose number under a key is at least the threshold, in their original order. A row without the column never matches.

print(count(bagsWhereAtLeast(bagList(), "lvl", 60)))

The rows whose number under a key is at most the threshold, in their original order. A row without the column never matches.

print(count(bagsWhereAtMost(bagList(), "lvl", 40)))

The rows whose field does NOT equal a value — including rows without the field at all. The complement of bagsWhere.

print(count(bagsWhereNot(bagList(), "hp", 30)))
print(count(bagsWhereNot(bagList(), "name", "guard")))
print(count(bagsWhereNot(bagList(), "alive", true)))

The rows whose number under a key is strictly over the threshold, in their original order. A row without the column never matches.

print(count(bagsWhereOver(bagList(), "hp", 50)))

The rows whose number under a key is strictly under the threshold, in their original order. A row without the column never matches.

print(count(bagsWhereUnder(bagList(), "hp", 10)))

A new bag with the same fields as this one. Shallow: a nested bag is shared, not copied — copy it too if you need it separate.

let b2 = copyBag(newBag())  print(b2)

The rows with later duplicates of a column removed — the first row with each value stays, in order. Rows without the column all count as sharing one blank value, so the first of those stays too.

print(count(distinctBagsBy(bagList(), "name")))

The FIRST row whose field equals a value, or none when no row matches — the table lookup, one call.

if findBag(bagList(), "hp", 30) == none { print("no row") }
if findBag(bagList(), "name", "guard") == none { print("no row") }
if findBag(bagList(), "alive", true) == none { print("no row") }

The row with the LARGEST number under a key — the leaderboard's top row. None when no row has the column. Ties answer the earliest row.

if maxBagBy(bagList(), "xp") == none { print("no rows") }

The average of a number column across the rows that have it, rounded toward zero. None when no row has the column.

print(meanBags(bagList(), "hp"))

A new bag holding both bags' fields; where both have a key, 'over' wins. Neither input is changed.

print(mergeBags(newBag(), bagOf("hp", 30)))

The row with the SMALLEST number under a key — the whole row, not the number. None when no row has the column. Ties answer the earliest row.

if minBagBy(bagList(), "hp") == none { print("no rows") }

A fresh, empty bag — the script's own record. Give it fields with bagPut and read them back with the typed bag reads.

let b = newBag()  print(newBag(), b)

One column of a table as a list: every row's number under the key, rows without one skipped — feed it to sum, mean or sorted.

print(sum(pluckNumbers(bagList(), "hp")))

One column of a table as a list: every row's text under the key, rows without one skipped — the text partner of pluckNumbers.

print(count(pluckTexts(bagList(), "name")))

The rows ordered by a number column, smallest first, rows without the column last, the input unchanged. sortBagsByDesc turns it round.

print(count(sortBagsBy(bagList(), "hp")))

The rows ordered by a number column, largest first, rows without the column last, the input unchanged — the leaderboard order.

print(count(sortBagsByDesc(bagList(), "xp")))

The total of a number column across every row, rows without it counting 0 — the one-call table sum. Faults on overflow.

print(sumBags(bagList(), "xp"))

The bag as compact JSON: nested bags nest, lists map item by item, tiles become {"x", "y"} objects. Refuses a bag that holds itself. The other half of jsonToBag — save it with the store, or print it.

print(bagToJson(bagOf("hp", 30)))

The bag as indented JSON, for a person to read — the same shape bagToJson writes compactly.

print(bagToJsonPretty(bagOf("hp", 30)))

Every object in the array at the path as a bag — the one call that turns a JSON table into rows. Items that are not objects are skipped.

for row in jsonBags("{\"xs\": [{}]}", "xs") { print(bagSize(row)) }

How many items the array at the path holds, or how many fields the object does. None when the path leads nowhere or to a plain value.

print(jsonCount("{\"xs\": [1, 2]}", "xs"))

The text with JSON's escapes applied and quotes around it — for building a JSON string by hand without breaking on a quote in the data.

print(jsonEscape("he said \"hi\""))

The true or false at a path, or none when the path leads nowhere or the value is not a boolean.

print(jsonFlag("{\"ok\": true}", "ok"))

True when the path leads to a value, of any type, including null. False for unparseable text — this never faults.

if jsonHas("{\"a\": 1}", "a") { print("there") }

True when the path leads to an explicit null — which jsonHas counts as present and the typed reads answer none for. This is how the two are told apart.

if jsonIsNull("{\"a\": null}", "a") { print("null") }

True when the text parses as JSON at all — ask before reading a reply you do not trust.

if jsonIsValid("{}") { print("parses") }

One item of the array at the path, as its own JSON — feed it back to the json reads to go deeper. None when there is no such item.

print(jsonItem("{\"xs\": [5, 6]}", "xs", 1))

Every field name of the object at the path, in the document's order. Empty when the path leads anywhere else — safe to walk with for. A name holding a dot or bracket cannot go back into a path (they are the path's own punctuation); read such a document with jsonToBag instead.

for k in jsonKeys("{\"a\": 1}", "") { print(k) }

The same JSON with every needless space removed — the shape to save or send. Refuses text that is not JSON.

print(jsonMinify("{ \"a\": 1 }"))

The whole number at a path, or none when the path leads nowhere, the value is not a number, or it has a real fraction (12.0 is whole; 12.5 is not — use jsonNumberScaled for those).

print(jsonNumber("{\"hp\": 30}", "hp"))

The number at a path multiplied by 'scale' and rounded half-up — how a decimal crosses into a whole-number language. 12.5 at scale 100 is 1250. None when the path leads nowhere or is not a number; faults on overflow.

print(jsonNumberScaled("{\"gp\": 12.5}", "gp", 100))

Every whole number in the array at the path, in order, anything else in the array skipped. Empty when the path is not an array — safe to walk.

print(sum(jsonNumbers("{\"xs\": [1, 2]}", "xs")))

The same JSON indented for a person to read. Refuses text that is not JSON, with the line and column of the problem.

print(jsonPretty("{\"a\": 1}"))

The text at a path. A string answers itself, unquoted; any other value answers as its own JSON, so there is always something to print. None when the path leads nowhere.

print(jsonText("{\"name\": \"guard\"}", "name"))

Every item of the array at the path as text: strings themselves, everything else as its own JSON. Empty when the path is not an array.

for t in jsonTexts("{\"xs\": [\"a\"]}", "xs") { print(t) }

The whole document as a bag: nested objects become nested bags, arrays become the closest list the language has, nulls are skipped and decimal numbers are kept as text. None when the text is not a JSON object — parse once, then use the typed bag reads.

let b = jsonToBag("{\"hp\": 30}")  if b != none { print(bagNumberOr(b, "hp", 0)) }