XTML Module Development Guide

Modules in XTML allow you to extend the language with custom functions that can be used inside <xtml> blocks. Modules are implemented as C++ shared libraries (DLLs) and can be loaded at runtime.

1. Module Structure

Every XTML module must implement a class that inherits from the base Module class:

#include "FunctionRegistry.h"

class MyModule : public Module {
public:
    void RegisterFunctions(FunctionRegistry& registry) override {
        // Register your functions here
    }
    ~MyModule() = default;
};

• RegisterFunctions is called by XTML to register all functions provided by your module.
• You can define functions in namespaces to organize them logically.

2. Registering Functions

Use FunctionRegistry to expose functions to XTML templates:

registry.RegisterNamespace("mymodule"); // namespace first
registry.RegisterFunction("mymodule", "add", [](const std::vector<var>& args) -> var {
    if (args.size() != 2 || args[0].type != DT_NUMBER || args[1].type != DT_NUMBER) {
        Utils::printerrLn("Error: add expects 2 numeric arguments.");
        return var{"", DT_UNKNOWN};
    }
    int sum = std::stoi(args[0].value) + std::stoi(args[1].value);
    return var{std::to_string(sum), DT_NUMBER};
}, 2, 2);

• Arguments: args is a vector of var objects.
• Return value: return a var object representing the function result.
• Min and max arguments: define how many arguments are required.

3. Building a Module

1. Create a DLL project in Visual Studio (or your preferred C++ toolchain).
2. Include FunctionRegistry.h and link against XTML core library if needed.
3. Implement your module class as shown above.
4. Export the module class in a factory function:

extern "C" __declspec(dllexport) Module* CreateModule() {
    return new MyModule();
}

5. Build the DLL and place it in the modules folder of XTML (get created during the first start of xtml).

4. Using Module Functions in XTML

Once a module is loaded, its functions can be called inside <xtml> blocks:

<xtml>
    var result = native mymodule::add(10, 5); // returns 15
    print("Sum: " + result);
</xtml>

• Functions must be namespaced with the native keyword (e.g., native mymodule::add).

5. Notes & Best Practices

• Ensure functions handle incorrect argument types and count gracefully.
• Return meaningful error messages via Utils::printerrLn.
• Modules can provide any type of value (DT_NUMBER, DT_STRING, DT_ARRAY, DT_BOOL).
• Test modules thoroughly before release.

Modules make XTML highly extensible and allow you to integrate custom C++ functionality directly into templates.