Managed Recs

Overview

The runtime configuration is stored as normal records in the Folio database with the special tag "rt". We call these managed records because they are used to manage the runtime itself. You can read these records using normal functions such as readAll(). However they cannot be written directly using commit(); instead you must use special functions respective to the record type.

There are five different record types represented by the rt tag enum:

• meta: exactly one record for the runtime meta
• lib: used to enable a Xeto lib for the namespace
• func: used to add a function in the companion lib
• spec: used to add a Xeto spec in the companion lib
• instance: used to add a Xeto instance in the companion lib

Each of these managed record types is discussed further below.

Meta

Every runtime has a metadata dict you can access in Fantom via Runtime.meta and in Axon via sysMeta() and projMeta(). System meta is used to configure the display name of the node in clustering. Project meta is used for the project's display name, steady configuration, etc. In the Haxall daemon there is just one combined system/project.

Runtime meta is stored via the rt:meta record:

rt: "meta"
dis: "My Project"
projMeta
version: "4.0.4"
steadyState: 5sec

Note that project meta has the tags projMeta and version which are managed by the system and should not be modified. Also note that your rt record does not define a name tag, but one is always inserted into the results of Runtime.meta or projMeta().

Lib

Records with the rt:lib tag are used to manage the Xeto libs enabled in the runtime's namespace. They always include the name tag with the library's dotted name string. Lib recs which map to an extension are used for the ext settings.

A rt:lib record looks like this:

rt: "lib"
name: "hx.bacnet"

The following Axon functions are used to manage your lib recs:

• libs(): list the status of enabled libs
• libAdd(): add one or more libs
• libRemove(): remove one or more libs
• extSettings(): read extension settings
• extSettingsUpdate(): modify extension settings

The following are the Fantom APIs:

• RuntimeLibs: add/remove libs
• Ext.settings: read settings

Companion Lib

Every project has a builtin Xeto lib named "proj" we call the companion library. This library is used to manage project specific specs, instances, and Axon functions. The representation of these managed recs is the AST or abstract syntax tree of the Xeto (versus the source format). This allows tools to construct and modify these records efficiently.

The following Axon functions are used to work with the companion lib managed recs:

• companionRead(): read by name
• companionAdd(): add new companion rec
• companionUpdate(): update existing companion rec
• companionRename(): rename companion rec
• companionRemove(): remove companion rec
• companionFunc(): parse an Axon function into its rec format
• companionParse(): parse Xeto source into rec format
• companionPrint(): print rec format back to Xeto

The following sections detail the managed rec AST format for each companion rec type.

Spec Companion Recs

You can use companionParse() to parse source code into the managed rec representation. The following tags are used:

• name: spec name in the companion lib
• base: ref to the base type
• spec: always @sys::Spec
• slots: grid of slot specs with name, type, and meta
• any other tags are spec meta

All type references such as base and type must be qualified refs such as @ph::Site.

Consider this Xeto spec:

// example spec
Person: Dict {
  dis: Str
  age: Number?
}

Would be represented as the following managed rec:

rt: "spec"
name: "Person"
base: @sys::Dict
doc: "example spec"
spec: @sys::Spec
slots: Zinc:
  ver:"3.0"
  name,type,maybe
  "dis",@sys::Str,
  "age",@sys::Number,M

Func Companion Recs

Func specs follow the same rules defined above for spec recs. However func recs are essentially slot specs merged into the sys::Funcs type using a synthetic mixin. Use the companionFunc() to parse an Axon function into its companion lib representation:

// axon expression
companionFunc("testAdd", "(a, b) => a + b")

// returns this managed rec representation
rt: "func"
name: "testAdd"
axon: "(a, b) => a + b"
base: @sys::Func
spec: @sys::Spec
slots:Zinc:
  ver:"3.0"
  name,type,maybe
  "a",@sys::Obj,M
  "b",@sys::Obj,M
  "returns",@sys::Obj,M

Instance Companion Recs

Instance managed recs are just normal data records that are added to the companion lib for applications which only work with Xeto lib data such as the Ion UI.

// axon expression
companionParse("""@my-site: Site { dis:"My Site" }""")

// return this managed rec
rt: "instance"
name: "my-site"
dis: "My Site"
spec: @ph::Site