meld

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>@run 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/" >@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/" aria-current="page">@run</a></li> <li><a href="/docs/directives/text/" >@text</a></li> </ul> </nav> </aside> <div class="docs-content"> <h1 id="%40run-directive" tabindex="-1">@run Directive</h1> <p>The <code>@run</code> directive executes shell commands and includes their output in your Meld document.</p> <h2 id="syntax" tabindex="-1">Syntax</h2> <pre><code class="language-meld">@run [command_text] @run [command_text] under header_text @run [$command({{textvar1}}, {{textvar2}})] </code></pre> <p>Where:</p> <ul> <li><code>command_text</code> is the shell command to execute</li> <li><code>header_text</code> is optional text to use as a header for the command output</li> <li><code>$command</code> refers to a command defined with <code>@define</code></li> </ul> <h2 id="command-specification" tabindex="-1">Command Specification</h2> <p>The command can be:</p> <ul> <li>A literal command: <code>@run [ls -la]</code></li> <li>A command with variables: <code>@run [echo "Hello, {{name}}"]</code></li> <li>A command with path variables: <code>@run [cat $docs/guide.md]</code></li> <li>A defined command: <code>@run [$listFiles($path)]</code></li> </ul> <h2 id="variables-in-commands" tabindex="-1">Variables in Commands</h2> <p>You can use different types of variables in commands:</p> <ul> <li>Text variables: <code>{{textvar}}</code></li> <li>Path variables: <code>$path</code></li> <li>Special path variables: <code>$HOMEPATH</code>, <code>$~</code>, <code>$PROJECTPATH</code>, <code>$.</code></li> <li>Command references: <code>$command({{param1}}, {{param2}})</code></li> </ul> <h2 id="output-handling" tabindex="-1">Output Handling</h2> <p>By default, the command's standard output (stdout) is captured and included in your document. Additionally:</p> <ul> <li>Standard error (stderr) is also captured and can be included</li> <li>In transformation mode, the stdout (and sometimes stderr) replaces the directive node</li> <li>The output can be assigned to a variable: <code>@text result = @run [command]</code></li> </ul> <h2 id="adding-headers" tabindex="-1">Adding Headers</h2> <p>You can add a header to command output using the <code>under</code> keyword:</p> <pre><code class="language-meld">@run [date] under Current Date </code></pre> <p>This will add a header "Current Date" above the command output.</p> <h2 id="error-handling" tabindex="-1">Error Handling</h2> <p>The implementation handles these error scenarios:</p> <ul> <li>Missing or empty command</li> <li>Command execution failures</li> <li>Commands that exit with non-zero status codes</li> </ul> <h2 id="examples" tabindex="-1">Examples</h2> <p>Basic command execution:</p> <pre><code class="language-meld">@run [echo "Hello, World!"] </code></pre> <p>Using variables in commands:</p> <pre><code class="language-meld">@text name = "Alice" @run [echo "Hello, {{name}}!"] </code></pre> <p>Using path variables:</p> <pre><code class="language-meld">@path src = "$PROJECTPATH/src" @run [ls -la $src] </code></pre> <p>Using command output in variables:</p> <pre><code class="language-meld">@text date = @run [date +"%Y-%m-%d"] @data files = @run [ls -la | jq -R -s -c 'split("\n")[:-1]'] </code></pre> <p>Adding headers to output:</p> <pre><code class="language-meld">@run [git status] under Repository Status </code></pre> <p>Using defined commands:</p> <pre><code class="language-meld">@define listFiles(dir) = @run [ls -la {{dir}}] @run [$listFiles($PROJECTPATH)] </code></pre> <h2 id="environment-%26-working-directory" tabindex="-1">Environment & Working Directory</h2> <ul> <li>Commands execute in the environment of the Meld process</li> <li>The working directory defaults to the current working directory</li> <li>Environment variables are available to the command</li> </ul> <h2 id="notes" tabindex="-1">Notes</h2> <ul> <li>Command execution is performed in a separate process using Node.js child_process.exec</li> <li>Commands that exit with non-zero status will generate errors</li> <li>The directive doesn't have built-in timeout mechanisms for long-running commands</li> <li>Command output is always converted to string (binary output may not be properly handled)</li> <li>The directive does not support interactive commands that require user input</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>