papagaio 0.4.1 → 0.5.0

package/README.md

@@ -1,9 +1,7 @@
 # Papagaio
-
-Minimal yet powerful text preprocessor.
+Minimal yet powerful text preprocessor with support for multi-character delimiters.
 
 ## Installation
-
 ```javascript
 import { Papagaio } from './src/papagaio.js';
 const p = new Papagaio();
@@ -11,17 +9,14 @@ const result = p.process(input);
 ```
 
 ## Configuration
-
 ```javascript
 p.symbols = {
   pattern: "pattern",      // pattern keyword
-  context: "context",      // context keyword
-  open: "{",               // opening delimiter
-  close: "}",              // closing delimiter
+  open: "{",               // opening delimiter (multi-char supported)
+  close: "}",              // closing delimiter (multi-char supported)
   sigil: "$"               // variable marker
 };
-p.recursion_limit = 512;   // iteration limit
-p.unique_id = 0;           // unique ID counter
+p.recursion_limit = 512;
 ```
 
 ---
@@ -29,35 +24,61 @@ p.unique_id = 0;           // unique ID counter
 ## Core Concepts
 
 ### 1. Simple Variables
-
 ```
 pattern {$x} {$x}
 hello
 ```
 Output: `hello`
 
-Variables capture words (non-whitespace sequences).
-
 ### 2. Multiple Variables
-
 ```
 pattern {$x $y $z} {$z, $y, $x}
 apple banana cherry
 ```
 Output: `cherry, banana, apple`
 
-## Blocks
+---
 
-Capture content between delimiters.
+## Whitespace Operators
 
-### Syntax
+Papagaio provides flexible whitespace handling for variable capture.
 
+### `$x` - Single Word Variable
+Captures a single non-whitespace token.
 ```
-$block name {open}{close}
+pattern {$x} {[$x]}
+hello world
 ```
+Output: `[hello]`
 
-### Example
+### `$$x` - Whitespace-Sensitive Variable
+Captures text including surrounding whitespace until the next significant token.
+```
+pattern {$$x world} {[$x]}
+hello   world
+```
+Output: `[hello  ]`
+
+### `$$$x` - Optional Whitespace Variable
+Captures with optional whitespace (no error if empty).
+```
+pattern {$$$x world} {<$x>}
+world
+```
+Output: `<>`
+
+---
+
+## Blocks
+
+Capture content between delimiters with full nesting support.
 
+### Syntax
+```
+$block varName {open}{close}
+```
+
+### Basic Example
 ```
 pattern {$name $block content {(}{)}} {[$content]}
 data (hello world)
@@ -65,287 +86,186 @@ data (hello world)
 Output: `[hello world]`
 
 ### Custom Delimiters
-
 ```
 pattern {$block data {<<}{>>}} {DATA: $data}
 <<json stuff>>
 ```
 Output: `DATA: json stuff`
 
-### Multiple Blocks
+### Multi-Character Delimiters
+```
+pattern {$block code {```}{```}} {<pre>$code</pre>}
+```markdown
+# Title
+```
+Output: `<pre># Title</pre>`
 
+### Multiple Blocks
 ```
 pattern {$block a {(}{)}, $block b {[}{]}} {$a|$b}
 (first), [second]
 ```
 Output: `first|second`
 
+### Nested Blocks
+```
+pattern {$block outer {(}{)}} {[$outer]}
+(outer (inner))
+```
+Output: `[outer (inner)]`
+
 ---
 
 ## Patterns
 
-### Basic
-
+### Basic Pattern
 ```
 pattern {match} {replace}
 ```
 
-### Real Example
-
+### Example
 ```
 pattern {# $title} {<h1>$title</h1>}
 # Welcome
 ```
 Output: `<h1>Welcome</h1>`
 
-### Multiple Patterns
-
+### Multiple Patterns Cascade
 ```
 pattern {a} {b}
 pattern {b} {c}
 pattern {c} {d}
 a
 ```
-Output: `d` (automatic cascade)
+Output: `d`
 
 ---
 
-## Contexts
+## Subpatterns
 
-Recursive processing scope.
+Subpatterns are patterns declared *inside* replacement bodies, existing only during parent pattern execution.
 
+### Syntax
+```
+$pattern {match} {replace}
 ```
-context {
-  pattern {$x} {<$x>}
-  
-  apple
-  banana
+
+### Example
+```
+pattern {eval $block code {(}{)}} {
+  $eval{
+    $pattern {undefined} {}
+    $code;
+    return "";
+  }
 }
+eval(console.log(123))
 ```
 Output:
 ```
-<apple>
- <banana>
+123
 ```
 
-**Empty contexts are automatically removed.**
+### Key Properties
+* Subpatterns exist only within the running pattern.
+* They do not leak into the global pattern list.
+* They can recursively modify inner content before `$eval` or other processors.
+* Multiple subpatterns can coexist in the same replacement.
 
 ---
 
 ## Special Keywords
 
-### $unique
-Generate unique incremental IDs for each pattern call. All occurrences of `$unique` within the same pattern replacement share the same ID.
-
-```
-pattern {item} {[$unique]item_$unique}
-item
-item
-item
-```
-Output: `[0]item_0`, `[1]item_1`, `[2]item_2`
-
-```
-pattern {a} {$unique $unique}
-a
-```
-Output: `0 0` (same ID for both occurrences)
-
-### $match
-Return the full match.
-
-```
-pattern {[$x]} {FOUND: $match}
-[data]
-```
-Output: `FOUND: [data]`
-
-### $prefix / $suffix
-Text before and after the match.
-
-```
-pattern {world} {$prefix$suffix}hello world test
-```
-Output: `hello hello  test test`
-
-### $clear
-Remove everything before the match.
-
+### $eval
+Executes JavaScript code.
 ```
-pattern {SKIP $x} {$clear KEEP: $x}
-IGNORE_THIS SKIP keep_this
+pattern {$x} {$eval{return parseInt($x)*2;}}
+5
 ```
-Output: `KEEP: keep_this`
-
-### $eval
-Execute JavaScript code.
+Output: `10`
 
+Supports multi-character delimiters:
 ```
-pattern {$x} {$eval{return parseInt($x) * 2;}}
+pattern {$x} {$eval<<parseInt($x)*2>>}
 5
 ```
 Output: `10`
 
----
 
-## Practical Examples
+## Important Rules
 
-### Markdown → HTML
+### Matching
+* `$x` = one word (no whitespace)
+* `$$x` = captures text with optional surrounding whitespace
+* `$$$x` = captures text with optional surrounding whitespace, can be empty or not found
+* Patterns apply globally until stable
+* Blocks support arbitrary nesting depth
 
-```
-context {
-  pattern {## $t} {<h2>$t</h2>}
-  pattern {# $t} {<h1>$t</h1>}
-  pattern {**$t**} {<strong>$t</strong>}
-  pattern {*$t*} {<em>$t</em>}
-  pattern {- $i} {<li>$i</li>}
-  
-  # Title
-  **bold** and *italic*
-  - item1
-  - item2
-}
-```
+### Block Matching
+* `$block name {open}{close}` captures delimited regions
+* Supports nested delimiters of any length
+* Multi-character delimiters fully supported (e.g., `{>>>}{<<<}`)
 
-### CSV → JSON
+### Whitespace Handling
+* Whitespace-optional tokens (`$$` alone) skip optional whitespace
+* Variables automatically skip leading whitespace when needed
+* Trailing whitespace is trimmed when variables appear before literals
 
-```
-pattern {$a,$b,$c} {{ id: '$a', name: '$b', role: '$c' }}
-1,Alice,Engineer
-2,Bob,Designer
-```
+---
 
-Output:
-```
-{ id: '1', name: 'Alice', role: 'Engineer' }
-{ id: '2', name: 'Bob', role: 'Designer' }
-```
+## Multi-Character Delimiter Support
 
-### Config Parser
+The updated version fully supports multi-character delimiters throughout all features.
 
+### Examples
+```javascript
+const p = new Papagaio('$', '<<<', '>>>');
 ```
-pattern {$key = $value} {const $key = '$value';}
-host = localhost
-port = 3000
-```
-
-Output:
-```
-const host = 'localhost';
-const port = '3000';
-```
-
-### HTML Generator
 
+### In Blocks
 ```
-pattern {$tag $content} {<$tag>$content</$tag>}
-div HelloWorld
-span Test
+pattern {$block data {<<}{>>}} {$data}
+<<content>>
 ```
 
-Output:
+### In Eval
 ```
-<div>HelloWorld</div>
-<span>Test</span>
+// const p = new Papagaio('$', '<<<', '>>>');
+pattern <<<$x>>> <<<$eval<<<return $x + 1>>>>>>
+5
 ```
 
 ---
 
-## Important Rules
-
-### Matching
-- Variables (`$x`) capture **one word** (no spaces)
-- Variables (`$$x`) captures one or more words (with spaces)
-- Patterns apply **globally** each iteration
-- Auto-recursion until: max 512 iterations OR no changes
-- `$ `  = one or more of this whitespace (spaces, tabs, newlines)
-- `$$ ` = zero or more of this whitespace (spaces, tabs, newlines)
-- `$$$ `= one or more whitespaces
-- `$$$$ `= zero or more whitespaces
-
-### Block Matching
-- `$block name {open}{close}` captures between delimiters
-- Supports nested delimiters automatically
-- Multiple blocks in one pattern work
-
-### Variables
-- Names: `[A-Za-z0-9_]`
-- Reuse: `$x` appears multiple times in replace
-- Undefined: becomes empty string
-
-### Limitations
-- You cannot match words containing the current sigil character.
-- You cannot match a $block{}{} using the current delimiters.
-- By design, whitespace operators need a whitespace after them to work properly, even the `$$$ ` and `$$$$ ` ones.
-- Multiple word variables (`$$x`) also captures leading/trailing whitespaces, so be careful when using them together with whitespace operators.
-
----
-
 ## Troubleshooting
 
 | Problem | Solution |
 |---------|----------|
-| Variable not captured | Check space between variables |
-| Block not working | Verify balanced delimiters `{` `}` |
-| Infinite recursion | Use `$clear` or reduce `recursion_limit` |
-| $eval not working | Errors return empty string, use try-catch |
-| Pattern doesn't match | Use whitespace operators between elements for flexible whitespace |
-| Whitespace operators | Remember they need a whitespace after them to work properly |
-| Whitespace operators not matching | Multiple word variables (`$$x`) also captures leading/trailing whitespaces, so be careful when using them together with whitespace operators. |
-
-## Known Bugs
-
-- Multi-character block delimiters that contains double quotes doesnt match properly.
+| Variable not captured | Check spacing and use appropriate whitespace operator (`$x`, `$$x`, `$$$x`) |
+| Block mismatch | Verify opening and closing delimiters match the declaration |
+| Infinite recursion | Reduce `recursion_limit` or simplify pattern dependencies |
+| Pattern not matching | Add whitespace operators (`$$`) for multi-word content |
+| Nested blocks fail | Ensure delimiters are properly balanced |
+| Multi-char delimiters broken | Check delimiters don't conflict; use escaping if needed |
 
 ---
 
 ## Syntax Reference
 
 ```
-pattern {$x $y} {$y, $x}               # basic pattern
-pattern {$x$ $y} {$x-$y}               # flexible whitespace
-pattern {$block n {o}{c}} {$n}         # block
-context { ... }                        # recursive scope
-$unique                                # unique ID per pattern
-$match                                 # full match
-$prefix / $suffix                      # before/after
-$clear                                 # clear before
-$eval{code}                            # execute JS
-$ / $$ / $$$ / $$$$                    # whitespace operators
+pattern {$x $y} {$y, $x}           # basic pattern with variables
+pattern {$$x $y} {$y, $x}          # whitespace-sensitive capture
+pattern {$$$x $y} {$y, $x}         # optional whitespace capture
+pattern {$block n {o}{c}} {$n}     # block capture with custom delimiters
+$pattern {a} {b}                   # subpattern (scoped to parent)
+$eval{code}                        # JavaScript evaluation
 ```
 
 ---
 
-## Complete Example
-
-```
-context {
-  # Markdown headers
-  pattern {# $title} {<h1>$title</h1>}
-  
-  # 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
-}
-```
-
-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>
-```
+## Performance Notes
 
----
+* Patterns apply recursively until no changes occur (up to `recursion_limit`)
+* Multi-character delimiter matching is optimized with regex escaping
+* Nested blocks and subpatterns have no theoretical depth limit
+* Large recursion limits can impact performance on complex inputs

package/bin/cli.qjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env qjs
+import * as std from "std";
+import * as os from "os";
+
+// Import Papagaio class - ajuste o caminho conforme necessário
+// Para QuickJS, você pode incluir o arquivo diretamente ou usar import
+import { Papagaio } from "../src/papagaio.js";
+
+// Version (você pode hardcoded ou ler de um arquivo JSON se necessário)
+const VERSION = "1.0.0";
+
+// Parse command line arguments
+const args = scriptArgs.slice(1); // QuickJS usa scriptArgs ao invés de process.argv
+
+// Help & Version
+if (args.includes("-v") || args.includes("--version")) {
+  std.out.puts(VERSION + "\n");
+  std.exit(0);
+}
+
+if (args.includes("-h") || args.includes("--help")) {
+  std.out.puts(`Usage: papagaio [options] <file>
+Options:
+  -h, --help      Show this help message
+  -v, --version   Show version number
+`);
+  std.exit(0);
+}
+
+// File input
+const file = args.find(arg => !arg.startsWith("-"));
+if (!file) {
+  std.err.puts("Error: no input file specified.\nUse --help for usage.\n");
+  std.exit(1);
+}
+
+// Read file
+let src;
+try {
+  const f = std.open(file, "r");
+  if (!f) {
+    std.err.puts(`Error: cannot open file '${file}'\n`);
+    std.exit(1);
+  }
+  src = f.readAsString();
+  f.close();
+} catch (e) {
+  std.err.puts(`Error reading file: ${e}\n`);
+  std.exit(1);
+}
+
+// Process with Papagaio
+const p = new Papagaio();
+const out = p.process(src);
+
+// Output result
+std.out.puts(out);