papagaio 0.5.0 → 0.6.1

package/README.md

@@ -1,22 +1,30 @@
 # Papagaio
-Minimal yet powerful text preprocessor with support for multi-character delimiters.
+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;
 
 ## 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 (multi-char supported)
   close: "}",              // closing delimiter (multi-char supported)
-  sigil: "$"               // variable marker
+  sigil: "$",              // variable marker
+  eval: "eval",            // eval keyword
+  block: "block",          // block keyword
+  regex: "regex"           // regex keyword
 };
-p.recursion_limit = 512;
 ```
 
 ---
@@ -25,48 +33,95 @@ p.recursion_limit = 512;
 
 ### 1. Simple Variables
 ```
-pattern {$x} {$x}
+$pattern {$x} {$x}
 hello
 ```
 Output: `hello`
 
 ### 2. Multiple Variables
 ```
-pattern {$x $y $z} {$z, $y, $x}
+$pattern {$x $y $z} {$z, $y, $x}
 apple banana cherry
 ```
 Output: `cherry, banana, apple`
 
 ---
 
-## Whitespace Operators
+## Variables
 
-Papagaio provides flexible whitespace handling for variable capture.
+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)
 
-### `$x` - Single Word Variable
-Captures a single non-whitespace token.
 ```
-pattern {$x} {[$x]}
+$pattern {$x} {[$x]}
 hello world
 ```
-Output: `[hello]`
+Output: `[hello] [world]`
 
-### `$$x` - Whitespace-Sensitive Variable
-Captures text including surrounding whitespace until the next significant token.
 ```
-pattern {$$x world} {[$x]}
-hello   world
+$pattern {$name $block content {(}{)}} {$name: $content}
+greeting (hello world)
 ```
-Output: `[hello  ]`
+Output: `greeting: hello world`
 
-### `$$$x` - Optional Whitespace Variable
-Captures with optional whitespace (no error if empty).
 ```
-pattern {$$$x world} {<$x>}
+$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 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
+```
+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`
+
 ---
 
 ## Blocks
@@ -80,21 +135,21 @@ $block varName {open}{close}
 
 ### Basic Example
 ```
-pattern {$name $block content {(}{)}} {[$content]}
+$pattern {$name $block content {(}{)}} {[$content]}
 data (hello world)
 ```
 Output: `[hello world]`
 
 ### Custom Delimiters
 ```
-pattern {$block data {<<}{>>}} {DATA: $data}
+$pattern {$block data {<<}{>>}} {DATA: $data}
 <<json stuff>>
 ```
 Output: `DATA: json stuff`
 
 ### Multi-Character Delimiters
 ```
-pattern {$block code {```}{```}} {<pre>$code</pre>}
+$pattern {$block code {```}{```}} {<pre>$code</pre>}
 ```markdown
 # Title
 ```
@@ -102,138 +157,255 @@ Output: `<pre># Title</pre>`
 
 ### Multiple Blocks
 ```
-pattern {$block a {(}{)}, $block b {[}{]}} {$a|$b}
+$pattern {$block a {(}{)}, $block b {[}{]}} {$a|$b}
 (first), [second]
 ```
 Output: `first|second`
 
 ### Nested Blocks
 ```
-pattern {$block outer {(}{)}} {[$outer]}
+$pattern {$block outer {(}{)}} {[$outer]}
 (outer (inner))
 ```
 Output: `[outer (inner)]`
 
 ---
 
-## Patterns
+## Pattern Scopes
+
+Patterns defined within a replacement body create nested scopes with hierarchical inheritance.
 
 ### Basic Pattern
 ```
-pattern {match} {replace}
+$pattern {hello} {world}
+hello
 ```
+Output: `world`
 
-### Example
-```
-pattern {# $title} {<h1>$title</h1>}
-# Welcome
-```
-Output: `<h1>Welcome</h1>`
+**Key Properties:**
+* Patterns are scoped to their context
+* Child patterns inherit parent patterns
+* Patterns do not persist between `process()` calls
+* Perfect for hierarchical transformations
 
-### Multiple Patterns Cascade
+### Nested Patterns with Inheritance
 ```
-pattern {a} {b}
-pattern {b} {c}
-pattern {c} {d}
-a
+$pattern {outer $x} {
+  $pattern {inner $y} {[$y from $x]}
+  inner $x
+}
+outer hello
 ```
-Output: `d`
-
----
+Output: `[hello from hello]`
 
-## Subpatterns
+The inner pattern has access to `$x` from the outer pattern's capture.
 
-Subpatterns are patterns declared *inside* replacement bodies, existing only during parent pattern execution.
-
-### Syntax
+### Deep Nesting
 ```
-$pattern {match} {replace}
+$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.
 
-### Example
+### Sibling Scopes Don't Share
 ```
-pattern {eval $block code {(}{)}} {
-  $eval{
-    $pattern {undefined} {}
-    $code;
-    return "";
-  }
+$pattern {branch1} {
+  $pattern {x} {A}
+  x
 }
-eval(console.log(123))
+$pattern {branch2} {
+  x
+}
+branch1
+branch2
 ```
 Output:
 ```
-123
+A
+x
 ```
 
-### 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.
+Patterns in `branch1` are not available in `branch2` (they are siblings, not parent-child).
 
 ---
 
 ## Special Keywords
 
 ### $eval
-Executes JavaScript code.
+Executes JavaScript code with access to the Papagaio instance.
+
 ```
-pattern {$x} {$eval{return parseInt($x)*2;}}
+$pattern {$x} {$eval{return parseInt($x)*2;}}
 5
 ```
 Output: `10`
 
-Supports multi-character delimiters:
+**Accessing Papagaio Instance:**
+```
+$pattern {info} {$eval{
+  return `Content length: ${papagaio.content.length}`;
+}}
+info
 ```
-pattern {$x} {$eval<<parseInt($x)*2>>}
+
+**Multi-character delimiters:**
+```
+$pattern {$x} {$eval<<parseInt($x)*2>>}
 5
 ```
 Output: `10`
 
+---
 
 ## Important Rules
 
-### 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
+### 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
+
+### 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)
 
 ### Block Matching
 * `$block name {open}{close}` captures delimited regions
 * Supports nested delimiters of any length
 * Multi-character delimiters fully supported (e.g., `{>>>}{<<<}`)
-
-### 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
+* Blocks support arbitrary nesting depth
 
 ---
 
 ## Multi-Character Delimiter Support
 
-The updated version fully supports multi-character delimiters throughout all features.
+Papagaio fully supports multi-character delimiters throughout all features.
 
-### Examples
+### Configuration
 ```javascript
 const p = new Papagaio('$', '<<<', '>>>');
 ```
 
+### In Patterns
+```
+$pattern<<<$x>>> <<<[$x]>>>
+hello
+```
+Output: `[hello]`
+
 ### In Blocks
 ```
-pattern {$block data {<<}{>>}} {$data}
+$pattern<<<$block data {<<}{>>}>>> <<<$data>>>
 <<content>>
 ```
+Output: `content`
 
 ### In Eval
 ```
-// const p = new Papagaio('$', '<<<', '>>>');
-pattern <<<$x>>> <<<$eval<<<return $x + 1>>>>>>
+$pattern<<<$x>>> <<<$eval<<<return $x + 1>>>>>>
 5
 ```
+Output: `6`
+
+---
+
+## Advanced Examples
+
+### 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>
+```
+
+### 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
+```
+
+### Conditional Processing
+```javascript
+const p = new Papagaio();
+const template = `
+$pattern {if $block cond {(}{)} then $block yes {[}{]} else $block no {<}{>}} {
+  $eval{
+    const condition = ($cond).trim();
+    return condition === 'true' ? '$yes' : '$no';
+  }
+}
+
+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
+```
 
 ---
 
@@ -241,31 +413,73 @@ pattern <<<$x>>> <<<$eval<<<return $x + 1>>>>>>
 
 | Problem | Solution |
 |---------|----------|
-| Variable not captured | Check spacing and use appropriate whitespace operator (`$x`, `$$x`, `$$$x`) |
+| 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 | Add whitespace operators (`$$`) for multi-word content |
+| 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 |
 
 ---
 
 ## Syntax Reference
 
 ```
-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
+$pattern {$x $y} {$y, $x}            # 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
+$eval{code}                          # JavaScript evaluation
+```
+
+---
+
+## API Reference
+
+### Constructor
+```javascript
+new Papagaio(sigil, open, close, pattern, evalKw, blockKw, regexKw)
+```
+
+**Parameters:**
+- `sigil` (default: `'$'`) - Variable prefix
+- `open` (default: `'{'`) - Opening delimiter
+- `close` (default: `'}'`) - Closing delimiter
+- `pattern` (default: `'pattern'`) - Pattern keyword
+- `evalKw` (default: `'eval'`) - Eval keyword
+- `blockKw` (default: `'block'`) - Block 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');
 ```
 
 ---
 
 ## 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
+* Multi-character delimiter matching is optimized with substring operations
+* 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
+
+---
+
+***PAPAGAIO IS CURRENTLY IN HEAVY DEVELOPMENT AND EXPERIMENTATION PHASE***

package/bin/cli.qjs

@@ -7,7 +7,7 @@ import * as os from "os";
 import { Papagaio } from "../src/papagaio.js";
 
 // Version (você pode hardcoded ou ler de um arquivo JSON se necessário)
-const VERSION = "1.0.0";
+const VERSION = "0.6.0";
 
 // Parse command line arguments
 const args = scriptArgs.slice(1); // QuickJS usa scriptArgs ao invés de process.argv

package/examples/simple.html

@@ -5,9 +5,9 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>papagaio test</title>
 </head>
-<script src="src/papagaio-bootstrap.mjs" type="module"></script>
+<script src="../src/papagaio-bootstrap.mjs" type="module"></script>
 <script type="papagaio">
-    pattern {abc} {$eval{console.log(papagaio)}}
+    $pattern {abc} {$eval{console.log(papagaio)} aaaaaaaaaaaaaaaaaaaaaaaaaaaa}
     abc
 </script>
 <body>

package/examples/wasm.papagaio

@@ -0,0 +1,70 @@
+// generic ts-like to wasm compiler
+
+// util patterns
+$pattern {// $comment $regex newline{[^\n]*}} {}
+$pattern {$regex spaces{\s\s}}{ }
+
+$eval{
+    papagaio.exit = function()
+    {
+        papagaio.content = "(module\n" + papagaio.content + "\n)";
+        papagaio.exit = null;
+    };
+    return ""
+}
+
+$pattern {export function $name $block params{(}{)}:$rets $block content{}{}} {
+    $pattern {parametrize}
+    {
+        $eval {
+            let str = "$params".replace("(", "").replace(")", "");
+            let params = str.split(",").map(p => p.trim()).filter(p => p);
+            let new_stuff = "";
+            for (const param of params) {
+                if (!param.includes(":")) continue; // Pula se não tem ':'
+                const [name, type] = param.split(":");
+                if (name && type) { // Verifica se ambos existem
+                    new_stuff += ` (param $${name.trim()} ${type.trim()}) `;
+                }
+            }
+            return new_stuff;
+        }
+    }
+
+    (func (export "$name") parametrize (result $rets)
+        $content
+    )
+}
+
+$pattern {function $name $block params{(}{)}:$rets $block content{}{}} {
+    $pattern {parametrize}
+    {
+        $eval {
+            let str = "$params".replace("(", "").replace(")", "");
+            let params = str.split(",").map(p => p.trim()).filter(p => p);
+            let new_stuff = "";
+            for (const param of params) {
+                if (!param.includes(":")) continue; // Pula se não tem ':'
+                const [name, type] = param.split(":");
+                if (name && type) { // Verifica se ambos existem
+                    new_stuff += ` (param $${name.trim()} ${type.trim()}) `;
+                }
+            }
+            return new_stuff;
+        }
+    }
+
+    (func $$name parametrize (result $rets)
+        $content
+    )
+}
+
+function name(a:i32, b:i32):i64 i64
+{
+    contentnans
+}
+
+export function funcao_exportada(a:f32, b:f32, c:f32):i64 i64 i64 i64
+{
+    fução expoortada1
+}