Skip to content

Latest commit

 

History

History
248 lines (206 loc) · 5.3 KB

README.md

File metadata and controls

248 lines (206 loc) · 5.3 KB
Raw

zzz

Simple and boring human readable data format for Zig.

zzz syntax describes a tree of strings. It has little syntactic noise and is really easy to implement. The spec does not force any specific rules for escaping or number parsing by design. Nodes in the tree are string slices.

zzz's focus is to be a simple and lightweight format. This library implements two trees: a static tree which has zero allocations, and a dynamic tree which manages slice and node allocations. Here's an example using the static tree:

// 100 is the max number of nodes.
var tree = zzz.StaticTree(100){};
try zzz.appendText(&tree, "foo:bar");
// There is always a root, and its value is empty.
assert(tree.root.value == "");
assert(tree.root.findNthChild(0, "foo") != null);
assert(tree.root.findNthDescendant(0, "bar") != null);
// Print the tree to standard out.
tree.root.show();

Note: This implementation is being iterated on while I use this for another project. API stability isn't a guarantee quite yet, and will also be subject to changes as Zig changes.

Use-cases

  • Configuration files
  • Game object descriptions
  • Embedded devices
  • Simple serialization format

Quick example

D&D Kobold stat block. Raw text here.

(YAML highlighting used)

# Comments begin with a hash symbol.

# : describes a parent child relationship
name: Kobold

# , describes a sibling relationship
tags: small, humanoid, lawful evil
armor class: 12

# : can appear on the same line, here "(2d6 - 2)" is a child of "5"
hit points: 5 : (2d6 - 2)

# This can be used for meta tagging
speed: 30 : ft

# Continuing on a newline. The indentation is exactly 2 spaces to describe a parent/child relationship
stats:
  str: 7: -2
  dex: 15: 2
  con: 9: -1
  int: 8: -1
  wis: 7: -2
  cha: 8: -1

# ; is used to go up in the tree. Here we ascend up from the "ft" node
senses: darkvision:60:ft;; passive perception:8
languages: common, draconic
challenge: 1/8

# Multline strings follow the same rules as Lua's. The first newline on an empty line is skipped
abilities:
  sunlight sensitivity: [[
While in sunlight, the kobold has disadvantage on attack
rolls, as well as on Wisdom (Perception) checks that rely on sight.]]
  pack tactics: [[
The kobold has advantage on an attack roll against a
creature if at least one of the kobold's allies is within
5 feet of the creature and the ally isn't incapacitated.]]

JSON example

Translated from http://www.json.org/example.html

menu:
  id: file
  value: File
  popup:
    menuitem:
      : value: New
        onclick: CreateNewDoc()
      : value: Open
        onclick: OpenDoc()
      : value: Close
        oneclick: CloseDoc()
{"menu": {
  "id": "file",
  "value": "File",
  "popup": {
    "menuitem": [
      {"value": "New", "onclick": "CreateNewDoc()"},
      {"value": "Open", "onclick": "OpenDoc()"},
      {"value": "Close", "onclick": "CloseDoc()"}
    ]
  }
}}

Building & examples

For more examples see the source comments and tests.

zig build test

zig build examples

Other languages

Syntax highlighting

Spec

zzz text describes a tree of strings. Special characters (and spaces) are used to go up and down the tree. The tree has an implicit empty root node.

Descending the tree:

grandparent:parent:child:grandchild

Output:

null -> "grandparent" -> "parent" -> "child" -> "grandchild"

Traversing the children of root (siblings):

sibling1,sibling2,sibling3

Output:

null -> "sibling1"
     -> "sibling2"
     -> "sibling3"

Going up to the parent:

parent:child;anotherparent

Output:

null -> "parent" -> "child"
     -> "anotherparent"

White space and newlines are significant. A newline will take you back to the root:

parent:child
anotherparent

Output:

null -> "parent" -> "child"
     -> "anotherparent"

Exactly two spaces are used to to go down a level in the tree:

parent:child
  sibling

Output:

null -> "parent" -> "child"
                 -> "sibling"

You can only go one level deeper than the previous line's depth. Anything more is an error:

parent:child
    sibling

Output:

Error!

Trailing commas, semicolons, and colons are optional. So the above (correct one) can be written as:

parent
  child
  sibling

Output:

null -> "parent" -> "child"
                 -> "sibling"

Strings are trimmed:

parent:     child:      grand child      ;

Output:

null -> "parent" -> "child" -> "grand child"

Strings can be quoted with double quotes, single quotes, or Lua strings:

"parent":[[ child ]]:[==[grand child]=]]==]:'great grand child'

Output:

null -> "parent" -> " child " -> "grand child]=]" -> "great grand child"

Lua strings will skip the first newline if it's empty:

[[
some text]]

Output:

null -> "some text"

Strings are not escaped and taken as-is.

"\n\t\r"

Output:

null -> "\n\t\r"

Comments begin with # and run up to the end of the line. Their indentation follows the same rules as nodes.

# A comment
a node
  # Another comment
  a child

Output:

null -> "a node" -> "a child"