This is currently just a draft and meant to be a request for comment. I'm looking for suggestions and feedback. Do y'all even think this is necessary? Have you found this syntax confusing when I've used it in the past?

Overview

What is Vizzy Textual Representation

Vizzy Textual Representation is a set of guidelines for representing vizzy expressions, instructions, and events in a way that is readable, unambiguous, and reflective of the visual appearance of the analogous elements. Vizzy Textual Representation is not meant to be a rigorously defined grammar, nor a parseable syntax appropriate for machine translation to and from Vizzy.

Motivation

It is sometimes necessary to describe Vizzy instructions, events, and expressions in a text medium such as comments or in Discord chat. And while in some instances screenshots are a viable option they are often inconvenient in that one must create the expression in the Flight Program editor, and comments on this website cannot have images directly and instead must link to them. While pseudo code based on other syntaxes may suffice for some users, it can be confusing for individuals who are new
to programming and are unfamiliar with more traditional text syntaxes, such as function(arg1, arg2). Additionally, the SimpleRockets.com website introduces the additional, and annoying, limitation that ampersands and left angle brackets cannot be used without being incorrectly escaped has HTML entities. In order to strive to have a consistent and readable textual representation for Vizzy across platforms I have put together this draft guideline.

Guidelines

Expressions

Expressions are the most commonly described element of Vizzy. Visually they consist of a series of text elements, slots where other expressions or literal values can be nested, and drop down boxes.

• Expressions should be kept on a single line.
• The text of the expression should be exactly as it is in the visual representation.
• Any nested expressions or literal values (or empty slots for values) should be enclosed in a pair of square brackets.
• Any drop down box selections should be displayed in between a pair of vertical pipe characters.

In order to improve readability all simple infix or unary operators (+ - / * % ^ = != < <= > >= and or not) should drop the square brackets so long as the value is a literal.

Any slot represented by a pair of square brackets may or may not be padded with whitespace for readability, however, slots containing text should not be padded unless that whitespace is meant to be part of the text value.

Note: the selection of square brackets as opposed to the more conventional parentheses was made out of a desire to avoid the ambiguity with the vector literal syntax (1, 2, 3), and to avoid the impression that function syntax is being used in cases like length of and join.

Examples

• Basic Arithmetic: 1 + 2
• Complex Arithmetic: [1 / 2.718] ^ [2743 % 73]
• Expression With Dropdown: |abs| of [-3.14159]
• Varargs Expression: join [foo] [ ] [bar] []

Literal Values

In Vizzy literal values can be used to represent text, vectors, numbers. In Vizzy Textual Representation. In order to avoid confusion regarding the use of quotes, all literal values should appear in Vizzy Textual Representation exactly as they do in the visual representation. This may lead to some ambiguity, for example boolean literal values would appear in Vizzy Textual Representation exactly the same as the text literals true or false, and if a text literal happened to be valid Vizzy Textual Representation it would be impossible to know that it was meant to represent a text literal and not a nested Vizzy expression.

Variables

In order to avoid the ambiguity between a text literal and a variable, variables should be prefixed with a dollar sign. This should look familiar to individuals with a passing knowledge of a variety of programing and scripting languages, and since it is not actually possible to put a $ in a variable name, should not create any confusion about with that variable name actually is.

Examples

• [1 / $e] ^ [10.5 * 4]
• join [Hello, ] [$name] []

Instructions

Simple instructions follow pretty much the same syntax rules as expressions, except that they should always start at the beginning of the line, and should be prefixed with a greater than symbol followed by a space.

Block instructions such as if blocks or while loops should also start with a vertical pipe, and their child expressions should be indented by two spaces.

Examples

Simple Instructions

• Stage Activation: > activate stage
• Set Pitch: > set craft |Pitch| to [22.5]

Block Instructions

If/Else If/Else

> if [ [nav |Pitch|] > 5 ] then
>   display [Up]
> else if [ [nav |Pitch|] < -5 ] then
>   display [Down]
> else
>   display [Level]

For

> for $i from [10] to [1] by [-1]
>   display [ join [T-] [$i] ]
>   wait [1] seconds
>   if [$abort] then
>     break

Comments

Comments are self explanatory, they start with a pound sign and a space.

# This is an example of a comment.

Events

To help make it obvious when a series of instructions is meant to be attached to an event, events should be prefixed with a plus sign followed by a space.

Example

+ on $part exploded
> display [ join [part [$part] |Name|] [ has unfortunately exploded] [] ]