meld
Version:
Meld: A template language for LLM prompts
236 lines (205 loc) • 8.29 kB
HTML
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Meld SDK Usage - meld</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Tektur:wght@800&family=Cousine:wght@400;700&display=swap" rel="stylesheet">
<link rel="stylesheet" href="/css/style.css">
<script src="/js/theme.js" defer></script>
<script src="/js/terminal.js" defer></script>
</head>
<body>
<header>
<div class="container">
<a href="/" class="logo">meld</a>
<nav>
<ul>
<li><a href="/" aria-current="page">Home</a></li>
<li><a href="/docs/introduction/" >Docs</a></li>
<li><a href="https://github.com/meldorg/meld">GitHub</a></li>
</ul>
</nav>
</div>
</header>
<main>
<div class="container">
<div class="docs-layout">
<aside class="docs-sidebar">
<nav>
<h3>Documentation</h3>
<ul class="nav-list">
<li><a href="/docs/introduction/" >Introduction</a></li>
<li><a href="/docs/cli-usage/" >CLI Usage</a></li>
<li><a href="/docs/sdk-usage/" aria-current="page">SDK Usage</a></li>
<li><a href="/docs/variables/" >Variables</a></li>
<li><a href="/docs/error-handling/" >Error Handling</a></li>
<li><a href="/docs/grammar-reference/" >Grammar Reference</a></li>
</ul>
<h3>Directives</h3>
<ul class="nav-list">
<li><a href="/docs/directives/" >Overview</a></li>
<li><a href="/docs/directives/data/" >@data</a></li>
<li><a href="/docs/directives/define/" >@define</a></li>
<li><a href="/docs/directives/embed/" >@embed</a></li>
<li><a href="/docs/directives/import/" >@import</a></li>
<li><a href="/docs/directives/path/" >@path</a></li>
<li><a href="/docs/directives/run/" >@run</a></li>
<li><a href="/docs/directives/text/" >@text</a></li>
</ul>
</nav>
</aside>
<div class="docs-content">
<h1 id="meld-sdk-usage" tabindex="-1">Meld SDK Usage</h1>
<p>The Meld SDK allows you to integrate Meld processing into your JavaScript or TypeScript applications.</p>
<h2 id="installation" tabindex="-1">Installation</h2>
<pre><code class="language-bash">npm install meld
</code></pre>
<h2 id="core-functions" tabindex="-1">Core Functions</h2>
<p>The SDK provides three main functions for working with Meld content:</p>
<h3 id="parse-meld-content" tabindex="-1">Parse Meld Content</h3>
<p>Parse raw Meld content into an Abstract Syntax Tree (AST):</p>
<pre><code class="language-typescript">import { parseMeld } from 'meld';
const content = `
@text name = "World"
Hello, {{name}}!
`;
const nodes = parseMeld(content);
</code></pre>
<p>The parsed AST contains nodes representing directives and text content, which can be further processed or manipulated.</p>
<h3 id="interpret-meld-ast" tabindex="-1">Interpret Meld AST</h3>
<p>Interpret parsed AST nodes with optional initial state:</p>
<pre><code class="language-typescript">import { interpretMeld, InterpreterState } from 'meld';
// Create initial state (optional)
const initialState = new InterpreterState();
initialState.setText('greeting', 'Hi');
// Interpret the nodes
const finalState = interpretMeld(nodes, initialState);
</code></pre>
<p>Interpretation executes directives, resolves variables, and produces a final state containing all defined variables and the processed content.</p>
<h3 id="run-meld-files" tabindex="-1">Run Meld Files</h3>
<p>Convenience function to read and interpret Meld files in one step:</p>
<pre><code class="language-typescript">import { runMeld } from 'meld';
// Run with default options (XML format)
const { state, output } = await runMeld('path/to/file.meld');
// Run with custom options
const { state, output } = await runMeld('path/to/file.meld', {
format: 'md', // or 'xml'
initialState: new InterpreterState()
});
// Use the state for further operations
console.log(state.getVariables());
// Use the formatted output
console.log(output);
</code></pre>
<h2 id="working-with-state" tabindex="-1">Working with State</h2>
<p>The <code>InterpreterState</code> class manages variables, commands, and content during interpretation:</p>
<pre><code class="language-typescript">import { InterpreterState } from 'meld';
// Create new state
const state = new InterpreterState();
// Set and get text variables
state.setText('name', 'Alice');
const name = state.getText('name');
// Set and get data variables
state.setData('user', { name: 'Alice', id: 123 });
const user = state.getData('user');
// Set and get path variables
state.setPath('docs', '/path/to/docs');
const docsPath = state.getPath('docs');
// Get all variables
const variables = state.getVariables();
</code></pre>
<h2 id="error-handling" tabindex="-1">Error Handling</h2>
<p>The SDK provides specialized error types for robust error handling:</p>
<pre><code class="language-typescript">import {
parseMeld,
MeldParseError,
MeldInterpreterError,
MeldFileNotFoundError,
MeldError
} from 'meld';
try {
const nodes = parseMeld(invalidContent);
} catch (error) {
if (error instanceof MeldParseError) {
console.error('Parse error:', error.message);
console.error('Line:', error.line);
console.error('Column:', error.column);
} else if (error instanceof MeldInterpreterError) {
console.error('Interpreter error:', error.message);
} else if (error instanceof MeldFileNotFoundError) {
console.error('File not found:', error.message);
} else if (error instanceof MeldError) {
console.error('General Meld error:', error.message);
} else {
console.error('Unknown error:', error);
}
}
</code></pre>
<h2 id="advanced-usage" tabindex="-1">Advanced Usage</h2>
<h3 id="custom-format-handlers" tabindex="-1">Custom Format Handlers</h3>
<p>You can register custom format handlers for variable formatting:</p>
<pre><code class="language-typescript">import { registerFormatHandler } from 'meld';
// Register a custom format handler
registerFormatHandler('uppercase', (value) => {
return String(value).toUpperCase();
});
// Now you can use it in Meld code
// @text name = "alice"
// @text greeting = `Hello, {{name>>(uppercase)}}!`
// Result: "Hello, ALICE!"
</code></pre>
<h3 id="file-system-customization" tabindex="-1">File System Customization</h3>
<p>You can provide custom file system handlers for testing or special environments:</p>
<pre><code class="language-typescript">import { runMeld, createMemoryFileSystem } from 'meld';
// Create an in-memory file system for testing
const memfs = createMemoryFileSystem({
'/test/file.md': 'This is a test file',
'/test/data.json': '{"key": "value"}'
});
// Use the custom file system
const { state, output } = await runMeld('path/to/file.meld', {
fileSystem: memfs
});
</code></pre>
<h2 id="integration-example" tabindex="-1">Integration Example</h2>
<p>Here's a complete example of integrating Meld into an application:</p>
<pre><code class="language-typescript">import { parseMeld, interpretMeld, InterpreterState } from 'meld';
import * as fs from 'fs';
// Read a Meld file
const content = fs.readFileSync('template.meld', 'utf-8');
try {
// Parse the content
const nodes = parseMeld(content);
// Create initial state with user data
const state = new InterpreterState();
state.setText('username', 'Alice');
state.setData('userData', {
id: 12345,
role: 'admin',
preferences: { theme: 'dark' }
});
// Interpret the nodes
const finalState = interpretMeld(nodes, state);
// Get the processed content
const result = finalState.getContent();
// Output the result
fs.writeFileSync('output.md', result, 'utf-8');
console.log('Processing complete!');
} catch (error) {
console.error('Error processing Meld file:', error.message);
}
</code></pre>
</div>
</div>
</div>
</main>
<footer>
<div class="container">
<p>© 2025 meld - <a href="https://github.com/meldorg/meld">GitHub</a></p>
</div>
</footer>
</body>
</html>