scriban-js

A rigorous, 1:1 JavaScript port of the Scriban C# templating language engine.

This project provides the Lexer, Parser, and Abstract Syntax Tree (AST) for Scriban in pure JavaScript (ES6 Modules). It is primarily designed to power Code Editors (like Monaco) by providing real-time syntax validation, error reporting, and context-aware auto-completion without needing a backend server.

Live Demo

• Editor Demo: Try the Monaco integration.
• Test Suite: Verify the parser logic against regression tests.

Features

• Strict Parsing: Implements the full Scriban grammar including if, for, capture, wrap, func, and pipes |.
• Lexer Parity: Handles complex interpolation ($"text {code}"), whitespace control ({{-), and Liquid compatibility modes.
• Rich AST: Produces a full object-oriented syntax tree (not just simple tokens), allowing for deep static analysis.
• Editor Tooling:
  • Validator: Reports precise error locations (line/column).
  • Auto-Completion: Features a "Cursor Trap" parser that builds scope chains to suggest local loop variables ($i) and custom functions.

Usage

1. Basic Parsing

import { Lexer } from './src/parsing/Lexer.js';
import { Parser } from './src/parsing/Parser.js';

const code = `{{ for item in products; item.name; end }}`;

const lexer = new Lexer(code);
const parser = new Parser(lexer);

// Parse the code into an AST
const scriptPage = parser.run();

if (parser.hasErrors) {
    parser.messages.forEach(error => console.error(error.toString()));
} else {
    console.log("Parsed Successfully!");
}

2. Monaco Editor Integration

See index.html for a full example of hooking up the Validator and Completion Provider.

import { ScribanValidator } from './src/scriban-validator.js';
import { ScribanCompletionProvider } from './src/scriban-completion.js';

// ... Monaco setup ...
const validator = new ScribanValidator();
const completer = new ScribanCompletionProvider();

// Validate on change
editor.onDidChangeModelContent(() => {
    validator.validate(editor.getModel());
});

// Register Completion
monaco.languages.registerCompletionItemProvider('scriban', {
    provideCompletionItems: (model, position) => completer.provideCompletionItems(model, position)
});

Architecture & Porting Details

This project is a manual, logic-preserving port of the original C# source code. For details on how the C# recursive descent parser was translated to JavaScript mixins, and how the AST is structured, please read the Architecture Guide.

Credits

• Original Author: Alexandre Mutel (xoofx) for the incredible Scriban library.
• Port Maintainer: Abdullah bin Amir/Badal Technologies.

License

This project is licensed under the MIT License. See LICENSE for details.