This is a scratch space for drafting updates to the command language guide. Once an update is stable and polished enough, it should be committed to the project repository.

The dyna3 command language

Overview

The dyna3 command language provides a text-based way to interact with assemblies, parallel to the graphical interface. A mostly-commutative fragment of it is also used to serialize assemblies.

This guide is meant to serve as both an introduction to the language and a reference that describes its current state of implementation. The language is a work in progress, and it may change substantially as it grows.

Since the language is built for interacting with assemblies, its features are often easiest to describe in the context of an assembly. We'll use the example assemblies that come with dyna3 for this purpose.

How-to

Referring to things

Concepts

A descriptor is an expression you use to refer to something you want to interact with, such as:

• A part of the assembly—an element or a regulator.
• An attribute of an element, like its label or its color.
• A part of dyna3, like a constraint-solving engine.

There are two ways a descriptor can refer to something:

• Directly, using the referent's assigned identifier.
• Indirectly, using the referent's type and enough additional information to specify it.

Examples

Here are some descriptors that are valid in the context of the "General" example assembly.

Descriptor	Mode	Referent's type…	and specification
ursa_major	Direct	The element (in this case, a sphere)…	with identifier ursa_major
HalfCurvature ursa_major	Indirect	The regulator of the half-curvature…	of ursa_major
InversiveDistance ursa_major ursa_minor	Indirect	The regulator of the inversive distance…	between ursa_major and ursa_minor
Color ursa_major	Indirect	The color…	of ursa_major
Engine "Inversive 0.1"	Indirect	The constraint-solving engine…	with version string "Inversive 0.1"

Syntax

Syntactically, a descriptor consists of a head followed optionally by a space-separated list of arguments.

• In a direct descriptor, the head is the referent's identifer, and there are no arguments.
• In an indirect descriptor, the head is the referent's type, and the arguments, if needed, provide additional specifying information.

As the examples show, the arguments of an indirect descriptor are often other descriptors. An argument that contains spaces must be enclosed in parentheses to show that all of its space-separated terms go together.

Creating things

Concepts

The command language doesn't have any explicit verbs for creating things. To create something, you just make a statement that presumes its existence. This language feature might be called "creation by presumption."

Examples

• In a new assembly, the statement

  Sphere
  

  creates a sphere, with the default identifier sphere1 and default values for its label, color, and other attributes.

• In the "General" example assembly, the statement

  InversiveDistance ursa_major ursa_minor
  

  creates a regulator that governs the inversive distance between ursa_major and ursa_minor. Subsequent uses of this statement will refer to the existing regulator rather than creating a new one.

• In the "General" example assembly, the statement

  InversiveDistance ursa_major Sphere
  

  creates a sphere and a regulator that governs its inversive distance from ursa_major. Each subsequent use of this statement will create an additional sphere with its own associated inversive distance regulator.

Assigning identifiers

Concepts

Every element comes with an identifier: an associated string that identifies it uniquely.

Examples

• In a new assembly, the statement

  strawberry is Sphere
  

  creates a sphere with the identifier strawberry.

• In the "General" example assembly, the statement

  big_bear is ursa_major
  

  assigns the new identifier big_bear to the existing sphere ursa_major.

Syntax

To be added

Default identifiers

Every type of element comes with a series of default identifiers, which consist of a type string followed by a sequence number. For example, the default identifiers for spheres are sphere1, sphere2, sphere3, and so on. When you create an element without assigning it an identifier, it gets the first default identifier that's not in use already.

Working with regulators

Concepts

A regulator operation is a statement you use to manipulate a regulator. There's only one so far: the set operation, denoted @, which is used to constrain or release the regulated quantity.

Examples

• In the "Radius ratio" example assembly, the statement

  InversiveDistance v1 v3 @ -2
  

  constrains the inversive distance between the points v1 and v3 to be -2.

• In the "General" example assembly, the statement

  InversiveDistance gemini_a gemini_b @ 0.5
  

  sets the inversive distance between the sphres gemini_a and gemini_b to 1/2. Since the assembly doesn't have a regulator for this inversive distance, the statement creates one by presumption.

Assigning attributes

Concepts

An attribute assignment is a statement you use to set the value of an attribute, like an element's label or color. The attribute assignment operator is denoted =.

Examples

• In the "General" example assembly, the statement

  Label ursa_major = "Big bear"
  

  changes the label of the sphere ursa_major from "Ursa major" to "Big bear".

• In the "General" example assembly, the statement

  Color ursa_major = 0.5 0.0 0.75
  

  changes the color of the sphere ursa_major from electric purple to plum.

Syntax

To be added

Consolidating statements

Concepts

When you want to make several different statements about the same thing, it's often helpful to make all those statements in the same breath. The command language uses detailed descriptors to make this possible.

Examples

• In the loading script for the "General" example assembly, the statement

  ursa_major is Sphere:
    Label = "Ursa major",
    Color = 0.25 0 1,
  

  creates a sphere, gives it an identifier, and sets its label and color.

• In the loading script for the "Radius ratio" example assembly, the statement

  f1:
    HalfCurvature @ 0,
    InversiveDistance v2 @ 0,
    InversiveDistance v3 @ 0,
    InversiveDistance v4 @ 0,
  

  constrains the sphere f1 to be a plane that passes through the points v2, v3, v4.

• In the "General" example assembly, the statement

  InversiveDistance ursa_major (peach is Point: Label = "Peach") @ 0
  

  creates a point, gives it an identifier, sets its label, and constrains it to lie on the sphere ursa_major.

Syntax

A detailed descriptor consists of a descriptor followed by a colon and then a comma-separated list of statements. The descriptor can optionally be preceded by an identifier assignment.

The statements that appear in a detailed descriptor are called details. The list of details is allowed to have a trailing comma, but the colon at the beginning of the list can't be trailing: a descriptor followed by a colon has to be followed by at least one detail.

To make detailed descriptors more readable, it's often helpful to use the command language's line continuation feature, as we do in some of the examples above. A newline usually indicates a break between statements, but a newline followed by at least one space or tab is treated as whitespace within a statement.