papagaio 0.1.8 → 0.2.3

package/README.md

@@ -1,336 +1,357 @@
-# Papagaio Preprocessor
+# Papagaio
 
-Papagaio is a lightweight, class‑based text preprocessor designed to support pattern rewriting, macro expansion, scoped transforms, and embedded JavaScript evaluation. It is engineered to be predictable, recursion‑safe, and easily embeddable in any JavaScript runtime.
-
----
-
-## Overview
-
-Papagaio processes an input string through a deterministic multi‑stage pipeline:
-
-1. **Scope blocks** (recursive processing)
-2. **Eval blocks** (JS execution)
-3. **Macro collection**
-4. **Pattern collection**
-5. **Pattern application**
-6. **Macro expansion**
-
-The engine runs until it reaches a fixed point or hits the recursion limit.
-
-Papagaio supports **nested delimiters**, **custom sigils**, and **configurable keywords**.
-
----
+Minimal yet powerful text preprocessor.
 
 ## Installation
 
-Papagaio ships as a standalone ES module.
-
-```js
-import { Papagaio } from "./papagaio.js";
+```javascript
+import { Papagaio } from './src/papagaio.js';
+const p = new Papagaio();
+const result = p.process(input);
 ```
 
----
-
-## Basic Usage
+## Configuration
 
-```js
-const p = new Papagaio();
-const output = p.process("pattern {a} {b}  a a a");
-console.log(output); // "b b b"
+```javascript
+p.open = "{";           // opening delimiter
+p.close = "}";          // closing delimiter
+p.sigil = "$";          // variable marker
+p.maxRecursion = 512;   // iteration limit
 ```
 
 ---
 
-## Core Features
+## Core Concepts
 
-### 1. Pattern Blocks
-
-Patterns rewrite text using a match → replacement structure:
+### 1. Simple Variables
 
 ```
-pattern { MATCH } { REPLACEMENT }
+pattern {$x} {$x}
+hello
 ```
+Output: `hello`
 
-Patterns are collected once per iteration and applied globally.
+Variables capture words (non-whitespace sequences).
 
-Example:
+### 2. Multiple Variables
 
 ```
-pattern {hello} {hi}
-hello world
+pattern {$x $y $z} {$z, $y, $x}
+apple banana cherry
 ```
+Output: `cherry, banana, apple`
 
-Output:
+### 3. Flexible Whitespace (`$$`)
 
 ```
-hi world
+pattern {$x$$and$$$y} {$x & $y}
+hello   and   world
+hello and world
 ```
+Output: `hello & world` (both)
 
-#### Variables
+`$$` = zero or more spaces/tabs/newlines.
 
-Variables use the configured **sigil** (default `$`).
+### 4. Literal Output (`$$`)
 
 ```
-pattern {say $x} {[$x]}
-say hello
+Price: $$50
 ```
+Output: `Price: $50`
 
-→ `[hello]`
+Use `$$` for literal `$` output.
 
-#### Balanced Block Variables
-
-Papagaio supports deep matching of balanced blocks:
-
-```
-pattern {($x)} {[BLOCK:$x]}
-(do something)
-```
+---
 
-→ `[BLOCK:do something]`
+## Blocks
 
-#### Spread Variables
+Capture content between delimiters.
 
-Spread variables capture until a terminating token:
+### Syntax
 
 ```
-pattern {from $x...to} {$x}
-from A B C to
+$block name {open}{close}
 ```
 
-→ `A B C`
-
-#### Metavariables
-
-Papagaio provides special `$keywords` inside replacements:
-
-| Variable  | Meaning                                    |
-| --------- | ------------------------------------------ |
-| `$match`  | Full matched text                          |
-| `$pre`    | Text before match                          |
-| `$post`   | Text after match                           |
-| `$unique` | Auto‑increment unique token                |
-| `$$`      | Whitespace wildcard in patterns            |
-| `$clear`  | Triggers clear‑rewrite of last replacement |
-
-Example:
+### Example
 
 ```
-pattern {x} {$pre[${unique}]$post}
-abcxdef
+pattern {$block content {(}{)}} {[$content]}
+data ( hello world )
 ```
+Output: `[hello world]`
 
----
-
-### 2. Macro Blocks
-
-Macros behave like simple template functions.
+### Custom Delimiters
 
 ```
-macro name { BODY }
-name(arg1, arg2)
+pattern {$block data {<<}{>>}} {DATA: $data}
+<<json stuff>>
 ```
+Output: `DATA: json stuff`
 
-Example:
+### Multiple Blocks
 
 ```
-macro wrap {[$1][$2]}
-wrap(a, b)
+pattern {$block a {(}{)}, $block b {[}{]}} {$a|$b}
+(first), [second]
 ```
+Output: `first|second`
 
-→ `[a][b]`
-
-#### Argument Mapping
+---
 
-Arguments map to `$1`, `$2`, … automatically. `$0` expands to the macro name.
+## Patterns
 
-Example:
+### Basic
 
 ```
-macro tag {<$0 $1>}  
-tag(title)
+pattern {match} {replace}
 ```
 
-→ `<tag title>`
-
----
-
-### 3. Eval Blocks
-
-Executes embedded JavaScript and returns the result as a string.
+### Real Example
 
 ```
-eval { return 3 + 7 }
+pattern {# $title} {<h1>$title</h1>}
+# Welcome
 ```
+Output: `<h1>Welcome</h1>`
 
-→ `10`
-
-Eval executes inside a strict IIFE.
-
-You may access:
-
-* `papagaio` → the processor instance
-* `ctx` → an empty object for temporary state
-
-Example:
+### Multiple Patterns
 
 ```
-pattern {sum $a $b} {eval { return Number($a) + Number($b) }}
-sum 2 8
+pattern {a} {b}
+pattern {b} {c}
+pattern {c} {d}
+a
 ```
-
-→ `10`
+Output: `d` (automatic cascade)
 
 ---
 
-### 4. Scope Blocks
+## Contexts
 
-Scope blocks create isolated processing regions using the same pipeline.
+Recursive processing scope.
 
 ```
-scope {
-    pattern {x} {y}
-    x x x
+context {
+  pattern {$x} {<$x>}
+  
+  apple
+  banana
 }
 ```
+Output:
+```
+<apple>
+<banana>
+```
 
-→ `y y y`
-
-Scopes do not leak macros or patterns to the outside.
+**Empty contexts are automatically removed.**
 
 ---
 
-## Delimiters
+## Special Keywords
 
-Papagaio supports configurable opening/closing pairs.
+### $unique
+Generate unique incremental IDs.
 
-```js
-p.delimiters = [["{", "}"], ["(", ")"]];
 ```
+pattern {item} {item_$unique}
+item
+item
+item
+```
+Output: `item_u0`, `item_u1`, `item_u2`
 
-Balanced variable matching works across all registered delimiter pairs.
-
----
-
-## Recursion Model
-
-Papagaio runs a fixed‑point loop:
-
-1. Process scopes
-2. Process eval blocks
-3. Collect macros
-4. Collect top‑level patterns
-5. Apply patterns
-6. Expand macros
+### $match
+Return the full match.
 
-If any Papagaio keyword remains in the output, it repeats.
+```
+pattern {[$x]} {FOUND: $match}
+[data]
+```
+Output: `FOUND: [data]`
 
-You can configure the iteration cap:
+### $prefix / $suffix
+Text before and after the match.
 
-```js
-p.maxRecursion = 256;
 ```
+pattern {$x} {BEFORE:$prefix | AFTER:$suffix}
+hello world test
+```
+Output: `BEFORE: | AFTER: world test`
 
----
+### $clear
+Remove everything before the match.
 
-## Error Handling
+```
+pattern {SKIP $x} {$clear KEEP: $x}
+IGNORE_THIS SKIP keep_this
+```
+Output: `KEEP: keep_this`
 
-Eval blocks are wrapped in a try/catch. Exceptions produce empty output.
+### $eval
+Execute JavaScript code.
 
-Pattern/macro recursion halts upon reaching `maxRecursion`.
+```
+pattern {$x} {$eval{return parseInt($x) * 2;}}
+5
+```
+Output: `10`
 
 ---
 
-## Advanced Examples
+## Practical Examples
 
-### Nested Macros
+### Markdown → HTML
 
 ```
-macro A {($1)}
-macro B {A($1)}
-B(hello)
+context {
+  pattern {# $t} {<h1>$t</h1>}
+  pattern {## $t} {<h2>$t</h2>}
+  pattern {**$t**} {<strong>$t</strong>}
+  pattern {*$t*} {<em>$t</em>}
+  pattern {- $i} {<li>$i</li>}
+  
+  # Title
+  **bold** and *italic*
+  - item1
+  - item2
+}
 ```
 
-→ `(hello)`
-
-### Dynamic Rewriting with `$unique`
+### CSV → JSON
 
 ```
-pattern {node} {id_$unique}
-node node node
+pattern {$a,$b,$c} {{ id: '$a', name: '$b', role: '$c' }}
+1,Alice,Engineer
+2,Bob,Designer
 ```
 
-→ `id_0 id_1 id_2`
+Output:
+```
+{ id: '1', name: 'Alice', role: 'Engineer' }
+{ id: '2', name: 'Bob', role: 'Designer' }
+```
 
-### Working with Pre/Post Context
+### Config Parser
 
 ```
-pattern {x} {$pre|X|$post}
-a x b
+pattern {$key = $value} {const $key = '$value';}
+host = localhost
+port = 3000
 ```
 
-→ `a |X| b`
+Output:
+```
+const host = 'localhost';
+const port = '3000';
+```
 
-### Spread Matching
+### HTML Generator
 
 ```
-pattern {let $name = $v...;} {[decl $name $v]}
-let x = 1 + 2 + 3;
+pattern {$tag $content} {<$tag>$content</$tag>}
+div HelloWorld
+span Test
 ```
 
-→ `[decl x 1 + 2 + 3]`
+Output:
+```
+<div>HelloWorld</div>
+<span>Test</span>
+```
 
 ---
 
-## API Reference
-
-### Class: `Papagaio`
-
-#### `process(input: string): string`
-
-Runs the full pipeline and returns the transformed text.
+## Important Rules
 
-#### `delimiters: Array<[string, string]>`
+### Matching
+- Variables (`$x`) capture **one word** (no spaces)
+- `$$` = flexible whitespace (0+ spaces/tabs/newlines)
+- Patterns apply **globally** each iteration
+- Auto-recursion until: max 512 iterations OR no changes
 
-List of opening/closing delimiter pairs.
+### Block Matching
+- `$block name {open}{close}` captures between delimiters
+- Supports nested delimiters automatically
+- Multiple blocks in one pattern work
 
-#### `sigil: string`
+### Variables
+- Names: `[A-Za-z0-9_]`
+- Reuse: `$x` appears multiple times in replace
+- Undefined: becomes empty string
 
-Variable prefix. Default `$`.
-
-#### `keywords`
+---
 
-Keyword configuration:
+## Troubleshooting
 
-* `pattern`
-* `macro`
-* `eval`
-* `scope`
+| Problem | Solution |
+|---------|----------|
+| Pattern doesn't match | Use `$$` between elements for flexible whitespace |
+| Variable not captured | Check space between variables |
+| Block not working | Verify balanced delimiters `{` `}` |
+| Infinite recursion | Use `$clear` or reduce `maxRecursion` |
+| $eval not working | Errors return empty string, use try-catch |
 
-#### Internal State
+---
 
-For debugging only:
+## Performance
 
-* `content` → latest processed text
-* `#matchContent`
-* `#scopeContent`
-* `#evalContent`
+- Simple patterns > complex patterns
+- Blocks have minor overhead
+- Avoid unlimited recursion
+- For large inputs, use multiple contexts
 
 ---
 
-## Embedding
+## Syntax Reference
 
-Papagaio is pure JS and safe to embed in build pipelines, CLIs, game engines, or runtime scripting layers.
+```
+pattern {$x $y} {$y, $x}              # basic pattern
+pattern {$x$$y} {$x-$y}               # flexible whitespace
+pattern {$block n {o}{c}} {$n}        # block
+context { ... }                        # recursive scope
+$$literal                              # output literal $
+$unique                                # unique ID
+$match                                 # full match
+$prefix / $suffix                      # before/after
+$clear                                 # clear before
+$eval{code}                            # execute JS
+```
 
-Example minimal CLI wrapper:
+---
 
-```js
-#!/usr/bin/env node
-const fs = require("fs");
-const { Papagaio } = require("./papagaio");
+## Complete Example
+
+```
+context {
+  # Markdown headers
+  pattern {# $title} {<h1>$title</h1>}
+  pattern {## $title} {<h2>$title</h2>}
+  
+  # Lists
+  pattern {- $item} {<li>$item</li>}
+  
+  # Inline formatting
+  pattern {**$text**} {<strong>$text</strong>}
+  pattern {*$text*} {<em>$text</em>}
+  
+  # Process content
+  # Welcome
+  ## Getting Started
+  This is **important** and *italic*
+  - First item
+  - Second item
+}
+```
 
-const input = fs.readFileSync(0, "utf8");
-const out = new Papagaio().process(input);
-process.stdout.write(out);
+Output:
+```html
+<h1>Welcome</h1>
+<h2>Getting Started</h2>
+This is <strong>important</strong> and <em>italic</em>
+<li>First item</li>
+<li>Second item</li>
 ```
 
----
+---

package/{cli.js → bin/cli.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { Papagaio } from "./papagaio.js";
+import { Papagaio } from "../src/papagaio.js";
 import fs from "fs";
 import { createRequire } from "module";
 const require = createRequire(import.meta.url);
-const pkg = require("./package.json");
+const pkg = require("../package.json");
 
 
 // Help & Version

package/index.html

@@ -301,7 +301,7 @@
     </div>
 
         <script type="module">
-            import { Papagaio } from './papagaio.js';
+            import { Papagaio } from './src/papagaio.js';
 
             let processor = null;
 

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "papagaio",
-  "version": "0.1.8",
+  "version": "0.2.3",
   "description": "easy yet powerful preprocessor",
-  "main": "papagaio.js",
+  "main": "src/papagaio.js",
   "type": "module",
+  "scripts": {
+    "test": "node tests/test.js"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jardimdanificado/papagaio.git"
@@ -13,16 +16,14 @@
     "macro",
     "pattern",
     "eval",
-    "isolate",
     "parser"
   ],
   "author": "jardimdanificado",
   "bugs": {
     "url": "https://github.com/jardimdanificado/papagaio/issues"
   },
-  "homepage": "https://github.com/jardimdanificado/papagaio#readme"
-,
+  "homepage": "https://github.com/jardimdanificado/papagaio#readme",
   "bin": {
-    "papagaio": "./cli.js"
+    "papagaio": "./bin/cli.js"
   }
-}
+}