papagaio 0.7.9 → 0.32.9

package/README.md

@@ -1,585 +1,325 @@
 # Papagaio
-Minimal yet powerful text preprocessor.
 
-- **It's portable!** papagaio requires only ES6 and nothing else.
-- **It's small!** papagaio is around ~250 lines and ~10kb.
-- **It's easy!** papagaio doesnt have any complicated stuff, 1 class and 1 method for doing everything!
-- **It's flexible!** do papagaio sigil and delimiters conflict with whatever you want to process? then simply change it! papagaio allow us to modify ANY of its keywords and symbols.
-- **It's powerful!!** aside been inspired by the m4 preprocessor and meant to be a preprocessor, papagaio still a fully-featured programming language because it can evaluate any valid javascript code using $eval;
+Papagaio is a C-first, embeddable text processing engine. It is designed to be highly modular and **script-agnostic**, allowing core pattern matching to be used alone or extended via WebAssembly (Wasm) plugins.
 
-## Installation
-```javascript
-import { Papagaio } from './papagaio.js';
-const papagaio = new Papagaio();
-const result = papagaio.process(input);
-```
-
-## Configuration
-```javascript
-papagaio.symbols = {
-  pattern: "pattern",      // pattern keyword
-  open: "{",               // opening delimiter (multi-char supported)
-  close: "}",              // closing delimiter (multi-char supported)
-  sigil: "$",              // variable marker
-  eval: "eval",            // eval keyword
-  block: "recursive",      // block keyword (recursive nesting)
-  regex: "regex",          // regex keyword
-  blockseq: "sequential"   // blockseq keyword (sequential blocks)
-};
-```
+## Key Features
 
----
+- **Lightweight Core**: Efficient C engine for pattern matching and transformation.
+- **Pattern-Matching**: Powerful capture system with built-in and custom modifiers.
+- **WebAssembly Plugins**: Highly secure, zero-dependency plugin architecture via an embedded `wasm3` runtime.
+- **Configurable Delimiters**: Redefine sigils, delimiters, and markers at runtime.
+- **Language Bindings**: Native usage in C and Node.js/WebAssembly.
 
-## Core Concepts
+## Quick Start
 
-### 1. Simple Variables
-```
-$pattern {$x} {$x}
-hello
-```
-Output: `hello`
-
-### 2. Multiple Variables
-```
-$pattern {$x $y $z} {$z, $y, $x}
-apple banana cherry
+### Command Line Interface (CLI)
+```sh
+# Process with patterns defined in the file or passed via -p
+papagaio -e '$pattern {hello $w} {Hi $w}' input.txt
 ```
-Output: `cherry, banana, apple`
 
----
-
-## Variables
-
-Papagaio provides flexible variable capture with automatic context-aware behavior.
-
-### `$x` - Smart Variable
-Automatically adapts based on context:
-- **Before a block**: Captures everything until the block's opening delimiter
-- **Before a literal**: Captures everything until that literal appears
-- **Otherwise**: Captures a single word (non-whitespace token)
-
-```
-$pattern {$x} {[$x]}
-hello world
-```
-Output: `[hello] [world]`
+### C API
+```c
+Papagaio *ctx = papagaio_open();
 
+char *out = papagaio_process_text(ctx, input_text, strlen(input_text));
+printf("%s", out);
+free(out);
+papagaio_close(ctx);
 ```
-$pattern {$name ${(}{)}content} {$name: $content}
-greeting (hello world)
-```
-Output: `greeting: hello world`
 
-```
-$pattern {$prefix:$suffix} {$suffix-$prefix}
-key:value
-```
-Output: `value-key`
-
-### `$x?` - Optional Variable
-Same behavior as `$x`, but won't fail if empty or not found.
+### JavaScript / WASM (Node.js)
+```javascript
+import Papagaio from './papagaio.js';
 
-```
-$pattern {$x? world} {<$x>}
-world
-```
-Output: `<>`
+const p = new Papagaio();
+await p.init();
+p.registerCommand("mycmd", (name, ...args) => `Result: ${args[0]}`);
 
+console.log(p.process('$mycmd{Hello}')); // Output: Result: Hello
 ```
-$pattern {$greeting? $name} {Hello $name$greeting}
-Hi John
-```
-Output: `Hello JohnHi`
 
 ---
 
-## Regex Matching
-
-Capture content using JavaScript regular expressions.
-
-### Syntax
-```
-$regex varName {pattern}
-```
-
-### Basic Example
-```
-$pattern {$regex num {[0-9]+}} {Number: $num}
-The answer is 42
-```
-Output: `Number: 42`
-
-### Complex Patterns
-```
-$pattern {$regex email {\w+@\w+\.\w+}} {Email found: $email}
-Contact: user@example.com
+## Pattern Syntax
+
+Patterns are composed of whitespace-separated tokens. The engine uses a "flex-matching" strategy that automatically skips horizontal whitespace between variables.
+
+- **Literal**: Matches exact text.
+- **Variable**: `$name` (captures a sequence up to the next pattern match).
+- **Optional**: `$name?` or `literal?` (marker is configurable, e.g., `MAYBE`, via `$changesymbols`).
+- **Escaping**: Use `$$` to match a literal `$`.
+
+### Modifiers
+Modifiers specify the data type or constraints of a match:
+- **Numbers**: `$var$int`, `$var$float`, `$var$number`
+- **Casing**: `$var$upper`, `$var$lower`, `$var$capitalized`
+- **Formats**: `$var$word`, `$var$identifier`, `$var$hex`, `$var$path`, `$var$binary`, `$var$percent`
+- **Regex**: `$id$regex{[0-9]+}`
+- **Block**: `$item$block{[}{]}` (captures everything between delimiters)
+- **Aliases**: `$kind$aliases{cat}{dog}{bird}` (multi-block syntax).
+- **Substrings**: `$var$starts{foo}`, `$var$ends{bar}`, `$var$prefix{p}`, `$var$suffix{s}`, `$var$infix{i}`, `$var$includes{x}`
+- **Grouping**: `$item$group{subpattern}` (recursive grouping, matches as one unit)
+- **Optionality**: any token (literal, variable, or group) can be made optional by adding `?` (or a custom marker like `MAYBE`).
+- **Trailing Sigil (whitespace collapse)**: appending a bare `$` (or the current sigil) directly after any variable or literal causes the matcher to **consume all following whitespace** in the input — making the adjacent `TOK_WS` optional. This is useful when the number of spaces between tokens is variable:
+  ```text
+  $pattern {$a$ $b} {$a/$b}
+  hello   world   → hello/world
+  ```
+  The trailing `$` after `$a` collapses any run of spaces/tabs/newlines between `$a` and `$b`.
+
+### Braced Variables
+
+When a captured variable name needs to be immediately followed by literal text (e.g., a suffix), wrap the name in `${...}` to prevent ambiguity:
+
+```text
+$pattern {$id$word} {${id}x}
+foo
+```
+*Output: `foox`* — without braces, `$idx` would be parsed as a single variable named `idx`.
+
+Braced syntax can be used in any replacement string:
+```text
+$pattern {$first $last} {Hello, ${first}!
+}
+John Doe
 ```
-Output: `Email found: user@example.com`
+*Output: `Hello, John!`*
 
-### Multiple Regex Variables
+### Nesting
+Modifiers support full recursive nesting:
+```text
+$pattern {$n$aliases{$x$int}{abc}} {VALUE: $n}
 ```
-$pattern {$regex year {[0-9]{4}}-$regex month {[0-9]{2}}} {Month $month in $year}
-2024-03
-```
-Output: `Month 03 in 2024`
 
 ---
 
-## Blocks
-
-Papagaio supports two types of block capture: **nested** and **adjacent**.
-
-### Nested Blocks - `${open}{close}varName`
-
-Captures content between delimiters with full nesting support. Nested delimiters are handled recursively.
-
-#### Basic Syntax
-```
-${opening_delimiter}{closing_delimiter}varName
-```
-
-#### Examples
-
-**Basic Recursive Block:**
-```
-$pattern {$name ${(}{)}content} {[$content]}
-data (hello world)
-```
-Output: `[hello world]`
-
-**Custom Delimiters:**
-```
-$pattern {${<<}{>>}data} {DATA: $data}
-<<json stuff>>
-```
-Output: `DATA: json stuff`
-
-**Multi-Character Delimiters:**
-```
-$pattern {${```}{```}code} {<pre>$code</pre>}
-```markdown
-# Title
-```
-Output: `<pre># Title</pre>`
-
-**Default Delimiters (empty blocks):**
-```
-$pattern {${}{}data} {[$data]}
-{hello world}
-```
-Output: `[hello world]`
-*(Uses default `{` and `}` when delimiters are empty)*
+## Extensibility (Wasm Plugins)
+
+Papagaio follows a Wasm-first plugin architecture. Core features are limited to pattern matching and transformation, while custom text processing capabilities are provided by WebAssembly plugins.
+
+### Built-in Operators
+- **`$document`**: Injects the current state of the document (alias for `$document$current`).
+- **`$document$original`**: Injects the initial, unprocessed input text. Useful for referencing the source even after multiple transformations.
+- **`$document$current`**: Injects the current state of the document during the pre-processing pass.
+- **`$wasm{path}`**: Loads a WebAssembly plugin from the file system (CLI only).
+- **$file{path}**: Injects the content of a file from the file system (CLI only).
+- **`$wat{source}`**: Compiles a WebAssembly Text Format (WAT) source string inline and registers all exported `papagaio_*` functions as commands. Useful for embedding lightweight plugins without an external `.wasm` file.
+- **`$NAME$from{value}`**: Dynamically assigns a processed `value` to `$NAME`. The assignment itself is suppressed from the output, and the variable becomes available for exact-match replacement in the remaining document.
+
+  ```text
+  $NAME$from{Alice}
+  Hello, $NAME!
+  ```
+  *Output: `Hello, Alice!`*
+
+  ```text
+  $wat{
+    (module
+      (func (export "papagaio_hello") (result i32)
+        i32.const 42))
+  }
+  $hello
+  ```
 
-**Nested Blocks:**
-```
-$pattern {${(}{)}outer} {[$outer]}
-(outer (inner (deep)))
-```
-Output: `[outer (inner (deep))]`
+---
 
-### Adjancent Blocks - `$${open}{close}varName`
+## CLI Argument Expansion
 
-Captures multiple adjacent blocks with the same delimiters and concatenates their content (separated by spaces).
+Papagaio can resolve command-line arguments directly within your source files. This is useful for passing configuration, flags, or metadata into the processing pipeline.
 
-#### Basic Syntax
-```
-$${opening_delimiter}{closing_delimiter}varName
-```
+### Positional Arguments
+The `argv` array maps as follows (where `argv[0]` is the binary name, invisible to Papagaio):
 
-#### Examples
+| Variable | Value |
+|---|---|
+| `$args$0` | `argv[1]` — the input file/script name |
+| `$args$1`, `$args$2`, … | Subsequent positional arguments |
+| `$args$count` | Total number of arguments (excludes the binary name, `argv[0]`) |
+| `$args$all` | All extra arguments from index 1 onwards (after the script), joined with spaces |
 
-**Basic Adjacent Block:**
-```
-$pattern {$${[}{]}items} {Items: $items}
-[first][second][third]
-```
-Output: `Items: first second third`
+If a `$args$NAME` variable is not found, it is emitted **literally** (e.g. `$args$missing` stays as-is).
 
-**Adjacent with Custom Delimiters:**
-```
-$pattern {$${<}{>}tags} {Tags: $tags}
-<html><body><div>
-```
-Output: `Tags: html body div`
+### Named Variables (Overrides)
+Arguments in the format `key=value` are automatically parsed and can be accessed in two ways:
+1. **Explicit**: `$args$key`
+2. **Direct**: `$key` (shorthand for `$args$key`)
 
-**Default Delimiters:**
-```
-$pattern {$${}{}data} {Result: $data}
-{a}{b}{c}
-```
-Output: `Result: a b c`
+Direct access (`$key`) will only resolve if `key` does not conflict with a registered command (like `$wasm`) or a built-in directive.
 
-**Mixed Usage:**
+#### Example:
+```sh
+./papagaiocc input.c version=1.2.3 target=wasm -O3
 ```
-$pattern {${(}{)}nested, $${[}{]}seq} {Nested: $nested | Seq: $seq}
-(a (b c)), [x][y][z]
+Inside `input.c`:
+```c
+const char *v = "$version"; // "1.2.3"
+const char *t = "$target";  // "wasm"
+const char *f = "$args$1";  // "-O3"
 ```
-Output: `Nested: a (b c) | Seq: x y z`
-
-### Block Comparison
-
-| Feature | Nested `${}{}var` | Adjacent `$${}{}var` |
-|---------|---------------------|------------------------|
-| Purpose | Capture nested content | Capture adjacent blocks |
-| Input | `[a [b [c]]]` | `[a][b][c]` |
-| Output | `a [b [c]]` | `a b c` |
-| Nesting | Handled recursively | Not nested, sequential |
-| Spacing | Preserves internal structure | Joins with spaces |
 
 ---
 
-## Pattern Scopes
+## Dynamic Customization
 
-Patterns defined within a replacement body create nested scopes with hierarchical inheritance.
+You can redefine the engine's syntax symbols at runtime using the atomic **`$changesymbols`** directive.
 
-### Basic Pattern
-```
-$pattern {hello} {world}
-hello
-```
-Output: `world`
+### `$changesymbols{sigil}{open}{close}{optional}`
+Default: `$changesymbols{$}{{} }{}}{?}`
 
-**Key Properties:**
-* Patterns are scoped to their context
-* Child patterns inherit parent patterns
-* Patterns do not persist between `process()` calls
-* Perfect for hierarchical transformations
-
-### Nested Patterns with Inheritance
-```
-$pattern {outer $x} {
-  $pattern {inner $y} {[$y from $x]}
-  inner $x
-}
-outer hello
+Example:
+```text
+$changesymbols{@}{<}{>}{!} @pattern <@n!> <ID: @n> [x] [y]
 ```
-Output: `[hello from hello]`
-
-The inner pattern has access to `$x` from the outer pattern's capture.
-
-### Deep Nesting
-```
-$pattern {level1 $a} {
-  $pattern {level2 $b} {
-    $pattern {level3 $c} {$a > $b > $c}
-    level3 $b
-  }
-  level2 $a
-}
-level1 ROOT
-```
-Output: `ROOT > ROOT > ROOT`
-
-Each nested level inherits all patterns from parent scopes.
-
-### Sibling Scopes Don't Share
-```
-$pattern {branch1} {
-  $pattern {x} {A}
-  x
-}
-$pattern {branch2} {
-  x
-}
-branch1
-branch2
-```
-Output:
-```
-A
-x
-```
-
-Patterns in `branch1` are not available in `branch2` (they are siblings, not parent-child).
+This changes the sigil to `@`, delimiters to `< >`, and the optional marker to `!`. Preprocessor directives (like `$changesymbols` itself) always use the stable `$` and `{}` to remain functional.
 
 ---
 
-## Special Keywords
+## Recursive Priority System
 
-### $eval
-Executes JavaScript code with access to the Papagaio instance.
+Papagaio allows you to control the order of execution and side-effects (such as pattern definitions or WASM loading) using the **`$priority$N`** directive.
 
-```
-$pattern {$x} {$eval{return parseInt($x)*2;}}
-5
-```
-Output: `10`
-
-**Accessing Papagaio Instance:**
-```
-$pattern {info} {$eval{
-  return `Content length: ${papagaio.content.length}`;
-}}
-info
-```
+- **`$priority$0{...}`**: Maximum priority.
+- **`$priority$max{...}`**: Alias for `INT_MIN + 1` (Absolute highest priority).
+- **`$priority$min{...}`**: Alias for `INT_MAX - 1` (Absolute lowest priority).
+- **`$priority$1`, `$priority$2`, ...**: Successively lower priorities.
+- **Recursive Evaluation**: Blocks with higher numerical priority (lower value) are fully processed — including their own nested patterns and commands — before any lower-priority blocks, regardless of their physical position in the file.
+- **Unspecified Priority**: Any text not wrapped in a `$priority` block is treated as priority `INT_MAX - 1` (processed last).
 
-**Multi-character delimiters:**
+#### Example:
+```text
+$priority$1{ Result: A }
+$priority$max{ $pattern{A}{OK} }
 ```
-$pattern {$x} {$eval<<parseInt($x)*2>>}
-5
-```
-Output: `10`
+*Output: `Result: OK`* — even though `A` is used before being defined in the source, the `$priority$max` block ensures the pattern definition happens first.
 
 ---
 
-## Important Rules
-
-### Variable Matching
-* `$x` = smart capture (context-aware: word, until literal, or until block)
-* `$x?` = optional version of `$x` (won't fail if empty)
-* `$regex name {pattern}` = regex-based capture
-* Variables automatically skip leading whitespace
-* Trailing whitespace is trimmed when variables appear before literals
-
-### Block Matching
-* `${open}{close}name` = nested block capture
-* `$${open}{close}name` = adjacent block capture (captures adjacent blocks)
-* Supports multi-character delimiters of any length
-* Empty delimiters `${}{}name` or `$${}{}name` use defaults from `symbols.open` and `symbols.close`
-* Sequential blocks are joined with spaces in the captured variable
+## Dynamic Variable Assignment ($from)
 
-### Pattern Matching
-* `$pattern {match} {replace}` = pattern scoped to current context
-* Patterns inherit from parent scopes hierarchically
-* Each `process()` call starts with a clean slate (no persistence)
-
----
+The **`$from`** operator allows you to capture processed content and assign it to a variable at runtime. This turns Papagaio into a stateful processor where variables can be defined, redefined, and chained.
 
-## Multi-Character Delimiter Support
+### Syntax
+`$NAME$from{...content...}`
 
-Papagaio fully supports multi-character delimiters throughout all features.
+1. **Recursive Processing**: The `content` is fully processed (patterns, WASM commands, other assignments) before being stored.
+2. **Immediate Registration**: The variable is registered as an exact-match rule as soon as it is parsed. This allows for **chained assignments**.
+3. **Output Suppression**: The entire `$from` directive is removed from the output text.
 
-### Configuration
-```javascript
-const p = new Papagaio('$', '<<<', '>>>');
-```
+### Examples
 
-### In Patterns
+#### Chained Assignments
+Variables can depend on previously defined variables within the same document:
+```text
+$A$from{1}
+$B$from{$A$A}
+Count: $B
 ```
-$pattern<<<$x>>> <<<[$x]>>>
-hello
-```
-Output: `[hello]`
+*Output: `Count: 11`*
 
-### In Blocks
-```
-$pattern<<<${<<}{>>}data>>> <<<$data>>>
-<<content>>
+#### Nested Assignments
+You can define internal variables while defining a larger block:
+```text
+$GREET$from{
+  $USER$from{Alice}
+  Hello, $USER!
+}
+$GREET
 ```
-Output: `content`
+*Output: `Hello, Alice!`*
 
-### In Eval
-```
-$pattern<<<$x>>> <<<$eval<<<return $x + 1>>>>>>
-5
+#### Interaction with Patterns
+Assignments can be used to dynamically generate pattern keys or replacements:
+```text
+$KEY$from{FOO}
+$pattern{$KEY}{BAR}
+Result: FOO
 ```
-Output: `6`
+*Output: `Result: BAR`*
 
 ---
 
-## Advanced Examples
+## Plugin Development
 
-### Markdown-like Processor
-```javascript
-const p = new Papagaio();
-const template = `
-$pattern {# $title} {<h1>$title</h1>}
-$pattern {## $title} {<h2>$title</h2>}
-$pattern {**$text**} {<strong>$text</strong>}
-
-# Hello World
-## Subtitle
-**bold text**
-`;
-
-p.process(template);
-// Output:
-// <h1>Hello World</h1>
-// <h2>Subtitle</h2>
-// <strong>bold text</strong>
-```
+Papagaio features a modern, frictionless Wasm plugin system. With the **`papagaiocc`** standalone compiler, you can write plugins in standard C using simple naming conventions and compile them into zero-dependency WebAssembly modules.
 
-### Array/List Processor
-```javascript
-const p = new Papagaio();
-const template = `
-$pattern {$${[}{]}items} {
-  $eval{
-    const arr = '$items'.split(' ');
-    return arr.map((x, i) => \`\${i + 1}. \${x}\`).join('\\n');
-  }
+### 1. Write your plugin
+Create a file named `greet.c`:
+```c
+// Functions starting with 'papagaio_' are automatically registered as commands
+char* papagaio_greet(int argc, char **argv)
+{
+    if (argc < 1) return "Hello, Stranger!";
+    return argv[0]; // return first argument
 }
-
-[apple][banana][cherry]
-`;
-
-p.process(template);
-// Output:
-// 1. apple
-// 2. banana
-// 3. cherry
 ```
 
-### Template System with State
-```javascript
-const p = new Papagaio();
-p.vars = {}; // Custom property for storing variables
-
-const template = `
-$pattern {var $name = $value} {$eval{
-  papagaio.vars['$name'] = '$value';
-  return '';
-}}
-$pattern {get $name} {$eval{
-  return papagaio.vars['$name'] || 'undefined';
-}}
-
-var title = My Page
-var author = John Doe
-Title: get title
-Author: get author
-`;
-
-p.process(template);
-// Output:
-// Title: My Page
-// Author: John Doe
-```
+To use the Papagaio Wasm SDK (`lib.c`), copy it from `examples/lib.c` into your project and include it explicitly:
+```c
+#include "lib.c"
 
-### Conditional Processing
-```javascript
-const p = new Papagaio();
-const template = `
-$pattern {if ${(}{)}cond then ${[}{]}yes else ${<}{>}no} {
-  $eval{
-    const condition = ($cond).trim();
-    return condition === 'true' ? '$yes' : '$no';
-  }
+char* papagaio_greet(int argc, char **argv)
+{
+    if (argc < 1) return "Hello, Stranger!";
+    
+    // lib.c provides standard C functions like malloc and sprintf
+    char *res = (char*)malloc(strlen(argv[0]) + 16);
+    sprintf(res, "Hello, %s!", argv[0]);
+    
+    return res;
 }
-
-if (true) then [yes branch] else <no branch>
-if (false) then [yes branch] else <no branch>
-`;
-
-p.process(template);
-// Output:
-// yes branch
-// no branch
 ```
 
-### Function-like Patterns
-```javascript
-const p = new Papagaio();
-const template = `
-$pattern {double $x} {$eval{return parseInt('$x') * 2}}
-$pattern {add $x $y} {$eval{return parseInt('$x') + parseInt('$y')}}
-
-double 5
-add 3 7
-add (double 4) 10
-`;
-
-p.process(template);
-// Output:
-// 10
-// 10
-// 18
-```
-
-### Sequential Block Processing
-```javascript
-const p = new Papagaio();
-const template = `
-$pattern {sum $${[}{]}nums} {
-  $eval{
-    const numbers = '$nums'.split(' ').map(x => parseInt(x));
-    return numbers.reduce((a, b) => a + b, 0);
-  }
-}
-
-sum [10][20][30][40]
-`;
-
-p.process(template);
-// Output: 100
+### 2. Compile with `papagaiocc`
+The `papagaiocc` tool is a self-contained compiler driver. Run it with your source file:
+```sh
+./papagaiocc greet.c
 ```
+This generates `greet.wasm`.
 
----
-
-## Troubleshooting
-
-| Problem | Solution |
-|---------|----------|
-| Variable not captured | Check context: use `$x?` for optional, or verify literals/blocks exist |
-| Block mismatch | Verify opening and closing delimiters match the declaration |
-| Infinite recursion | Pattern creates circular transformation; redesign pattern logic |
-| Pattern not matching | Verify whitespace between tokens, check if variable should be optional |
-| Pattern not available | Check scope hierarchy; patterns only inherit from parents, not siblings |
-| Nested blocks fail | Ensure delimiters are properly balanced |
-| Multi-char delimiters broken | Check delimiters don't conflict; use escaping if needed |
-| Regex not matching | Test regex pattern separately; ensure it matches at the exact position |
-| Empty delimiter behavior | `${}{}x` uses defaults; explicitly set if you need different behavior |
-
----
-
-## Syntax Reference
-
+If your plugin uses `lib.c`, pass the directory containing it via `-I`:
+```sh
+./papagaiocc greet.c -I /path/to/lib
 ```
-$pattern {$x $y} {$y, $x}            # pattern with variables
-$pattern {$x? $y} {$y, $x}           # optional variable
-$pattern {$regex n {[0-9]+}} {$n}    # regex capture
-$pattern {${o}{c}n} {$n}             # recursive block (nested)
-$pattern {$${o}{c}n} {$n}            # sequential block (adjacent)
-$pattern {${}{}n} {$n}               # block with default delimiters
-$eval{code}                          # JavaScript evaluation
+Or simply place `lib.c` in the same directory as `greet.c`:
+```sh
+# Copy the SDK alongside your source
+cp examples/lib.c .
+./papagaiocc greet.c
 ```
 
----
-
-## API Reference
-
-### Constructor
-```javascript
-new Papagaio(sigil, open, close, pattern, evalKw, blockKw, regexKw, blockseqKw)
+### 3. Use in Papagaio
+Loading the Wasm file automatically registers all exported commands.
+```text
+$wasm{greet.wasm}
+$greet{Papagaio}
 ```
+*Output: Hello, Papagaio!*
 
-**Parameters:**
-- `sigil` (default: `'$'`) - Variable prefix
-- `open` (default: `'{'`) - Opening delimiter
-- `close` (default: `'}'`) - Closing delimiter
-- `pattern` (default: `'pattern'`) - Pattern keyword
-- `evalKw` (default: `'eval'`) - Eval keyword
-- `regexKw` (default: `'regex'`) - Regex keyword
-
-### Properties
-- `papagaio.content` - Last processed output
-- `papagaio.match` - Last matched substring (available in replacements)
-- `papagaio.symbols` - Configuration object
-- `papagaio.exit` - Optional hook function called after processing
-
-### Methods
-- `papagaio.process(input)` - Process input text and return transformed output
-
-### Exit Hook
-```javascript
-const p = new Papagaio();
-p.exit = function() {
-  console.log('Processing complete:', this.content);
-};
-p.process('$pattern {x} {y}\nx');
-```
+### Wasm SDK (lib.c)
+The Wasm SDK lives at `examples/lib.c` inside the repository. It is **not** automatically embedded into `papagaiocc` — you supply it to your plugin's build as needed. It provides a curated, zero-dependency C standard library for WebAssembly, including:
+- **Memory Management**: `malloc`, `free`, `realloc`
+- **String Processing**: `strlen`, `strcpy`, `sprintf`, `strrev`, etc.
+- **Formatted I/O**: `printf`, `snprintf`, `sscanf`
+- **Standard Math**: `sin`, `cos`, `pow`, etc.
 
 ---
 
-## Performance Notes
+## Building
 
-* Multi-character delimiter matching is optimized with substring operations
-* Sequential blocks scan for adjacent matches without recursion overhead
-* Nested patterns inherit parent patterns through recursive application
-* Nested blocks and patterns have no theoretical depth limit
-* Large recursion limits can impact performance on complex inputs
-* Each `process()` call is independent with no persistent state between calls
+```sh
+make            # Core & CLI
+make papagaiocc # Standalone plugin compiler
+make wasm       # WebAssembly build (Papagaio in the browser/node)
+make test       # Run comprehensive test suite
+```
 
----
+## References
 
-***PAPAGAIO IS CURRENTLY IN HEAVY DEVELOPMENT AND EXPERIMENTATION PHASE***
+- [cpp](https://en.wikipedia.org/wiki/C_preprocessor)
+- [m4](https://www.gnu.org/software/m4/)
+- [libregexp](https://bellard.org/quickjs/)
+- [quickjs](https://bellard.org/quickjs/)
+- [tcc](https://bellard.org/tcc/)
+- [wasm3](https://github.com/wasm3/wasm3)
+- [watr](https://github.com/dy/watr)