Welcome to Mech!

Hello and welcome to the documentation for Mech, a programming language 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.

An Example: FizzBuzz

Let's get right to it, here's Mech some code:

This short example demonstrates several key features of the language:

• The syntax is concise, expressive and flexible, without the need for keywords and semicolons. In general, Mech programs should be much shorter than equivalent programs in other languages.

• Logical indexing manipulates elements of vectors based on conditions, a declarative way to express iteration and choice, which lends to parallel execution.

• Operations are broadcast elementwise across vectors without needing to write loops, which allows for more efficient execution and automatic vectorization resulting code.

• Type inference is used to determine the types of variables and expressions, so you don't have to specify all types explicitly.

• Variables are immutable by default, which encourages safer programming practices and makes reasoning about code easier.

• Rich text formatting is supported throughout Mech, including in comments, allowing you to document your code in a way that is easy to read and understand.

Why Mech?

The Big Idea

First, a little story...

In 2007, DARPA1 hosted a "Grand Urban Challenge" in which researchers were tasked with building autonomous vehicles that could navigate a city environment. The competition was structured in two phases: first, a qualifying round where teams had to demonstrate their vehicles could navigate a simple course, and then a final round where they had to navigate a more complex urban environment.

Qualifying teams were sorted into two groups: Track A teams were granted $1 million each to fund their competition entry; while Track B teams were invited to compete without any direct funding support from DARPA.

Of the 35 semifinalist teams, 11 advanced to the final event -- with 7 from Track A and 4 from Track B. It's not a surprise that of the 6 teams that finished the race, 5 were Track A. Just one team from Track B, the Ben Franklin Racing Team2, managed against all odds to finish the race. How did they do it?

When you look at the table above it's clear that despite their small size and limited funding, BFRT had a significant competitive advantage; whereas other teams invested in a C++ codebase that comprised hundreds of thousands of lines of code, Little Ben ran on just 5,000 lines of MATLAB code -- two orders of magnitude fewer lines of code than any other team.

This is a striking result, and it serves to challenge some conventional wisdom in robotic system design; high-level languages like MATLAB, which are sometimes considered "scripting languages", are often dismissed as being too slow or limited for serious applications. But in this case, BFRT was able to leverage MATLAB's extensive toolboxes and high-level abstractions to rapidly prototype, simulate, and deploy their autonomous driving logic.

This is where Mech comes in. Because the truth is, despite it working out for the BFRT, MATLAB still has a lot of shortcomings -- critically that it's not free and open source, so it can never really be a viable option for most developers. Therefore, Mech is our attempt to build an open-source language in this space that combines the best features of MATLAB with the performance and flexibility of a systems programming language like C++ in the context of robot programming.

Mech includes all of the matrix operations, data manipulation, and high-level abstractions that make MATLAB so powerful, but it also provides features such as:

• blazing fast performance

• more data types and structures

• static typing, including physical units

• state machines

• capability permission system

• reactive programming model

• concurrent and distrubted runtime

• live programming environment

• advanced debugging modalities, like time travel debugging

which make it more suitable for building complex, distributed systems from prototypign to production.

So why Mech? If you're looking to build a complex system, something on the order of a robot car, Mech will allow you to implement it in fewer lines of code, with performance on par with systems langauges, but safety and flexibility that you would expect from a high-level language.

Lineage

Mech is growing on a strange branch of the programming language family tree. We've already mentioned MATLAB as a major influence, but Mech also draws inspiration from a number of other languages and paradigms, including:

• Eve - Aside from MATLAB, Eve is the most direct influence on Mech. Eve was a dataflow language and environment focused on reactivity, declarative programming, and live coding. Mech builds on Eve's strengths, such as its spreadsheet-like model and live programming environment.

• Rust - The Mech compiler is implemented in Rust, and so it inherits some of Rust's design principles, such as its focus on safety, concurrency, and performance.

• Smalltalk - Mech is inspired by Smalltalk's introspective programming model, which allows you to inspect and modify the program's structure and behavior at runtime. Mech also shares Smalltalk's focus on object-oriented programming, in the original sense as a message-passing model for communication between objects.

• Logo - Mech shares in Logo's mission of being accessible to beginners, especially kids, and its focus on interactive, visual programming.

• Visual Basic 6 - The best version of Visual Basic, which was a popular for its GUI for building Windows desktop apps. Mech takes inspiration from VB6's event-driven programming model and its focus on building interactive applications.

• ROS - Not a programming language, but a middleware for building robot applications. Mech draws inspiration from ROS's modular architecture, its focus on data-driven design, and its use of a publish-subscribe messaging model for communication between components.

• Lucid - The first dataflow programming language, designed for building data-driven programs. Mech is inspired by Lucid's focus on data dependencies, its use of a declarative programming model, and its support for temporal operators.

If you've used or loved these languages, then you might find similar features in Mech that make it a good fit for your projects!

Is Mech for you?

Mech isn't just for building robots -- its reactive programming model and data-driven design make it suitable for a wide range of applications, from data science to game development. If you can model your project as a feedback control loop, or a data transformation pipeline, then Mech is a good fit for you.

Mech is for you if:

• You're a data scientist makes interactive visualizations of data, and you'd like host it on the internet or embed it in a native desktop application.

• You're a game designer who wants to build a game that requires networking and real-time data processing for multiplayer interactions.

• You're an artist who creates interactive installations or generative art that make use of sensors and servos.

• You're an engineer builds devices or robot that interact with the real-world via embedded microcontrollers, sensors, and motors.

• You're an educator uses animations and visualizations to teach concepts in math, science, or art.

• You're a researcher who builds simulations or models of a complex system, and you'd like to distribute it on the web or embed it inside of your journal article.

• You're a developer builds GPU accelerated applications that work natively across windows, mac, linux, and the web.

• You're a business person is comfortable with spreadsheets to something that can scale to automate business processes as well.

• You're a programming language enthusiast who wants to get involved in a project that is researching new directions in language design and tooling.

Programming System

Whereas traditional languages provide only syntax and a runtime, Mech comes with integrated tools for data transformation, distribution, resource monitoring, and program optimization.

Overview

The Mech programming system consists of four parts:

1. A data description language, which allows you to define the structure of your data and how it can be transformed.

2. A reactive programming model, based on state machines, which allows authors to write systems that can take advantage of asynchrouns and parallel program execution. (WIP)

3. A distributed execution engine, which allows you to run Mech programs across multiple machines in a variety of environments, including CPUs, GPUs, embedded devices, and the web. (WIP)

4. A rich set of "machines", libraries, tools, and data sources which provide a wide range of functionality, including data visualization, machine learning, simulation, and more. (WIP)

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.

About this Documentation

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.

Note - This documentation is written in Mechdown, a lightweight markup language that is compatible with Mech. This means that each document is a valid Mech program that can be executed.

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 language and fixing some of the 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 languages version is v0.2. This version require a rewrite of most of hte v0.1 codebase to accomodate changes to the data model and programming model, so many of the features in v0.1 have yet to be reimplemented.

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