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.

An Example: FizzBuzz

Here's Mech some code:

This short example demonstrates several key features of the language:

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

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

• 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, making documentation clear and readable.

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

Why Mech?

Mech is designed to make building data-driven systems easier by providing a reactive programming model that is based on defining data dependencies and transformations. Mech programs can be thought of as feedback control systems, where data flows through a network of transformations and state machines that react to changes in the data.

This covers a lot of common use cases:

• Games - receives user input from 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 - user clicks a button or types on their keyboard, which changes the UI state, which is then rendered to the screen.

• Data Science - 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 (Document Object Model) for display in the browser.

However, most programming languages are based on a model of sequential execution, where the program is a series of instructions that are executed one after the other. Therefore when building these systems in those langauges, develoeprs often bring in additional libraries, framework, and middleware to bridge the gap between the sequential programming model and the data-driven, reactive nature of these applications.

In Mech, programmers define data and their relationships. Then they transformations these data with a rich set of operators and functions. Mech's compiler and runtime automatically determine how data flows through programs, and optimizes them for performance. When underlying data change, Mech updates all dependent data automatically. The Mech Platform also serializes, distributes, and logs your data. Together, this allows you to build efficient, data-driven, distributed systems that react to change, without having to write custom event loops or bring in large frameworks.

Programming System

We refer to Mech as a "programming system" because it encompasses more than just a programming language, but also a platform for building, running, and managing Mech programs 1.

Mech comes with integrated tools for data transformation, distribution, resource monitoring, and program optimization. We call this the "Platform", which is distinct from the "Language", which is the syntax and semantics used to write Mech programs.

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 you 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. WIP

4. A rich set of "machines", libraries, tools, and data sources which provide a wide range of functionality. 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.

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.2.66-beta.

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