Introduction

Welcome to Mech!

Hello and welcome to the documentation for Mech, a programming language and platform for developing data-driven, reactive systems. Mech authors build programs by defining data dependencies, transformations, and state machines. This makes Mech particularly well-suited for applications that require real-time data processing, such as simulations, visualizations, and cyber-physical systems like robots.

Example Programs

To give you a sense of what Mech looks like, here are a few example programs that demonstrate some of its core features and syntax.

Hello, World!

First, the classic program which prints the string "Hello, World!" to the console:

In Mech, the result of the final expression in a program is automatically returned and printed to the console, without needing an explicit print statement.

FizzBuzz

Next, a simple FizzBuzz program that prints the numbers from 1 to 10, replacing multiples of 2 with "Fizz", multiples of 3 with "Buzz", and multiples of both with "FizzBuzz":

This example demonstrates several core Mech features:

• Concise syntax: Expressive and flexible, with no need for keywords or semicolons; Mech programs are generally shorter than in other languages.

• Declarative style: Focus on what to compute, not how to compute it, leading to clearer and more maintainable code.

• Broadcast operations: Vector operations apply elementwise automatically, removing loops and enabling efficient vectorization.

• Static typing: Types are checked at compile time, catching errors early and improving performance.

• Type inference: Variable and expression types are inferred, so explicit type declarations are often unnecessary.

• Immutable by default: Variables are immutable unless specified, promoting safer code and easier reasoning.

• Logical indexing: Select and manipulate vector elements via conditions, enabling declarative iteration and parallel execution.

• Rich text formatting: Comments and code support rich formatting using a Markdown-like syntax called Mechdown, making documentation clear and readable.

Power Function

Here is an example of a recursive function to compute the power of a number:

• Pattern matching: Different input cases are handled cleanly and declaratively with patterened matching on function parameters.

• Kind annotations: Function parameters and return types are be annotated for clarity and type checking.

• Recursive functions: Functions in Mech can be defined recursively, allowing for elegant solutions to problems that have a self-similar structure.

• Idempotent: Functions produce the same output for the same input and can be automatically memoized by the runtime for improved performance on repeated calls with the same arguments.

Matrix Multiplication

Here is an example of matrix multiplication in Mech:

• Matrices: Matrices and vectors are built into the language, unified as a single data type

• Linear algebra operations: Common linear algebra operations like matrix multiplication, transpose, and cross are supported natively with concise syntax.

• Shape validation: Matrix dimensions are checked at compile time and rejected if they are incompatible for the operation.

Gaussian Elimination

Here is an example of performing Gaussian elimination to solve a system of linear equations:

• Solvers: Mech includes built-in solvers for common mathematical problems, such as linear systems, optimization, and differential equations.

• Numeric precision: Supports data types with varying levels of precision up to 128 bits, as well as floating-point, rational, imaginary, complex, and arbitrary precision integers.

• Performance: Mech's solvers are optimized for performance, and can take advantage of hardware acceleration when available.

Friends-of-Friends

Mech has a set datastructure with support for set comprehensions and relational algebra. Here is an example that finds the friends-of-friends for a given user in a social network:

• Set comprehensions: concisely create sets from an iterable in a single line of code

• Pattern matching: Tuples are destructured directly in the comprehension.

• Relational: Reusing variables creates natural joins across data.

• Declarative: Relationships are described without explicit iteration.

Why Mech

Mech programs start with data. You define data structures, and then describe how they relate to each other through formulas and state machines. The Mech compiler and runtime automatically determine how data flows through your program, and optimizes it for performance. When underlying data change, Mech updates all dependent data automatically. This makes it easier to build systems that react to change, without having to write custom event loops or bring in large frameworks.

Mech is an embeddable language, meaning you can integrate it into existing applications and systems. This allows you to leverage Mech's data-driven programming model without having to rewrite your entire codebase, so the cost of adoption is low.

You don't even have to use Mech as a full programming language, because it's also a pretty good presentation language as well. Mechdown, the markup language used to write this documentation, is designed to be both human-readable and machine-executable. This means you can write documents that are also valid Mech programs, as a front-end for your non-Mech systems.

Over time, you can use more Mech incrementally where it makes the most sense and brings the most leverage, starting with small scripts and moving to larger programs as you become more comfortable with the language.

Use Cases

Mech programs can be thought of as feedback control systems, which are systems that maintain a desired state by continuously adjusting their behavior based on changes in input data. This program architecture is surprisingly general, and covers a variety of common use cases:

• Games - receives user input from a game controller, updates internal player scores and runs game logic, then renders the game to the screen.

• Embedded Systems - sensors make environmental readings and update the device, which reacts by controlling actuators or sending messages.

• User Interfaces - the user clicks a button or types on their keyboard, which changes the UI state, which is then rendered to the screen.

• Data Science - the user loads data from a source and processes it, which updates visualizations or statistical models.

• Robotics - sensor readings from cameras and LIDAR are processed by the robot to update its internal belief, which is used to plan and execute actions in the physical world.

• Web Applications - user interactions and network events update the application state, which is then rendered to the DOM for display in the browser.

• Financial Systems - market data and user transactions update the system state, which is then used to make trading decisions or generate reports.

If you are building one of these types of systems, Mech may be a good fit for your project!

Programming System

Overview

The Mech programming system consists of four parts:

1. Mech - The programming language proper, which includes the syntax, semantics, and core libraries for writing Mech programs.

2. Mechdown - A lightweight markup language for writing Mech documentation and literate programs.

3. Standard Library - A collection of modules and functions that provide common functionality for Mech programs.

4. Tools - A set of command-line tools and utilities for working with Mech programs.

5. Notebook - An interactive notebook environment for writing and executing Mech code in a rich, document-like interface.

Tools

• mech - the Mech programming language toolchain, which includes:

• Parser and compiler for the text-based Mech syntax

• Runtime for executing Mech programs

• REPL for interactive programming

• Formatter for formatting Mech code into canonical style or HTML documentation.

• Server for serving Mech programs to a wasm client

• Language Server Protocol implementation

• mech-wasm - a wasm-based client for running Mech programs in the browser or other wasm environments.

• mech-notebook - a notebook editor for Mech that runs natively on Windows, macOS, and Linux, and also supports running in the browser via mech-wasm.

Features

Some of the key features of the Mech programming platform include:

• Automatic data propagation: Mech automatically tracks data dependencies and propagates changes through the program, ensuring that all dependent data are updated correctly.

• Vectorized operations: Mech supports vectorized operations, allowing you to perform computations on entire arrays of data without explicit loops, which leads to more concise and efficient code.

• Live, literate programming: Mech supports live literate programming environment, meaning you can write and execute code in an interactive notebook-style interface, with rich text formatting and inline documentation.

• Distribution and Serialization: Mech programs can be easily distributed across multiple machines, and all data can be serialized and deserialized automatically, including entire functions and programs.

• Time travel debugging: Mech's runtime supports time travel debugging, allowing you to step forwards and backwards through program execution to inspect the state of your data at any point in time.

• AI-optimized: Mech is designed to work with AI systems, making it easier for AI to understand and write Mech code even without having been trained on it.

For a complete list of features and the statuses of their implementations, see the ROADMAP.

About This Documentation

Structure

This documentation is designed to help you get started with Mech, understand its core concepts, and provide guidance on how to use the language effectively. It is structured as follows:

1. Getting Started: an introduction to Mech, how to install it, and how to build and run Mech programs. It also covers the Mech REPL (Read-Eval-Print Loop) for interactive programming.

2. Reference: a detailed reference for the Mech language, including its data model, programming model, system model, standard library, and Mechdown reference.

3. Guides: provides practical guides and tutorials for using Mech, including a quick introduction to the language, tutorials for specific use cases, and guides for developers coming from other programming languages.

4. Design Documents: information on the design principles behind Mech, including the language specification, design principles, syntax design notes, and the roadmap for future development, as well as the history of the language.

Conventions

This documentation uses several conventions to help you navigate and understand the content:

• Executable Code Blocks: Mech code examples are presented in code blocks, with syntax highlighting to improve readability.

• Links: hyperlinks to other sections of the documentation or external resources are provided throughout the text for easy navigation.

• Module Links: references to standard library functions and modules are indicated differently to distinguish them from regular text.

• This is a reference to the set module.

• This is a reference to the set/union function.

• Notes and Warnings: important information, tips, and warnings are highlighted using callout blocks to draw attention to them.

Mechdown

This documentation is written in Mechdown, a lightweight markup language that is designed simulatneously with Mech. This means that each document is a valid program that can be executed on the Mech platform.

Getting Involved

The Mech community stays active at a few places around the Internet:

• Discord - for live chat

• GitHub - for code and issues

• YouTube - for video tutorials

• Reddit - for help and general discussion

• Mailing List - for dev discussion

Project Status

Mech has been in active development since 2018, and reached beta status in 2022.

The beta phase has focused on stabilizing the core language and fixing shortcomings of the initial design. We anticipate four stages of development in the beta stage:

• v0.1 - proof of concept system - minimum viable language implementation

• v0.2 - data specification - formulas, defining and manipulating data

• v0.3 - program specification - functions, modules, state machines

• v0.4 - system specification - tools, distributed programs, capabilities

Currently the platform version is v0.3.2-beta.

Visit the ROADMAP for more information on the current status of features.