Command language

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

The dyna3 command language will provide a text-based way to interact with assemblies, parallel to the graphical interface. A mostly-commutative fragment of it will also be used to serialize assemblies. Here are some ideas about how it might be designed, partly developed in conversation with members of @Vectornaut's game development group.

Design

Goals

Quick and comfortable to use during interactive sessions.
Low barrier to getting started; designed for learning by doing.

Refinement

Questions

What should composition look like?
Occasionally worth asking: what should the abstract syntax tree look like?

Comparisons

Syntax

Principles

Commands have verbs. Each command should contain an implicit or explicit verb. It should be easy to learn to look at a command and see what the verb is.
Creation by presumption. A command that presumes the existence of an element or regulator should create that element or regulator, as long as it’s specified unambiguously and it doesn’t exist already.

Approaches to design goals

Quick and comfortable to use during interactive sessions

Minimal punctuation.
Terse command names.

Low barrier to getting started; designed for learning by doing

Lots of context help.
GUI interactions made visible as commands?
Clear command names.

Context help

Design considerations

How much can you disambiguate based on prefixes?
Partial expression parsing is crucial. There are many options!
- Focus on the last word.
- Build a partial syntax tree with markers for missing data.
- Come up with multiple continuation options.

Thoughts

Sphere
| Explanation of creation attributes

Angle a b
| Add regulator: Angle a b
| Set regulator: Angle a b @ [value]
| Unset regulator: Angle a b @ unset

Thoughts

Elements

Creating elements

Sphere

Create a sphere with default parameters and a default ID. The verb in this command is implicit: “[let there be] a sphere.” We can think of this as copula omission. Creating a sphere through the graphical interface should have the same result.

Observables and regulators

Referring to regulators

Given two elements a and b, we can refer to the angle between them as Angle a b. If the angle is being regulated, we can refer to the regulator in the same way.

We could make regulator references more visually coherent, and help distinguish them from identifiers, by requiring parentheses: Angle(a b). This would be especially helpful for observables with short names, like an X observable for the x coordinate of a point. In an expression like X a, the observable and the element are visually similar. The form X(a) makes it clear that X is a regulator.

Creating regulators

Syntax options

Angle a b

regulate Angle a b

Create a regulator for the angle between elements a and b. The implicit copula option is shorter, and more analogous to how you create an element, but it might introduce confusion about whether we’re referring to an observable or a regulator. The option with the explicit verb regulate makes it more clear that we’re referring to a regulator.

Angle a Sphere

By the creation by presumption principle, this should create a regulator for the angle between the element a and a new sphere.

Manipulating observables

Angle a b ~ 30

Push the angle between a and b toward 30°. This is analogous to the manipulations you might do by dragging elements in the display. It doesn’t create a regulator, because it’s referring to Angle a b as an observable.

Setting regulators

Angle a b @ 30

Set the regulator for the angle between a and b to 30°, creating the regulator if it doesn’t already exist.

Syntax options

unset Angle a b

Angle a b @ unset

Unset the regulator for the angle between a and b. The option with unset afterward might be more discoverable through context help.

Identifiers

Assigning identifiers

Syntax options

a is Sphere

Sphere named a

Create a sphere, as described above, and set its identifier to a. The is option follows the strong tradition of putting identifiers on the left, but the named option might work better with an interactive help system.

Syntax options

r is Angle a b

Angle a b named r

Assign the identifier r to the regulator for the angle between a and b, creating the regulator if it doesn’t exist already.

Syntax options

a is c

c named a

Assign the a new identifier, a, to the object with the identifier c.

Nesting identifier assignments

Syntax options

r is Angle a b is Sphere

Angle a Sphere named b named r

It seems like this should assign the identifier r to the angle between a and a new sphere with identifier b. Readability is very poor for both versions! Suggestions:

If the language has both statements and expressions, is could be a statement, and thus syntactically inadmissible for nesting.
If the language is purely expression-based:
- An is expression could return unit, making it semantically inadmissible for nesting.
- An is expression could require punctuation for nesting.

Composition

Broad ideas

To accommodate a flexible verb list, we'll almost certainly need some kind of separators to specify the tree structure. Polish notation won't cut it.
- Parentheses are a standard option
- Tcl uses newlines and semicolons to separate commands, whitespace to separate words within commands, and double quotes and curly braces for grouping
Typically, parser generators can only handle the parts of the syntax that can be turned into parse tables at compile time.

Creation attributes

When creating an entity, one might want to elaborate on it by adjusting its parameters, manipulating related observables, or creating and setting related regulators. One way to do that would be through extra commands that are bundled together with the creation command, and which use the creation command as context. For example, the following might be equivalent:

s is Sphere
  color = orange
  Radius @ 2
t is Sphere
  color = purple
  Radius @ 3
  Angle s @ unset

s is Sphere: color = orange, Radius @ 2
t is Sphere: color = purple, Radius @ 3, Angle s @ unset

s is Sphere
s.color = orange
Radius s @ 2
t is Sphere
t.color = purple
Radius t @ 3
Angle s t @ unset

Default regulators might be implemented as creation attributes, so that the following would be equivalent

Sphere

Sphere
  Radius @ unset

and the following would also be equivalent

Point

Point
  X @ unset
  Y @ unset
  Z @ unset

A boolean attribute called bare could be used to create an element without its default regulators.

Sphere
  bare