papagaio 0.4.2 → 0.5.2

package/README.md

@@ -1,27 +1,25 @@
 # 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();
-const result = p.process(input);
+const papagaio = new Papagaio();
+const result = papagaio.process(input);
 ```
 
 ## Configuration
-
 ```javascript
-p.symbols = {
+papagaio.symbols = {
   pattern: "pattern",      // pattern keyword
-  open: "{",               // opening delimiter
-  close: "}",              // closing delimiter
-  sigil: "$"               // variable marker
+  open: "{",               // opening delimiter (multi-char supported)
+  close: "}",              // closing delimiter (multi-char supported)
+  sigil: "$",              // variable marker
+  eval: "eval",            // eval keyword
+  block: "block",          // block keyword
+  regex: "regex"           // regex keyword
 };
-
-p.recursion_limit = 512;
-p.unique_id = 0;
+papagaio.recursion_limit = 512;
 ```
 
 ---
@@ -29,108 +27,185 @@ 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
+## 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]`
+
+```
+pattern {$name $block 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.
+
+```
+pattern {$x? world} {<$x>}
+world
+```
+Output: `<>`
+
+```
+pattern {$greeting? $name} {Hello $name$greeting}
+Hi John
+```
+Output: `Hello JohnHi`
+
+---
+
+## Regex Matching
 
-Capture content between delimiters.
+Capture content using JavaScript regular expressions.
 
 ### Syntax
+```
+$regex varName {pattern}
+```
 
+### Basic Example
 ```
-$block name {open}{close}
+pattern {$regex num {[0-9]+}} {Number: $num}
+The answer is 42
 ```
+Output: `Number: 42`
 
-### Example
+### Complex Patterns
+```
+pattern {$regex email {\w+@\w+\.\w+}} {Email found: $email}
+Contact: user@example.com
+```
+Output: `Email found: user@example.com`
+
+### Multiple Regex Variables
+```
+pattern {$regex year {[0-9]{4}}-$regex month {[0-9]{2}}} {Month $month in $year}
+2024-03
+```
+Output: `Month 03 in 2024`
 
+### Notes
+- Regex patterns are cached for performance
+- Matches are anchored at the current position (no searching ahead)
+- Invalid regex patterns will cause the match to fail gracefully
+
+---
+
+## 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 +214,115 @@ 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]`
+### 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
+* 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
+* 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 context: use `$x?` for optional, or verify literals/blocks exist |
+| Block mismatch | Verify opening and closing delimiters match the declaration |
+| Infinite recursion | Reduce `recursion_limit` or simplify pattern dependencies |
+| Pattern not matching | Verify whitespace between tokens, check if variable should be optional |
+| 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 |
 
 ---
 
-## 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}          # optional variable
+pattern {$regex n {[0-9]+}} {$n}   # regex 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
+* Regex patterns are automatically cached to improve performance
+* 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);