meta.org

Meta

This file uses newline-delimited JSON encoding. Non-JSON lines can be ignored, so you can interpret this file directly without extracting json blocks first.

Meta’s data model is much simpler, though, so we won’t need full power of JSON. Meta file is a set of 4-tuples [rowId, element, attribute, value].

Elements and attributes are referenced by ids. What’s more, attributes are elements, so they live in the same namespace.

Values are opaque bytes. Unless you know what they represents, you can’t do anything useful about them.

Core

Now, let’s create our first element (attribute).

The next line assigns attribute 0 of element 0 to be “identifier”. In other words, we just assigned identifier “identifier” to itself.

["0", "0", "identifier"]

(identifier(0).identifier(0) = "identifier")

Next, let’s create another attribute.

["1", "0", "attribute/value-type"]

(~attribute/value-type(1).identifier(0) = “attribute/value-type”)

attribute/value-type is an attribute that specifies type of values of attribute.

Do you remember that values are actually opaque byte blobs? This attribute should help you distinguish them.

So far we have only used one value type—string. Let’s define it.

["2", "0", "String"]

(String(2).identifier(0) = "String")

Now we can assign String type to identifier attribute. In other words, we say that identifiers are strings.

["0", "1", "2"]

(identifier(0).attribute/value-type(1) = String(2))

oh well, we just used another attribute type-reference! Let’s define it.

["3", "0", "Reference"]

(Reference(3).identifier(0) = "Reference")

and assign attribute/value-type attribute its proper value-type

["1", "1", "3"]

(attribute/value-type(1).attribute/value-type(1) = Reference(3))

We’re done?

We have defined a number of attributes that can define further attributes. From now on the system can define itself.

Annotator

All these ["1", "1", "3"] are not exactly easy to read. Let’s build a tool to help us!

See ./meta-query/ directory for such a tool.

When invoked with meta.org --annotate-file, it prints all Meta rows along with a more human-readable annotation:

$ meta-query/index.js meta.org --annotate-file --only-meta
;; ["0", "0", "identifier"]  //=> identifier(0).identifier(0) = "identifier"
;; ["1", "0", "attribute/value-type"]  //=> attribute/value-type(1).identifier(0) = "attribute/value-type"
;; ["2", "0", "String"]  //=> String(2).identifier(0) = "String"
;; ["0", "1", "2"]  //=> identifier(0).attribute/value-type(1) = String(2)
;; ["3", "0", "Reference"]  //=> Reference(3).identifier(0) = "Reference"
;; ["1", "1", "3"]  //=> attribute/value-type(1).attribute/value-type(1) = Reference(3)

Documentation

Let’s add documentation.

["4", "0", "comment"]
["4", "1", "2"]
["4", "4", "Comment attribute. Can be attached to any element to describe its meaning and add useful notes."]

["0", "4", "Identifier is a human-friendly name of the element. Usually assumed to be unique, so you could find element by its identifier."]
["1", "4", "Type of the attribute values."]
["2", "4", "String value must be a valid UTF-8–encoded string."]
["3", "4", "Reference value is an id of another element."]