mclangc/docs/main.md

Quick warning

This language is still in its pre alpha stages, while it tends to work it still has numerous bugs, breaks, and fails with a smell of unusual input, it is not suitable for anything beyond experimenting and having fun. That said this project has been my biggest one yet, and is one of my favorites, having went under multiple rewrites over the 4 or so years its changed a lot from simple forth style syntax, to now, a c/rust style, which has been a struggle, but now its at a point where it actually produces code and you can kinda make something with it.

Hope you have fun figuring out how to use this damn thing, and maybe even build something with it.

Also, the docs are also written with ChatGPT (gross, i know), but i needed some docs fast.

- MCorange

Summary

This language is a small, low level, C and Rust inspired systems language with a strong focus on explicit control, simple syntax, and predictable behavior. It mixes familiar C style statements and loops with Rust-like ideas such as structs, methods, references, and explicit types. The goal is clarity over magic: most things are spelled out, lifetimes are implied by references, and there is little hidden behavior.

The language is suitable for experiments, embedded style programs, or as a foundation for a custom runtime or OS environment. It favors straightforward semantics, manual control flow, and a minimal standard library model.

High level description

As a procedural language, barely higher level than C, programs are built from functions, structs, and constants. Types are explicit, references are written by prepending &, and arrays or slices are expressed directly in the type system. For now code is organized with include, for simpler development, this will change into modules eventually.

Control flow is traditional and imperative. There are if, else, for, while, and loop constructs, along with break and continue. Functions return values explicitly using return, and side effects are visible and direct.

Methods are just functions namespaced under a type, and there is no hidden constructor logic. Everything that allocates or returns a reference does so explicitly.

Small language reference

Types

Type aliases:

type cstr = [u8];

Creates an alias. Here, str is defined as a byte array type.

Built-in simple types:

• usize/isize
• i8-i64
• u8-u64
• bool
• array or slice types like [u8]

References are written with &T.

Includes

include "std.mcl";

Textual inclusion of another source file. This is resolved at compile time.

Structs

struct Foo {
    a: usize,
    b: &str
}

Structs group named fields. Fields have explicit types. There are no implicit constructors.

Functions

Function definition syntax:

fn name(arg: Type, ...) -> ReturnType {
    ...
}

Example:

fn mul(n: usize, n2: usize) -> usize {
    return n * n2;
}

Functions may return values using return. Void functions omit the return type.

Methods

Methods are functions scoped to a type:

As of now methods are only able to be linked to Structs

fn Foo.new(a1: usize, b: &str) -> &Foo {
    return &Foo {
        a: a1,
        b: b
    };
}

This defines a constructor-like function for Foo. It explicitly returns a reference to a Foo value.

Variables

Variables are declared with let:

let obj = Foo::new(1, "owo");

Type inference appears to exist, but types can likely be written explicitly if desired.

Field access

Struct fields can be accessed through references:

obj->b;

As well as without dereferencing:

obj.c

Control flow

Infinite loop:

loop {
    ...
}

While loop:

while (true) {
    ...
}

For loop:

for (let i = 0; i < 10; i += 1) {
    ...
}

Conditionals:

if (i > 7) {
    break;
} else {
    continue;
}

Constants

const FOO: usize = main;

Statics

static FOO: usize = main;