Mindcode 3.0

[cardillan]

Mindcode 3.0 is planned for release in a few weeks. To make the transition easier, please make sure your Mindcode compiles under the strict syntax, which is the default.

Mindcode 3.0

Version 3.0 comes with an updated compiler containing many components that were rewritten completely from scratch. These components include grammar definition, parser and code generator - optimizations were largely unaffected by the rewrite. Code which compiled under the strict (the default) syntax of Mindcode 2.5.0 or later will compile in the version 3.0 as well and should produce the same result (the generated code and execution timing may be different).

New features

The rewritten compiler brings these new features and changes:

• Support for string interpolation: print($"Sum: ${a + b}.");. Any expression, including e.g. function calls, can be used in the curly braces. Enhanced comments have the same capabilities: /// Sum: ${a + b}.
• Support for color literals in the form of %rrggbb or %rrggbbaa, e.g. %ff0000 is bright red.
• Prefix and postfix increment/decrement operators: total++ or --limit, for example.
• All constructs that expect a body of statements now accept an empty body as well: void foo() end;, or do while @time < endTime;.
• Unary plus/minus operators are fully supported.
• Properties and methods can be invoked on expressions:
  • type = getlink(index).@type
  • getlink(index++).enabled = false;
  • getMessageBlock().printflush()
• Support for code blocks (delimited by begin and end).
• The loop keyword in do loop while loops is optional. The keyword will be deprecated and eventually dropped.
• Special types of variables (external variables and properties) can be used in the same way as normal variables, e.g. as function output arguments.
• Better reporting of errors and warnings produced during compilation.
  • The compiler now reports errors and warnings that occur in unused functions as well.
• New mechanism of mlog variable names generation.

New experimental features

• Variables can be explicitly declared, with optional additional functionality:
  • declared linked blocks can have guard code automatically generated,
  • declared external variables can be cached.
• Newly defined strict and relaxed syntax modes.

Breaking changes

A new system of selecting Mindustry Logic version targets was adopted.

Removed features

Mindcode 3.0 removed most of the features which were deprecated in previous versions of Mindcode. As a result, the following elements of Mindcode syntax are no longer supported:

• Kebab-case identifiers for variables and functions.
• Escaped double quotes in string literals.
• Using parentheses around the list of values in list iteration loops.
• The printf() function in Mindustry Logic 7 language target.
• Using global variables for program parametrization.
• All features of Mindcode 2.x relaxed syntax mode.

The relaxed syntax mode in Mindcode 2.x defined some language elements as optional. All these elements are no longer optional and must be always specified:

• semicolons after each statement,
• the @ prefix for Mindustry built-in variables used as properties (e.g. vault1.@coal instead of vault1.coal),
• the out modifier when passing an output argument to a Mindustry Logic built-in function,
• the do keyword in loops,
• the then keyword in if and case expressions.

Promoted experimental features

The following features are no longer considered experimental:

• Support for Mindustry Logic 8.
• The system library.
• The require keyword and --append command-line argument for adding a system library or another external file to the compiled code.
• Output and input/output arguments of user defined functions.
• Vararg (variable arity) functions.
• Function overloading.
• The mlog and mlogSafe functions for creating custom instructions.
• Multiple iterators and output iterators in list iteration loops.
• Formattable string literals.
• Enhanced comments.
• The sort-variables compiler directive
• All existing optimizations available on experimental level:
  • If Expression Optimization: instruction propagation (now available on advanced level)
  • Single Step Elimination: removing of jumps identical to the previous jump if the control flow and jump condition remains unchanged (now available on advanced level)
  • Print Merging Optimization: merging print output using the format instruction when compiling for Mindustry Logic 8 (now available on basic level)
  • Data Flow Optimization: full optimization of global variables (now available on basic/advanced level)
• Built-in processor emulator.
• Generating Mindcode signature at the end of the compiled program.

New features

Selected new features are described in greater detail here.

Mindustry Logic versioning

Mindcode uses the target directive and command-line option to specify which version of Mindustry Logic and Mindcode syntax to use when compiling source code. A new system for specifying these targets was adopted.

The target versions consist of a major and minor version number. As of now, these versions exist:

Version	Description
6.0	Mindustry Logic for the latest release of Mindustry 6.
7.0	Mindustry Logic for the latest release of Mindustry 7.
7.1	As above, with slightly revised syntax of some functions.
8.0	Mindustry Logic for the latest BE release of future Mindustry 8.

Version 8.0 will be the version corresponding to the official Mindustry 8 release. Possible further enhancements of Mindustry 8 or, possibly, of the Mindcode language will be incorporated as separate versions with updated minor version number.

The target can be set using either just a major, or both major and minor version numbers. When specifying both numbers, the specified version is used. When specifying just the major version, the most recent minor version in given major category is used. Example:

#set target = 7;        // Sets version 7.1
#set target = 7.0;      // Sets version 7.0

To use a world-processor variant of Mindcode language, it is necessary to add W as a suffix to the version number:

#set target = 8W;     // World-processor logic version 8
#set target = 7.0W    // World-processor logic version 7.0

The same names of version targets is used with the -t / --target command-line option.

Syntax modes

Mindcode 3.0 again supports a strict and relaxed syntax modes, but they work different from strict and relaxed syntax modes in Mindcode 2.x.

Relaxed syntax is the default one in Mindcode 3.0. Code which compiled under strict syntax in 2.X (which was the default one in 2.x) compiles under the relaxed syntax in Mindcode 3.0.

Relaxed syntax

Relaxed syntax is useful for shorter scripts, as it requires less boilerplate code.

• Code in global scope. It is permissible to place executable code outside a code block (e.g. print("Hello!"); printflush(message1); is a valid source code).
• Implicit variables. Variable declaration is optional. When variables aren't declared, they can be used freely in the source code and their scope is determined by naming convention. The naming convention rules are the same as in the previous Mindcode versions:
  • Linked blocks: if the variable name corresponds to a known linked block, it is automatically regarded as a linked block reference and is implicitly global (e.g. cell1 or switch2).
  • External variables: if the variable name starts with the $ prefix, the variable is external. A place in the heap is assigned to the variable, and the variable is implicitly global.
  • Global variables: if the variable name doesn't contain lowercase characters, the variable is global (e.g. COUNT) and is accessible from all code blocks and functions.
  • Local variables: if the variable name contains at least one lowercase character, the variable is either local (defined for the entire function, if used within a function) or main (defined for all code outside any function).

Strict syntax

Note

Strict syntax is currently an experimental feature and its rules might still change.

Strict syntax is useful for larger projects, as it enforces additional rules designed to make source code more maintainable. Code adhering to the strict syntax produces the same output when compiled under the relaxed syntax as when compiled under the strict syntax.

• No code in global scope. Only declarations are allowed in the global scope. All code must be enclosed either in a code block (i.e. between the begin and end keywords), or in a function.
• Explicit variables. All variables must be declared before being used, even variables representing linked blocks. The variables are valid in the code block in which they were declared. There are two exception to the requirement of explicit variable declarations:
  • Linked blocks used as arguments in the param declarations do not need to be declared separately (e.g. param message = message1; does not require linked message1; to be declared beforehand). These linked blocks can then be accessed in code only via the parameter (message in this case), not the linked block itself (message1 would not be recognized in later code unless explicitly declared).
  • Similarly, linked blocks used in allocate heap / allocate stack declarations do not need to be separately declared (e.g. allocate heap in cell1 does not require linked cell1 to be declared beforehand). Linked blocks used in allocate declarations cannot be accessed directly, and the specified linked block (cell1 in this case) would not be recognized in later code unless explicitly declared.

The requirement to declare variables explicitly helps with spotting misspelled variable names, as unknown variable names cause compilation errors, as well as helping identify some cases when a single variable is used for multiple different purposes, as repeated variable declaration also causes compilation errors.

Mixed syntax

To help with a transition of relaxed syntax code to the strict standard, a third mixed syntax mode is available. In this mode, code is compiled under the relaxed syntax, but all violations of the strict syntax rules are reported as warnings.

Code blocks

Code block is a sequence of expressions or statements enclosed in a larger syntactic element. Code blocks can be nested. For example:

if condition then
    // This is a code block
    print("true");
else
    // Another code block
    while true do
        // Nested code block
        print("false");
    end;
end;

Mindcode now also provides an explicit code block:

begin
    // This is a code block
end; 

Code block defined at the topmost level is called 'main code block' and contains the main program code. At this moment more than one code block is allowed, and in a compiled program the code from the main code block(s) is executed. In strict syntax mode (see below), all executable code must be placed either in a main code block, or in a function:

#set syntax = strict;

print("Hello");       // Error: code outside a main code block is not allowed in sctrict mode

begin
    print("Hello");   // OK
end;

In relaxed mode, an implicit main code block is created containing all executable code.

Variable declarations

The following types of variables now can be explicitly declared:

• regular variables,
• external variables,
• linked variables.

Note

Variables created using a declaration are called 'explicit' or 'declared' variables. Variables used in the code without prior declaration are called 'implicit' variables.

Unlike implicit variables, the declared variables are valid in the scope they're declared in: global, main or local. Global variables are accessible from anywhere in the program, main and local variables from the code block they're declared in. It is possible to use names corresponding to linked blocks (e.g. wave1) for declared variables.

When a main or local variable has the same name as a global variable, the global variable is hidden and cannot be accessed in the corresponding code block.

Regular variables

Regular variables are declared using this syntax:

[noinit] [volatile] var <variable1> [= <initial value>] [, <variable2> [= <initial value>] ... ];

When declaring global variables, these additional modifiers can be used:

• noinit: this modifier suppresses the "uninitialized variable" warning for the declared variable. Uninitialized global variables retain the last value assigned to them in the last iteration of the program. This modifier cannot be used if the variable is assigned an initial value.
• volatile: the compiler assumes that volatile variables can be changed externally and handles them correspondingly. The only known mechanism for external modification of a variables is the sync instruction, therefore variables used with this instruction should be declared volatile.

Modifiers can be specified in any order.

External variables

[noinit] [cached] external [var] <variable1> [= <initial value>] [, <variable2> [= <initial value>] ... ];

External variables must be declared in global scope and are therefore always global. External variables can use the $ prefix, but can be declared without it. The $ prefix is part of the variable name: $a is different from a.

To use external variables, a heap needs to be allocated first using allocate heap declaration. A variable is assigned the lowest unoccupied slot from the heap. If the heap doesn't have enough capacity for the variable, an error occurs.

external is a modifier, and the var keyword is optional when external is used. Modifiers can be specified in any order. When declaring external variables, these additional modifiers can be used:

• cached: the value of the variable is read from the external memory just once at the variable creation and is kept in a processor variable. When using the variable value, the processor variable is used. When assigning a new value to the variable, the processor variable is updated, and the value is also written to the memory. It is assumed that only the current program changes the value of the corresponding external memory slot.
• noinit: this modifier is only meaningful with the cached modifier. When used, the initial value of the variable is not read from the memory slot at all, the variable only allows to write new values to the memory slot. This modifier cannot be used if the variable is assigned an initial value.

Cached variables are useful for situations where you want to store latest values in a memory to be reused when the processor is reset. Noinit cached variables are useful for unidirectional sending of data between processors. In both cases, you can read from the variables without any performance penalty, but all writes are automatically propagated to the memory without any explicit code.

Linked variables

[noinit] linked [var] <variable1> [= <linked block>] [, <variable2> [= <linked block>] ... ];

Linked variables must be declared in global scope and are therefore always global. When an initial value is not assigned to the variable, the variable identifier is the name of the linked block: linked cell1; declares a cell variable representing the cell1 block linked to the processor. When an initial value is assigned to the variable, the assigned value must be a name of the linked block, while the variable identifier will be used to represent the variable in the program: linked up = switch1, down = switch2;. This is useful to assign symbolic names to linked blocks.

A warning is generated if the name of the linked block used in variable declaration is not recognized, however the linked block is created. This way, it is possible to use linked blocks unrecognized by Mindcode (e.g. blocks from a mod).

linked is a modifier, and the var keyword is optional when linked is used. Modifiers can be specified in any order. When declaring external variables, these additional modifiers can be used:

• noinit: this modifier disables the generation of the guard code (see below).

Guard code for linked variables

When declaring a linked variable, Mindcode generates a guard code (single instruction per declared variable) which blocks execution until a block is linked to the processor under the expected name:

linked output = message1;
print("Here we are");
printflush(output);
stopProcessor();

compiles to

jump 0 equal message1 null
print "Here we are"
printflush message1
stop
print "Compiled by Mindcode - github.com/cardillan/mindcode"

Additionally, guard code is generated for undeclared linked blocks used in the allocate declaration (e.g. allocate heap in bank1; will generate guard code for bank1). To disable guard code generation in this case, explicitly declare the variable using noinit keyword:

noinit linked bank1;
allocate heap in bank1;

Guard code is not generated for linked variables that were not explicitly declared, for linked variables declared with the noinit modifier, and when guard code generation is disabled by the #set link-guards = false; compiler directive or the --link-guards false command-line argument.

Undeclared linked blocks used as parameter values (e.g. param memory = bank1;) also do not generate guard code.

Variable scopes

Implicit main variables are valid in all code outside functions. Implicit local variables are valid in their entire function.

Explicit variables are limited to the code block they're declared in:

#set syntax = strict;
begin
    // i is declared within the for code block
    for var i in 1 .. 3 do
        println(i);
    end;
    
    println(i);  // Error: i is not longer valid in this scope
end;

Variable names can be reused in non-overlapping scopes:

#set syntax = strict;
begin
    for var i in 1 .. 3 do
        println(i);
    end;
    
    for var i in 6 .. 9 do
        println(i);
    end;
end;

Variable resolution can be especially confusing when not using main code blocks:

var a = 1;        // Global variable
println(a);       // Prints "1"

if a > 0 then
    a = 2;        // Global variable again
    println(a);   // Prints "2"

    // The declaration is valid, because the code is in an implicit main code block and therefore
    // this is a new main variable distinct from global variable 'a':
    var a = 3;     
    println(a);   // Prints "3"
end;

// Main variable 'a' is no longer in scope: this is the global variable. 
println(a);       // Prints "2"

Properly enclosing the code in main code block makes the actual variable scope much clearer:

#set syntax = mixed;

var a = 1;

begin
    println(a);

    if a > 0 then
        a = 2;
        println(a);

        var a = 3;
        println(a);
    end;

    println(a);
end;

For this reason, we strongly suggest to enclose the code in main code block when using variable declarations, and to avoid using the same name for global and main/local variables.

Mixing explicit and implicit variables

In the relaxed and mixed syntax modes it is possible to use both explicit and implicit declared variables.

When encountering a variable identifier in the relaxed or mixed syntax, Mindcode attempts to resolve the variable using already known variables. If a known variable is not found, an implicit variable, valid for the entire function or all main code blocks, is created. Consequently, the following errors may occur when mixing explicit and implicit variables:

def function()
    x = 1;          // The variable is implicitly created here
    var x = 2;      // Error - multiple declarations of x
    
    // Here i is declared, and therefore valid within the for loop:
    for var i in 1 .. 3 do
        println(i);
    end;
    
    // Error: variable i isn't recognized in current scope, but implicit declaration
    // would create a variable in the full function scope, leading to a conflict with
    // variable i declared above.   
    println(i);
end;   

These errors do not arise if all variables using the same name are always declared, or none of them is.

Mlog variable name generation

Implicit and explicit variable names used in source code are translated to mlog using these rules:

• linked block and parameters: no modification to the variable name
• global variables: .variable (a . prefix)
• main variables: :variable (a : prefix)
• local variables: :fnX:variable (a : prefix both to the function counter and a variable name)
• temporary variables: *tmpX (*tmp + counter)
• function return address/variable: :fnXX*retaddr/:fnXX*retval
• stack pointer: *sp

If the same main or local variable is declared multiple times in the same function (in different code blocks), they actually represent different variables within a program. In this case, a unique numerical suffix is appended to variables created in the second and subsequent declarations, separated by . (a dot):

begin var i = 1; end;
begin var i = 2; end;

compiles into

set :i 1
set :i.1 2

[cardillan]

Seeing mlogjs/mlogjs#236, I'm starting to think that Mindcode might provide a way around shadowing global variables too.

On the other hand, I'm planning to add namespaces in not too distant future, and maybe a mechanism for accessing shadowed variables might emerge naturally from it.

[cardillan]

A first preview of Mindcode 3.0 was published:

• Release: https://github.com/cardillan/mindcode/releases/tag/v3.0.0-preview1
• Web app (preview): https://mindcode3-55e3aab18846.herokuapp.com/
• Readme: https://github.com/cardillan/mindcode/tree/mc3
• Documentation: https://github.com/cardillan/mindcode/blob/mc3/doc/syntax/SYNTAX.markdown