papagaio 0.4.2 → 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
-  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;
-p.unique_id = 0;
 ```
 
 ---
@@ -29,108 +24,133 @@ p.unique_id = 0;
 ## Core Concepts
 
 ### 1. Simple Variables
-
 ```
 pattern {$x} {$x}
 hello
 ```
-
 Output: `hello`
 
 ### 2. Multiple Variables
-
 ```
 pattern {$x $y $z} {$z, $y, $x}
 apple banana cherry
 ```
-
 Output: `cherry, banana, apple`
 
 ---
 
-## Blocks
+## Whitespace Operators
 
-Capture content between delimiters.
+Papagaio provides flexible whitespace handling for variable capture.
 
-### Syntax
+### `$x` - Single Word Variable
+Captures a single non-whitespace token.
+```
+pattern {$x} {[$x]}
+hello world
+```
+Output: `[hello]`
 
+### `$$x` - Whitespace-Sensitive Variable
+Captures text including surrounding whitespace until the next significant token.
 ```
-$block name {open}{close}
+pattern {$$x world} {[$x]}
+hello   world
 ```
+Output: `[hello  ]`
 
-### Example
+### `$$$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)
 ```
-
 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}
 ```
 
 ### Example
-
 ```
 pattern {# $title} {<h1>$title</h1>}
 # Welcome
 ```
-
 Output: `<h1>Welcome</h1>`
 
 ### Multiple Patterns Cascade
-
 ```
 pattern {a} {b}
 pattern {b} {c}
 pattern {c} {d}
 a
 ```
-
 Output: `d`
 
 ---
 
-# Subpatterns
+## Subpatterns
 
-Subpatterns allow patterns to be declared *inside* other patterns, existing only during the execution of that parent pattern.
+Subpatterns are patterns declared *inside* replacement bodies, existing only during parent pattern execution.
 
 ### Syntax
-
 ```
 $pattern {match} {replace}
 ```
 
-A subpattern behaves like a normal pattern but is **scoped only to the replacement body where it appears**.
-
 ### Example
-
 ```
 pattern {eval $block code {(}{)}} {
   $eval{
@@ -139,133 +159,113 @@ pattern {eval $block code {(}{)}} {
     return "";
   }
 }
-
 eval(console.log(123))
 ```
-
 Output:
-
 ```
 123
 ```
 
 ### 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 handle it.
-* Multiple subpatterns can coexist inside the same replacement.
+* They can recursively modify inner content before `$eval` or other processors.
+* Multiple subpatterns can coexist in the same replacement.
 
 ---
 
 ## Special Keywords
 
-### $unique
-
-Generates unique incremental IDs.
-
+### $eval
+Executes JavaScript code.
 ```
-pattern {item} {[$unique]item_$unique}
-item
-item
+pattern {$x} {$eval{return parseInt($x)*2;}}
+5
 ```
+Output: `10`
 
-Outputs:
-
+Supports multi-character delimiters:
 ```
-[0]item_0
-[1]item_1
+pattern {$x} {$eval<<parseInt($x)*2>>}
+5
 ```
+Output: `10`
 
-### $match
-
-Full matched text.
 
-```
-pattern {[$x]} {FOUND: $match}
-[data]
-```
+## Important Rules
 
-Output: `FOUND: [data]`
+### 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
 
-### $prefix / $suffix
+### Block Matching
+* `$block name {open}{close}` captures delimited regions
+* Supports nested delimiters of any length
+* Multi-character delimiters fully supported (e.g., `{>>>}{<<<}`)
 
-Text before and after match.
+### 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 {world} {$prefix$suffix}hello world test
-```
+---
 
-Output: `hello hello  test test`
+## Multi-Character Delimiter Support
 
-### $clear
+The updated version fully supports multi-character delimiters throughout all features.
 
-Removes everything before match.
+### Examples
+```javascript
+const p = new Papagaio('$', '<<<', '>>>');
+```
 
+### In Blocks
 ```
-pattern {SKIP $x} {$clear KEEP: $x}
-IGNORE SKIP keep
+pattern {$block data {<<}{>>}} {$data}
+<<content>>
 ```
 
-Output: `KEEP: keep`
-
-### $eval
-
-Executes JS.
-
+### In Eval
 ```
-pattern {$x} {$eval{return parseInt($x)*2;}}
+// const p = new Papagaio('$', '<<<', '>>>');
+pattern <<<$x>>> <<<$eval<<<return $x + 1>>>>>>
 5
 ```
 
-Output: `10`
-
----
-
-## Important Rules
-
-### Matching
-
-* `$x` = one word
-* `$$x` = multiword (captures whitespace too)
-* `$`, `$$`, `$$$`, `$$$$` = whitespace operators
-* Patterns apply globally until stable
-* Blocks can be nested
-
-### Block Matching
-
-* `$block name {open}{close}` captures delimited regions
-* Supports nested delimiters
-
 ---
 
 ## Troubleshooting
 
-| Problem               | Solution                   |
-| --------------------- | -------------------------- |
-| Variable not captured | Check spacing              |
-| Block wrong           | Verify delimiters          |
-| Infinite recursion    | Reduce recursion limit     |
-| Pattern not matching  | Add whitespace operators   |
-| Multiword var issues  | Beware whitespace consumed |
+| Problem | Solution |
+|---------|----------|
+| 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 |
 
 ---
 
-## Known Bugs
+## Syntax Reference
 
-* Multi-character delimiters containing `"` break nested parsing.
+```
+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
+```
 
 ---
 
-## Syntax Reference
+## Performance Notes
 
-```
-pattern {$x $y} {$y, $x}
-pattern {$block n {o}{c}} {$n}
-$pattern {a} {b}       # subpattern
-$unique
-$match
-$prefix / $suffix
-$clear
-$eval{code}
-```
+* 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);