3. The binding

Contents of FBL 0.12

3.1 Overview

A binding declares how one format maps to a language's model. Every binding has the same parts:

{
  "title": "Timeline Markup Language",
  "claims": { "extensions": [".tml"], "origins": ["generic/timeline"] },
  "body": { "kind": "file", "family": "yaml" },
  "reader": "declared",
  "text": { "newline": "crlf", "indent": 2, "finalNewline": true },
  "header": { "key": "timeline", "value": 1 },
  "elements": [ … ],
  "relations": [ … ],
  "registration": { … },
  "template": { "text": "timeline: 1\r\nelements: []\r\n" }
}

Property	Type	Description
`title`, `doc`	LocalizedText, Doc	As in DISL.
`claims`	Claims	Required. Which files the binding takes (section 12).
`body`	Body	Required. A file of one family, or a folder (sections 4 and 10). (FBL 0.9) A body of the `grammar` family carries its grammar (section 4.9).
`reader`	`"declared"` or PluginReader	Required. `declared`: the rules of this binding read and write the body. A PluginReader: a persistence plugin does (section 11).
`readOnly`	bool or LocalizedText	The body is never written; a text is the reason a host shows.
`text`	TextDefaults	Conventions for new text where the body gives no evidence (section 6.3).
`header`	Header	A version or identity mark the body starts with (section 5.6).
`comment`	Regex	`lines` and `blocks`: a line that matches it is a comment (section 4.6).
`unmatched`	`"keep"` (default), `"report"`	`lines`, `blocks` and `bullets`: whether a statement no rule matches is also reported (section 7.4).
`blocks`	BlockRule[]	`blocks`: statements that open blocks and produce nothing (section 4.7).
`sections`	SectionRule[]	(FBL 0.7) `bullets`: the headings whose list items the rules read (section 4.8).
`elements`	ElementRule[]	Rules producing elements (section 5).
`relations`	RelationRule[]	Rules producing relations (section 5.4).
`registration`	RegistrationSettings	What the binding adds to the registration (section 8).
`template`	Template	The bytes of a new body (section 13).

A declared binding MUST have at least one element or relation rule. A binding with a plugin reader has no rules; its model is what the plugin reads.

3.2 The body

Property	Type	Description
`kind`	`"file"`, `"folder"`	Required.
`family`	`"yaml"`, `"json"`, `"xml"`, `"lines"`, `"blocks"`, (FBL 0.7) `"bullets"`, (FBL 0.9) `"grammar"`	Required for a declared file body: the family whose lossless reading the rules address (section 4).
`grammar`	string or `{file}`	(FBL 0.9) Required for, and only for, the `grammar` family: the grammar that reads the body, in ATD grammar notation, as its text or as the name of a file beside the FBL document (section 4.9).
`start`	Name	(FBL 0.9) `grammar`: the grammar's start rule. Default `start`.
`recover`	`{unit, sync}`	(FBL 0.9) `grammar`: read a body that does not parse in part, unit by unit, skipping to a synchronising token (section 4.9). Absent: a body that does not parse is unreadable (section 7.5).
`alsoRead`	family[]	Other families accepted for the same body. The host tries `family` first, then each of these in order, and uses the first under which the body is readable. A document read under another family keeps that family for writing.
`recognise`, `files`, `ignore`, `settle`		Folder bodies only (section 10).

3.3 The one-place rule

A value that can be written back MUST be bound to exactly one place in the body: a key, an XML attribute, the text of an element, a named group of a line, or a word of a group (section 5.2). A value bound only through CEL (value) is read-only. This is what makes write-back defined: FBL never inverts an expression.

3.4 Read-only bindings and rules

A binding with readOnly is never written: the host offers no gesture that changes the model, and says why when the user tries. A rule or an attribute binding with readOnly is read and never written; a gesture that would change it is refused with the rule's reason, or a host-chosen one when readOnly is true. Elements that DISL derives (DISL §4.11) are never written either.