meld

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>@define Directive - 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/" >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/" aria-current="page">Overview</a></li> <li><a href="/docs/directives/data/" >@data</a></li> <li><a href="/docs/directives/define/" aria-current="page">@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="%40define-directive" tabindex="-1">@define Directive</h1> <p>The <code>@define</code> directive creates reusable commands that can be referenced in <code>@run</code> directives.</p> <h2 id="syntax" tabindex="-1">Syntax</h2> <pre><code class="language-meld">@define command = @run [content] @define command(param1, param2) = @run [content {{param1}} {{param2}}] @define command.about = "description" @define command.meta = "description" </code></pre> <p>Where:</p> <ul> <li><code>command</code> is the name of the command (must be a valid identifier)</li> <li><code>param1</code>, <code>param2</code>, etc. are parameter names (must be valid identifiers)</li> <li><code>content</code> is the command content (following @run patterns)</li> <li>Field metadata is limited to specific fields (.about, .meta)</li> </ul> <h2 id="identifier-requirements" tabindex="-1">Identifier Requirements</h2> <ul> <li>Command names must start with a letter or underscore</li> <li>Can contain letters, numbers, and underscores</li> <li>Case-sensitive</li> <li>Cannot be empty</li> </ul> <h2 id="command-parameters" tabindex="-1">Command Parameters</h2> <p>Parameters are defined in parentheses and must be referenced in the command body:</p> <pre><code class="language-meld">@define greet(name) = @run [echo "Hello, {{name}}!"] </code></pre> <p>Parameter rules:</p> <ul> <li>Names must follow identifier rules (start with letter/underscore)</li> <li>All parameters defined must be used in the command body</li> <li>All parameters referenced in the command must be declared</li> <li>No duplicate parameter names are allowed</li> <li>Parameters are referenced using <code>{{paramName}}</code> syntax</li> <li>Parameters are required when calling the command</li> </ul> <pre><code class="language-meld">@text user = "Alice" @run [$greet({{user}})] </code></pre> <h2 id="command-body-requirements" tabindex="-1">Command Body Requirements</h2> <ul> <li>The right-hand side must be an @run directive, not other directive types</li> <li>The command itself is the content inside the @run brackets</li> <li>Empty commands are technically allowed but will result in empty content</li> </ul> <h2 id="command-metadata" tabindex="-1">Command Metadata</h2> <p>You can add metadata to commands using the field syntax:</p> <pre><code class="language-meld">@define listFiles(dir) = @run [ls -la {{dir}}] @define listFiles.about = "Lists all files in the specified directory" </code></pre> <p>Supported metadata fields:</p> <ul> <li><code>.about</code> - Command description</li> <li><code>.meta</code> - Additional metadata</li> </ul> <h2 id="examples" tabindex="-1">Examples</h2> <p>Basic command definition:</p> <pre><code class="language-meld">@define sayHello = @run [echo "Hello, World!"] @run [$sayHello] </code></pre> <p>Command with parameters:</p> <pre><code class="language-meld">@define greet(name, greeting) = @run [echo "{{greeting}}, {{name}}!"] @text user = "Alice" @run [$greet({{user}}, "Hi")] </code></pre> <p>Command with path variables:</p> <pre><code class="language-meld">@define listDir(dir) = @run [ls -la {{dir}}] @path src = "$PROJECTPATH/src" @run [$listDir($src)] </code></pre> <p>Command with metadata:</p> <pre><code class="language-meld">@define runScript(script) = @run [bash {{script}}] @define runScript.about = "Executes a bash script" </code></pre> <h2 id="error-handling" tabindex="-1">Error Handling</h2> <p>The implementation handles these error scenarios:</p> <ul> <li>Invalid directive structure</li> <li>Duplicate parameter names</li> <li>Invalid parameter names</li> <li>Unreferenced parameters (defined but not used)</li> <li>Undeclared parameters (used but not defined)</li> <li>Invalid metadata fields</li> </ul> <h2 id="notes" tabindex="-1">Notes</h2> <ul> <li>The right-hand side of @define must be an @run directive</li> <li>Cannot use other directives (@embed, @text, etc.) as the command body</li> <li>Command parameters are required when calling the command</li> <li>Commands can only be used within @run directives</li> <li>Metadata fields are restricted to specific field names</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>