Learn Mech in Fifteen Minutes

Comments

-- Single line comment.

// Also a single line comment.

Mech does not support multiline comments. Instead, Mech encourages literate programming through a Markdown-esque syntax called Mechdown, exemplified by this document.

Comments are therefore to be used primarily inside of code blocks.

Comments support paragraph formatting, such as bold, underline, links, etc. For example:

 -- Comments support **bold**,  __underline__, [links](/foo/bar), etc.

Identifiers

Identifiers start with letters or most UTF-8 encoded characters, and can contain alphanumeric, most emojis, /, *, +, -, and ^ characters.

• Hello-Word

• io/stdout

• Δx^2

• 🤖

• A*

The preferred identifier case in Mech is kebab-case (words deliniated by dashes). Slashes also allow identifiers to be scoped to a particular namespace.

Kinds

A kind describes the type of data a value can hold. Every value in Mech has a kind, and kinds themselves are values.

Kinds describe the data type, not mutability, which is a property of the data binding.

Simple Kinds

Kinds are written inside angle brackets < >. The following kinds represent the built-in data types in a base Mech distribution:

Compound Kinds

Kinds compose structurally to describe collections.

• Matrix: <[T]:2,3> (A 2x3 matrix of T)

• Table: <|x<T>,y<U>|:3> (A table with columns x and y of types T and U, and 3 rows)

• Tuple: <(T,U)> (An ordered pair)

• Map: <{K:V}> (Maps K to V)

• Set: <{T}> (A set of unique T values)

Kind Annotations & Conversion

Annotations constrain variables or cast literals.

Custom Kinds & Enums

Aliases:

You can create aliases for semantic clarity.

Enums:

Enums define a fixed set of variants using atoms.

Data Types

Number

Numbers in Mech can be classified into the following categories:

• Integers - Whole numbers, which can be positive, negative, or zero

• Signed - Can represent both negative and positive values

• i8 - 8-bit signed integer

• i16 - 16-bit signed integer

• i32 - 32-bit signed integer

• i64 - 64-bit signed integer

• i128 - 128-bit signed integer

• Unsigned - Can only represent zero and positive values

• u8 - 8-bit unsigned integer

• u16 - 16-bit unsigned integer

• u32 - 32-bit unsigned integer

• u64 - 64-bit unsigned integer

• u128 - 128-bit unsigned integer

• Float - Decimal numbers with fractional components

• f32 - 32-bit floating-point number

• f64 - 64-bit floating-point number

• Rational - Numbers represented as fractions of integers

• r64 - 64-bit rational number

• Complex - Numbers with real and imaginary components

• c64 - 64-bit complex number

Numeric literals can be expressed in various formats:

• Floating-point numbers, expressed in standard decimal notation and scientific notation

• Integers, expressed in decimal (base 10), hexadecimal (base 16), octal (base 8), and binary (base 2)

• Rational numbers, expressed as fractions a/b, where a is the numerator and b is the denominator

• Complex numbers, expressed in the form a + bi or a + bj, where a is the real part and b is the imaginary part

Floating-Point Literals

Floating-point literals are used to represent decimal numbers with fractional components. They are flexible in that they can represent both very large and very small numbers, and also can represent integer values between -1.7e308 and 1.7e308 for f64, and between -3.4e38 and 3.4e38 for f32.

Floating-point literals are expressed in standard decimal notation or scientific notation:

Each value is inferred as f64 unless otherwise specified. To specify a specific type, floating-point literals can also be suffixed with a specific kind:

Integer Literals

Integer literals can be written in the following formats:

Decimals without a prefix are inferred as floating-point numbers (f64), while those with the 0d prefix are inferred as signed integers (i64). Each of the other formats are also inferred as i64 unless otherwise specified. Any integer literal can be suffixed with a specific kind to indicate its type:

Decimal literals can be signed or unsigned. Signed literal types include i8, i16, i32, i64, and i128. Unsigned literal types include u8, u16, u32, u64, and u128.

Rational Literals

Rational numbers are used to represent fractions exactly as ratios of two integers. They are expressed in the form a/b, where a is the numerator and b is the denominator.

Rational numbers are written as follows:

Two rational literals can represent the same numeric value but have different representations:

Complex Literals

Complex numbers are used to represent numbers with both real and imaginary components. They are expressed in the form a + bi or a + bj, where a is the real part and b is the imaginary part.

Complex numbers are written as follows:

The imaginary unit can be represented by either i or j. Both representations are equivalent and can be used interchangeably.

String

String literals are written using double quotes ".

Strings may contain spaces and punctuation. Whitespace inside a string literal is preserved.

Escape sequences may be used for special characters:

"line 1\nline 2"
"quote: \""
"tab\tseparated"
"backslash: \\"

When rendered:

Raw string literals can be created using triple double quotes """. In this form, escape sequences are not processed, and all characters are taken literally, including backslashes and quotes.

"""C:\Users\Name\Documents"""
"""This is a "raw" \string\ literal."""

When rendered:

String Concatenation

Strings can be concatenated using the + operator:

String concatentation is broadcast element-wise over matrices of strings:

If both operands are matrices of strings, they must have compatible dimensions:

Conversion to String

All values can be converted to strings explicitly.

Use <[string]> to create a matrix of strings:

This converts a <[f64]:1,4> (row matrix of floats) to a <[string]:2,2> (square matrix of strings).

Boolean

Boolean literals are written using the keywords true and false.

Several alterantive forms are also accepted:

Logical Operations

Boolean values support the following logical operations:

Comparison Operations

Comparison operators produce boolean results:

Filtering

An array of logical values can be used as an index to filter another array:

Atom

Atoms are written using a leading colon : followed by an identifier:

Atom names may be any valid identifier, including Unicode characters.

Two atoms with the same name are identical:

Empty

An empty value is written using one or more underscores _:

Empty is used to represent missing values in tables and skipped elements in tuple destructuring.

Variables

Variables are created using the := operator:

By default, all variables are immutable. To create a mutable variable, prefix the variable name with ~:

Semicolons can be used to write multiple statements on one line:

You can use a kind annotation in the variable declaration to constrain the variable to a specific kind:

Data Structures

Matrix

Declare a matrix using square brackets [].

Use semicolons ; or newlines to separate rows.

Use commas , or spaces to separate columns.

[1,2,3]   -- A row vector (1x3)
[1 2 3]   -- The same row vector

[1;2;3]   -- A column vector (3x1)
[1        
 2
 3]       -- The same column vector

[1,2;3,4] -- A matrix (2x2)
[1 2
 3 4]     -- The same matrix
[1 + 2; 3 + 4] -- Elements can be expressions

By default, all matrices are rank 2, meaning they have rows and columns. Elementes are indexed in a [row, column] format.

When parsed and formatted, they look like this:

Broadcast Operations

If matrices have the same dimension, standard arithmetic operations are performed element-wise:

If one of the operands is a scalar, it will be added or subtracted from each element of the matrix:

Matrix Access

Logical Indexing

Operators

mech:disabled

(6.3.1) Element Access

Tuple elements are accessed by their 1-based index using the `.` operator.

mech:ex 6.3.1

(6.3.2) Destructuring

Tuples can be destructured into variables:

mech:ex 6.3.2

(6.4) Record

Records are written using curly braces `{}` with named fields. Each field is written as `name: value` and fields are separated by commas.

mech:disabled

Records may be written inline or across multiple lines for readability:

(6.5) Table 

Tables are defined using the pipe `|` character. Each column is defined with a name and a kind, which describes the type of data it holds.

This creates a table with two columns, `x` of kind `f32` and `y` of kind `bool`:

mech:disabled

You can write tables inline as well:

(6.5.1) Coulmn Access

Access table columns as vectors with the `.` operator:

mech:disabled

Row Access

Access table rows as records using the single index operator []:

Table Operators

Set

A set is an unordered collection of unique elements. They are defined using curly braces {}.

Elements are separated by commas ,. Duplicate elements are automatically removed.

Set Operators

Map

You can define maps using curly braces {} with a colon : to separate keys from values.

Functions and Patterns

Functions are defined with a signature and one or more pattern branches.

Pattern branches are matched top-to-bottom:

Guarded branches:

Pattern Varieties

• Wildcard: * matches any value

• Variable: x matches any value and binds it to x

• Tuple: (x, y) matches a tuple and binds its elements to x and y

• Array: [first ... last] matches an array and binds its elements to first and last

• Slice [head | tail] matches a non-empty array, binding the head to head and the tail to tail

Enums and Match

Define enums using atoms:

Use ? to match on values:

Tagged variants (payloads):

State Machines

State machines use #Name(...), explicit states, and transitions.

Pattern-based state transitions: