meld
Version:
Meld: A template language for LLM prompts
136 lines (130 loc) • 5.82 kB
HTML
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Error Handling in Meld - 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/" >SDK Usage</a></li>
<li><a href="/docs/variables/" >Variables</a></li>
<li><a href="/docs/error-handling/" aria-current="page">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="error-handling-in-meld" tabindex="-1">Error Handling in Meld</h1>
<p>Meld has a structured approach to error handling, categorizing errors into different severity levels.</p>
<h2 id="error-categories" tabindex="-1">Error Categories</h2>
<h3 id="fatal-errors-(halt-execution)" tabindex="-1">Fatal Errors (Halt Execution)</h3>
<p>These errors stop Meld execution immediately:</p>
<ul>
<li>Missing or inaccessible referenced files</li>
<li>Invalid syntax in Meld files</li>
<li>Invalid file extensions</li>
<li>Circular imports</li>
<li>Type mismatches (using wrong variable type)</li>
<li>Missing required command parameters</li>
<li>Invalid path references (not using $HOMEPATH/$PROJECTPATH)</li>
</ul>
<h3 id="warning-errors-(continue-with-warning)" tabindex="-1">Warning Errors (Continue with Warning)</h3>
<p>These issues generate warnings but allow execution to continue:</p>
<ul>
<li>Missing optional fields in data structures (returns empty string)</li>
<li>Missing environment variables (when referenced)</li>
<li>Command execution that produces stderr but exits with code 0</li>
<li>Fields accessed on non-existent data paths (returns empty string)</li>
</ul>
<h3 id="silent-operation-(no-error%2Fwarning)" tabindex="-1">Silent Operation (No Error/Warning)</h3>
<p>These situations don't generate errors or warnings:</p>
<ul>
<li>Expected stderr output from successfully running commands</li>
<li>Empty or partial results from valid operations</li>
<li>Type coercion in string concatenation</li>
<li>Normal command output to stderr</li>
</ul>
<h2 id="common-error-scenarios" tabindex="-1">Common Error Scenarios</h2>
<h3 id="file-system-errors" tabindex="-1">File System Errors</h3>
<ul>
<li><strong>Missing Files</strong>: When an <code>@embed</code> or <code>@import</code> directive references a non-existent file</li>
<li><strong>Path Validation</strong>: When paths don't use <code>$HOMEPATH</code> or <code>$PROJECTPATH</code></li>
<li><strong>File Permission Issues</strong>: When Meld can't read a referenced file</li>
</ul>
<h3 id="syntax-errors" tabindex="-1">Syntax Errors</h3>
<ul>
<li><strong>Invalid Directive Syntax</strong>: Malformed directives or missing required components</li>
<li><strong>Invalid Variable References</strong>: Using variables that haven't been defined</li>
<li><strong>Quoting Issues</strong>: Mismatched quotes or invalid string formats</li>
</ul>
<h3 id="execution-errors" tabindex="-1">Execution Errors</h3>
<ul>
<li><strong>Command Failures</strong>: When an <code>@run</code> command exits with a non-zero status</li>
<li><strong>Circular Imports</strong>: When Meld detects circular file imports</li>
<li><strong>Type Mismatches</strong>: Using the wrong variable type in a context</li>
</ul>
<h2 id="error-recovery" tabindex="-1">Error Recovery</h2>
<p>Meld attempts to recover from non-fatal errors by:</p>
<ul>
<li>Substituting empty strings for missing data fields</li>
<li>Continuing past warnings when possible</li>
<li>Providing detailed error messages with line numbers and context</li>
</ul>
<h2 id="best-practices" tabindex="-1">Best Practices</h2>
<ul>
<li>Always check that referenced files exist</li>
<li>Use path variables consistently</li>
<li>Validate command exit codes</li>
<li>Handle optional data fields gracefully</li>
<li>Check for environment variables before using them</li>
<li>Test Meld scripts with error cases to ensure proper handling</li>
</ul>
</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>