Quick Start Guide

Installation

# One-line install (downloads latest release)
curl -fsSL https://raw.githubusercontent.com/akaoio/xmd/main/install.sh | bash

# Verify installation
xmd version

Updating XMD

# Upgrade to latest release
xmd upgrade

# Check current version
xmd version

Basic Usage

1. Create a simple XMD file

Create example.md:

<!-- xmd:
set name = "Developer"
set date = exec date +"%Y-%m-%d"
-->

# Hello !

Today is .

<!-- xmd: for i in 1..3 -->
- Item 
<!-- xmd: endfor -->

2. Process the file

# Output to stdout
xmd example.md

# Save to file
xmd example.md -o output.md

# Watch mode for real-time updates
xmd watch src/ dist/

# Use with variables
xmd example.md -v name="Alice"

Key Concepts

Variables

<!-- xmd: set user = "John" -->
<!-- xmd: set count = 42 -->
<!-- xmd: set active = true -->

Advanced Scripting Features

Array Literals and Iteration

<!-- xmd:
set technologies = ["C", "JavaScript", "Python", "Go"]
set content = ""
for tech in technologies
    content += "- **" + tech + "** programming language\n"
-->
<article class="post">

  <header class="post-header">
    <h1 class="post-title">Test Migration to AST Functions</h1>
  </header>

  <div class="post-content">
    <h1 id="test-migration-to-ast-functions">Test Migration to AST Functions</h1>

<h2 id="overview">Overview</h2>
<p>Before we can purge legacy string parsers, we must migrate all tests to use AST functions.</p>

<h2 id="tests-requiring-migration">Tests Requiring Migration</h2>

<h3 id="1-testintegrationtest_advanced_integrationc">1. test/integration/test_advanced_integration.c</h3>
<ul>
  <li><strong>Currently uses</strong>: <code class="language-plaintext highlighter-rouge">process_xmd_content_enhanced()</code></li>
  <li><strong>Migrate to</strong>: <code class="language-plaintext highlighter-rouge">ast_process_xmd_content()</code></li>
  <li><strong>Notes</strong>: May use enhanced features - verify AST supports all functionality</li>
</ul>

<h3 id="2-teststresstest_brutal_nestingc">2. test/stress/test_brutal_nesting.c</h3>
<ul>
  <li><strong>Currently uses</strong>: <code class="language-plaintext highlighter-rouge">process_xmd_content()</code></li>
  <li><strong>Migrate to</strong>: <code class="language-plaintext highlighter-rouge">ast_process_xmd_content()</code></li>
  <li><strong>Notes</strong>: Stress test - ensure AST handles deep nesting</li>
</ul>

<h3 id="3-teststresstest_resource_exhaustionc">3. test/stress/test_resource_exhaustion.c</h3>
<ul>
  <li><strong>Currently uses</strong>: <code class="language-plaintext highlighter-rouge">process_xmd_content()</code></li>
  <li><strong>Migrate to</strong>: <code class="language-plaintext highlighter-rouge">ast_process_xmd_content()</code></li>
  <li><strong>Notes</strong>: Resource limits test - verify AST respects limits</li>
</ul>

<h3 id="4-testxmd_processortest_advanced_scriptingc">4. test/xmd_processor/test_advanced_scripting.c</h3>
<ul>
  <li><strong>Currently uses</strong>: Legacy string parser functions</li>
  <li><strong>Migrate to</strong>: AST equivalents</li>
  <li><strong>Notes</strong>: Complex scripting scenarios</li>
</ul>

<h3 id="5-testxmd_processortest_xmd_processorc">5. test/xmd_processor/test_xmd_processor.c</h3>
<ul>
  <li><strong>Currently uses</strong>: <code class="language-plaintext highlighter-rouge">process_xmd_content()</code></li>
  <li><strong>Migrate to</strong>: <code class="language-plaintext highlighter-rouge">ast_process_xmd_content()</code></li>
  <li><strong>Notes</strong>: Core processor tests - critical to migrate correctly</li>
</ul>

<h3 id="6-testxmd_processortest_truncate_fixc">6. test/xmd_processor/test_truncate_fix.c</h3>
<ul>
  <li><strong>Currently uses</strong>: Legacy functions</li>
  <li><strong>Migrate to</strong>: AST functions</li>
  <li><strong>Notes</strong>: Tests truncation handling</li>
</ul>

<h2 id="migration-steps">Migration Steps</h2>

<ol>
  <li><strong>Function Signature Changes</strong>:
    <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Old: process_xmd_content(input, variables)</span>
<span class="c1">// New: ast_process_xmd_content(input, variables)</span>
</code></pre></div>    </div>
  </li>
  <li><strong>Include Updates</strong>:
    <div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Remove: #include "process_xmd_content.h"</span>
<span class="c1">// Add: #include "ast_process_xmd_content.h"</span>
</code></pre></div>    </div>
  </li>
  <li><strong>Variable Store Changes</strong>:
    <ul>
      <li>AST functions use the same <code class="language-plaintext highlighter-rouge">store*</code> type</li>
      <li>No changes needed for variable handling</li>
    </ul>
  </li>
  <li><strong>Output Handling</strong>:
    <ul>
      <li>AST functions return allocated strings</li>
      <li>Remember to free the result</li>
    </ul>
  </li>
</ol>

<h2 id="testing-migration-success">Testing Migration Success</h2>

<ol>
  <li>Run each test individually after migration</li>
  <li>Compare output with legacy function results</li>
  <li>Ensure all edge cases still pass</li>
  <li>Check memory usage hasn’t increased significantly</li>
</ol>

<h2 id="blocked-by">Blocked By</h2>

<ul>
  <li>Library build failure (libxmd_lib.a not created)</li>
  <li>Test executables not being generated</li>
  <li>Need BO to fix build system first</li>
</ul>

<h2 id="team-assignments">Team Assignments</h2>

<ul>
  <li><strong>XOAI</strong>: Document migration requirements (COMPLETE)</li>
  <li><strong>BO</strong>: Fix build system, then help migrate tests</li>
  <li><strong>CAM</strong>: Validate migrated tests produce same results</li>
  <li><strong>DADDY</strong>: Coordinate migration effort</li>
</ul>

<hr />
<p><em>Created by XOAI for team reference</em></p>

  </div>

</article>

Dynamic Imports

<!-- xmd:
set sections = ["intro.md", "setup.md", "usage.md"]
set documentation = ""
for section in sections
    documentation += import section + "\n\n"
-->

String Concatenation

<!-- xmd:
set title = "XMD Guide"
set version = "v2.0"
set header = "# " + title + " " + version
-->

Command Execution

<!-- xmd: exec ls -la -->
<!-- xmd: set files = exec find . -name "*.md" -->

Functions

<!-- xmd:
set data = "Hello World"
print(data)
-->

<!-- xmd: cmd("echo 'Hello from cmd!'") -->

Complex Multiline Scripts

<!-- xmd:
set project_files = ["README.md", "CHANGELOG.md", "LICENSE.md"]
set toc = "# Table of Contents\n\n"
for file in project_files
    toc += "- [" + file + "](" + file + ")\n"
-->

Next Steps