Language Essentials

MatchBox runs BoxLang on a Rust VM. This tour introduces the core language; use the Run buttons to try examples in your browser.

For runtime and target differences, see BoxLang compatibility. For the language in depth, use the language reference. To learn by doing, start with the course.

Variables, strings and operators

name = "MatchBox";
active = true;
count = 3;
println( "Hello, #name#!" );
println( "Built with " & name );
println( count * 2 + 1 );
println( "abc" contains "b" );
println( n ?: "n is null" );

Output:

Hello, MatchBox!
Built with MatchBox
7
true
n is null

Variables are dynamically typed. & joins strings, #expression# interpolates inside a double-quoted string, and ?: supplies a value when the left side is null. See operators.

Arrays and structs

targets = [ "native", "browser", "embedded" ];
println( targets[ 1 ] );
targets.append( "wasi" );
println( targets.len() );

project = { name: "Hello", ready: true };
println( project.NAME );

lengths = arrayMap( targets, ( target ) => len( target ) );
println( serializeJSON( lengths ) );

{ name, ready } = project;
println( name & " " & ready );
println( serializeJSON( [ 0, ...targets ] ) );

Output:

native
4
Hello
[6,7,8,4]
Hello true
[0,"native","browser","embedded","wasi"]

Arrays are 1-indexed and struct keys are case-insensitive. Destructuring and spread are covered in destructuring, spread and ranges. MatchBox also has a set type.

Control flow and functions

for ( target in [ "native", "browser" ] ) {
    if ( target == "native" ) {
        println( "Build an executable" );
    } else {
        println( "Explore " & target );
    }
}

switch ( "b" ) {
    case "a":
        println( "A" );
        break;
    case "b":
    case "c":
        println( "B or C" );
        break;
    default:
        println( "other" );
}

function greet( name = "world" ) {
    return "Hello, " & name;
}
double = ( number ) => number * 2;
println( greet() );
println( greet( name = "Ada" ) );
println( double( 21 ) );

Output:

Build an executable
Explore browser
B or C
Hello, world
Hello, Ada
42

Use while, do ... while, break, continue and ranges for other loop shapes. Closures can use values from their enclosing function; see scopes.

Classes

class Product accessors="true" {
    property name;
    property price;

    function init() {
        return this;
    }
}

product = new Product();
product.setName( "Widget" );
println( product.getName() );

Output:

Widget

Use init to initialize objects and extends="Parent" to inherit behavior. See classes.

Errors and asynchronous work

try {
    throw( type = "MyError", message = "boom" );
} catch ( any e ) {
    println( e.type & ": " & e.message );
} finally {
    println( "done" );
}

future = runAsync( () => {
    sleep( 100 );
    return "finished";
} );
println( future.get() );

Output:

MyError: boom
done
finished

A typed catch handles matching errors; catch ( any e ) is a fallback. See error handling and async and futures.

Function library

MatchBox ships built-in functions for strings, arrays, structs, dates, JSON, regular expressions, XML, hashing and more. The function reference lists each one. Some groups are optional parts of the build:

See Building MatchBox for custom build options.

Other parts of the language

• Templates (.bxm): mix markup with BoxLang.
• Modules: add functions and classes with --module.
• Queries and data.
• Java interop: experimental.
• Native Fusion: call Rust from BoxLang.