Skip to content
Source on GitHubVisitors

5. Files and descriptions

Contents of ATD 0.1

5.1 The header and the tool construct

Every .atd file MUST start with the header atd <major>.<minor>, the version of ATD it is written in. It is the one construct every version of the grammar keeps (section 18).

A root file follows its header with the tool construct, which names the kind, the origin and the version of the tool type and holds its members:

atd 0.1
diagram freeplane/mindmap version "1.4.0" {
  label "Mind map"
  …
}
  • The kind is diagram, designer or editor, and decides which constructs the description may hold (section 14.4).
  • The origin is the tool type's <vendor>/<type> (DISL's and DESL's language.origin). A description of a tool type that has a .dis or .des MUST have its origin, and its label MUST be its display name (FR-025).
  • version is the tool type's semantic version (DISL's language.version).
  • The members are the constructs of sections 7 to 13, in any order; their order is kept (section 16).

5.2 Parts

A description MAY be split over several files (FR-012). One is its root; each other is a part, which follows its header with part of <origin> and holds members as the tool construct does, without braces:

atd 0.1
part of freeplane/mindmap

notation { … }
layout { … }

A part's members are members of the description. A part MUST name the origin of the root that imports it (ATD2007), and MUST NOT be imported by two roots (ATD2008).

5.3 Imports

  • import "<path>" in a root or a part takes the part at <path> into the description. The path is relative to the importing file and MUST stay within the description's folder (ATD2009 otherwise, as for a file that is not there).
  • Imports MAY form any graph; a cycle among them is reported once, at the import that closes it as the files are visited from the root in the order of their imports (ATD2003), and the description is still checked.
  • import "<path>" as <name> takes another tool description as a library, as DISL §3.3's imports do: its element types, functions and other declarations are visible prefixed with <name>.. Its settings are DISL's Import (version, include, integrity).

5.4 Versions

A reader MUST read the header before anything else and select the grammar of the version it declares. A version it does not know is refused with a finding that names both versions (ATD0001), never read as the nearest one it knows. A description is checked with the grammar and the rules of the version it declares, so a keyword a later version adds never reaches an earlier file.

5.5 The abstract tree

A reader lowers what it parses into the abstract tree of atd.schema.json#/$defs/Tree, which atd tree prints: per file, its version and its tool or part, each construct a node with its kind, its span (section 3.1), its name, its doc and its fields, each value as section 6.6 says and each expression with CEL's abstract syntax. The abstract tree is not an interchange form (FR-030): nothing reads it back as a description, and the .atd text is normative.

Referenced from