Melt

HTTP Server & MVC Framework

Minimal server

class App {
    method handle() {
        let path = getRequestPath();
        if (path == "/") {
            setResponseBody("<h1>Hello</h1>");
            setResponseStatus(200);
        } else {
            setResponseStatus(404);
        }
    }
}
setHandler("App");
listen(8080);

Run: ./build/melt examples/server.melt then open http://localhost:8080/

MVC app (web_project_mvc)

Run: ./build/melt examples/web_project_mvc/main.melt

Structure: main.melt → config + routes; config/app.melt, config/database.melt; routes.melt (servePublic then controller); controllers/*.melt; models/; views/layout.melt + views/*.html (Blade-like {{ key }}, {!! key !!}); public/js, public/css, public/images; migrations/*.sql; run_migrations.melt.

Adding a route: Add branch in routes.melt, new controller file, render method in views/layout.melt, optional views/name.html.

Migrations: ./build/melt examples/web_project_mvc/run_migrations.melt. Add migrations/NNN_name.sql and append filename to migrationFiles in the runner.

Official website (official_website_using_melt)

Full Melt website: Home, Documentation, About, Resource, Support, and a dynamic blog (MySQL).

Run: ./build/melt examples/official_website_using_melt/main.melt then open http://localhost:4000

Structure: main.melt → config + routes; config/app.melt (port 4000), config/database.melt; routes.melt (servePublic then routes for /, /documentation, /about, /resource, /support, /blog, /blog/new, POST /blog, 404); controllers/*.melt (Home, Documentation, About, Resource, Support, Blog, NotFound); database/models/blog.melt (BlogPost); database/migrations/*.sql; database/seeders/*.melt; views/layout.melt + views/*.html; public/css/site.css; run_migrations.melt, run_seeders.melt.

Menu: Home (/), Documentation (/documentation), About (/about), Resource (/resource), Support (/support), Blog (/blog), New post (/blog/new).

Blog: All posts listed on /blog (drafts show “Draft” badge). Create at /blog/new; check “Publish” to show immediately. Edit config/database.melt for MySQL. Migrations: ./build/melt examples/official_website_using_melt/run_migrations.melt (requires -DUSE_MYSQL=ON).

Official Website (full reference)

The official Melt website lives in examples/official_website_using_melt/. It is built with Melt using the same MVC pattern as web_project_mvc and includes a dynamic blog backed by MySQL.

Run

./build/melt examples/official_website_using_melt/main.melt

Then open http://localhost:4000. Without MySQL, the site runs; the blog shows “No posts yet” and the New post form is available (creating a post requires MySQL).

Project structure

Menu and routes

Blog and database

Table: blog_posts (id, title, body, published, created_at). All posts shown on /blog; drafts show a “Draft” badge.

Migrations: -DUSE_MYSQL=ON, then ./build/melt examples/official_website_using_melt/run_migrations.melt. Edit config/database.melt for your MySQL.

Create post: Open /blog/new, fill title and body, optionally check “Publish”, submit.

Development guide

Building the interpreter and writing loadable extensions.

Building the interpreter

From the repo root:

cmake -B build && cmake --build build   # → build/melt
# Add targets in CMakeLists.txt for extensions → bin/modules/

Optional: -DUSE_MYSQL=ON. Config is read from build/melt.ini and project melt.config.

Extension contract

Loadable extensions are shared libraries. Each must export:

extern "C" void melt_register(Interpreter* interp);

Melt calls melt_register(interp) after loading. Register built-ins with:

interp->registerBuiltin("functionName", yourNativeFn);

Built-in function signature

Type Interpreter::NativeFn:

Value yourBuiltin(Interpreter* interp, std::vector<Value> args);

Value is a std::variant of std::monostate, double, std::string, bool, and object/array/class types. Return e.g. Value(3.14) or Value(std::string("hi")).

Include path

Extensions need the same includes as the main binary so #include "interpreter.hpp" works (e.g. -I src -I src/core from repo root).

Building extensions

• Example: CMake (see extensions/) builds extensions/example/example.cpp into bin/modules/example.dylib (macOS), example.so (Linux), or example.dll (Windows).
• macOS: use -fPIC -shared -undefined dynamic_lookup so the extension resolves Interpreter::registerBuiltin from the main binary at load time.
• Linux: main binary is built with -rdynamic so loaded .so files can resolve interpreter symbols.

Configuration (melt.ini)

In build/melt.ini or project melt.config:

• extension_enabled = 1|0|true|false|on|off — enable/disable loading extensions (default: on).
• extension_dir = directory relative to the melt binary (default: modules).
• extension = comma-separated extension names to load (e.g. example, math).

Libraries are loaded from <binDir>/<extension_dir>/<name>.so|.dylib|.dll.

Example extension

See extensions/example/example.cpp for a minimal extension (exampleVersion, exampleAdd, exampleSqrt). Example docs: extensions/example/index.html.

Adding your own extension

1. Add a folder under extensions/ with a .cpp that implements melt_register and registerBuiltin calls.
2. Add a CMake target (or Makefile wrapper target) to build a shared library into bin/modules/<name>.so|.dylib|.dll.
3. Set extension = <name> (or append to the list) in melt.ini.

Module development guide (step by step)

This guide explains how to create a Melt loadable module (extension) in simple steps. A module is a shared library (.so, .dylib, or .dll) that adds new built-in functions to Melt. Your Melt scripts can then call these functions like any other built-in.

What you need

• A C++ compiler (same as for building Melt: g++ or clang++).
• The Melt source code (so you can #include "interpreter.hpp").
• One or more .cpp files that implement your functions and the melt_register entry point.

Step 1: Create your module folder and source file

Create a folder under extensions/, for example extensions/mymodule/. Inside it, create a .cpp file (e.g. mymodule.cpp). This file will contain all your native functions and the registration function.

Step 2: Include the interpreter header

At the top of your .cpp file, include the Melt interpreter so you can use Interpreter, Value, and registerBuiltin:

#include "interpreter.hpp"

When building, you must pass the same include paths as the main Melt binary (e.g. -I src -I src/core from the repo root).

Step 3: Write a built-in function

Every built-in has the same C++ signature:

static Value myFunc(Interpreter* interp, std::vector<Value> args) {
    // interp: use if you need the interpreter (e.g. get variables)
    // args: the arguments passed from Melt (e.g. myFunc(1, 2) → args[0]=1, args[1]=2)
    // Return a Value: number, string, bool, etc.
    return Value(42.0);           // number
    return Value(std::string("hi"));  // string
    return Value(true);          // boolean
}

Reading arguments: args is a vector of Value. Each Value can hold a number (double), string, bool, array, or object. Use std::get_if<double>(&args[0]) to get a number, std::get_if<std::string>(&args[0]) for a string, and so on. Check args.size() before indexing.

Returning: Return Value(...). For "no value" you can return Value() (monostate).

Step 4: Implement the registration entry point

Melt loads your library and looks for a single function named melt_register. It must be extern "C" so the name is not mangled. Inside it, register each of your built-ins with the interpreter:

extern "C" void melt_register(Interpreter* interp) {
    interp->registerBuiltin("myFunc", myFunc);
    interp->registerBuiltin("myOtherFunc", myOtherFunc);
}

The first argument is the name as seen in Melt (your script will call myFunc(...)). The second is the C++ function pointer. Melt calls melt_register(interp) once when the extension is loaded.

Step 5: Build the shared library

You must compile your .cpp into a shared library and put it where Melt can find it.

• Linux: g++ -std=c++17 -fPIC -shared -I src -I src/core -o bin/modules/mymodule.so extensions/mymodule/mymodule.cpp (Melt's main binary is built with -rdynamic so the .so can resolve interpreter symbols.)
• macOS: clang++ -std=c++17 -fPIC -shared -undefined dynamic_lookup -I src -I src/core -o bin/modules/mymodule.dylib extensions/mymodule/mymodule.cpp
• Windows: Build a .dll with similar flags and place it in bin/modules/mymodule.dll.

Or add a target to CMakeLists.txt (or the Makefile wrapper) to build your library into bin/modules/.

Step 6: Enable the extension in config

Create or edit build/melt.ini (next to the melt binary). Add or set:

extension_dir = modules
extension = example,mymodule

extension_dir is the folder under the binary directory where Melt looks for libraries (default modules). extension is a comma-separated list of extension names (no suffix). Melt will load bin/modules/mymodule.so (or .dylib / .dll) and call melt_register.

Step 7: Use your functions in Melt

Run a script that calls your new built-ins. For example:

let x = myFunc(1, 2);
print myOtherFunc("hello");

If the extension failed to load, Melt will print an error to stderr. If it loaded, your functions are available globally like print or readFile.

Summary

1. Create extensions/<name>/<name>.cpp.
2. Include interpreter.hpp.
3. Implement one or more functions with signature Value fn(Interpreter*, std::vector<Value> args).
4. Implement extern "C" void melt_register(Interpreter* interp) and call interp->registerBuiltin("name", fn) for each.
5. Build a shared library into bin/modules/<name>.so|.dylib|.dll.
6. Set extension = <name> in build/melt.ini (or project melt.config).
7. Run ./build/melt your_script.melt and call your built-ins from the script.

See extensions/example/example.cpp for a minimal working example (exampleVersion, exampleAdd, exampleSqrt).

Embedded guide

This section explains the embedded build of Melt, when to use it, what it includes and excludes, and how to run a sample embedded-style application.

What is the embedded build?

The embedded build (embedded build) produces a smaller binary, build/melt-embedded, by excluding optional subsystems that are not needed on resource-constrained or embedded-style targets:

• HTTP server — no listen(), setHandler(), getRequestPath(), servePublic(), etc. Scripts that call these get a clear runtime error: "Melt embedded build: HTTP server not available".
• MySQL / SQLite — no mysqlConnect, mysqlQuery, mysqlFetchRow, mysqlFetchAll, mysqlClose, sqliteOpen, sqliteExec, sqliteQuery, sqliteFetchRow, sqliteFetchAll, sqliteClose. Those built-ins are not registered (calling them yields "unknown variable").
• GUI (SDL2) — no imagePreview(). The GUI window is not linked. Scripts that call it get a runtime error.

The embedded binary still includes the core language (variables, types, control flow, classes, methods, import, try/catch/throw) and built-ins such as print, readFile, writeFile, arrays, JSON, base64, xorCipher, vectors, and the module loader (loadable extensions). So you can script logic, file I/O, and optional native extensions (e.g. GPIO or UART) without pulling in HTTP, MySQL, or SDL2.

When to use it

• Smaller binary and fewer dependencies — Use melt-embedded when you run Melt on a device (e.g. Raspberry Pi, BeagleBone) or in an environment where you do not need a web server, database client, or GUI. The binary is smaller and does not link libmysqlclient or SDL2.
• Embedded-style scripting — Use it for scripts that implement control logic, read/write files or device nodes, or call into native extensions that talk to hardware (GPIO, UART, etc.). The script runs in a loop or is invoked by a host process; it does not start an HTTP server.
• CI or minimal installs — Use the embedded build in CI or minimal installs where you only need to run Melt scripts that do not use HTTP, MySQL, or GUI.

What is included vs excluded

How to build and run

embedded build

This produces build/melt-embedded. Run scripts with:

./build/melt-embedded path/to/script.melt

Use the same working directory and path rules as for melt (e.g. run from project root when using import or relative paths in readFile). Do not call listen(), MySQL built-ins, or imagePreview() in scripts intended for the embedded binary.

Sample embedded system

A sample embedded-style application is provided in examples/embedded_system/. It demonstrates a simple control loop: read "sensor" input (from a file or simulated value), update state, and write "actuator" output (to a file or stdout). This pattern is typical of embedded or IoT scripts that run on a small device.

• examples/embedded_system/main.melt — Entry point: loads config, runs the main loop for a number of cycles, and exits.
• examples/embedded_system/config.melt — Configuration (e.g. cycle count, paths for sensor/actuator files).
• examples/embedded_system/loop.melt — Core logic: read sensor, compute state, write output. Imported by main.

Run it with the embedded binary (from project root):

./build/melt-embedded examples/embedded_system/main.melt

You can use the full build/melt as well; the script does not use HTTP, MySQL, or GUI. The embedded build is recommended so the binary and dependencies stay minimal.

Extending for real hardware

On a real embedded or single-board target (e.g. Raspberry Pi running Linux), you can:

1. Build melt-embedded on the device or cross-compile, and install it (e.g. cmake --install build --prefix /usr/local (or extend the build for an embedded binary)).
2. Implement a loadable extension that provides built-ins such as gpioRead(pin), gpioWrite(pin, value), uartWrite(str), or delayMs(ms). Register them in melt_register and load the extension via melt.ini or melt.config.
3. Write Melt scripts that call those built-ins in a loop, or invoke the script from a systemd unit or cron job. The sample in examples/embedded_system/ uses file I/O as a stand-in for hardware; replace that with calls to your extension once it is available.

Summary

• Build: embedded build → build/melt-embedded.
• Use when: You need a smaller binary and do not need HTTP, MySQL, or GUI.
• Run: ./build/melt-embedded script.melt. Avoid listen(), MySQL, and imagePreview().
• Sample: examples/embedded_system/main.melt shows a simple sensor–logic–actuator loop; run it with melt-embedded.

Examples

Run from project root: ./build/melt examples/<path>.melt