papagaio 0.5.2 → 0.6.2

package/README.md

@@ -1,5 +1,11 @@
 # 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
@@ -19,7 +25,6 @@ papagaio.symbols = {
   block: "block",          // block keyword
   regex: "regex"           // regex keyword
 };
-papagaio.recursion_limit = 512;
 ```
 
 ---
@@ -28,14 +33,14 @@ papagaio.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`
@@ -53,19 +58,19 @@ Automatically adapts based on context:
 - **Otherwise**: Captures a single word (non-whitespace token)
 
 ```
-pattern {$x} {[$x]}
+$pattern {$x} {[$x]}
 hello world
 ```
-Output: `[hello]`
+Output: `[hello] [world]`
 
 ```
-pattern {$name $block content {(}{)}} {$name: $content}
+$pattern {$name $block content {(}{)}} {$name: $content}
 greeting (hello world)
 ```
 Output: `greeting: hello world`
 
 ```
-pattern {$prefix:$suffix} {$suffix-$prefix}
+$pattern {$prefix:$suffix} {$suffix-$prefix}
 key:value
 ```
 Output: `value-key`
@@ -74,13 +79,13 @@ Output: `value-key`
 Same behavior as `$x`, but won't fail if empty or not found.
 
 ```
-pattern {$x? world} {<$x>}
+$pattern {$x? world} {<$x>}
 world
 ```
 Output: `<>`
 
 ```
-pattern {$greeting? $name} {Hello $name$greeting}
+$pattern {$greeting? $name} {Hello $name$greeting}
 Hi John
 ```
 Output: `Hello JohnHi`
@@ -98,30 +103,25 @@ $regex varName {pattern}
 
 ### Basic Example
 ```
-pattern {$regex num {[0-9]+}} {Number: $num}
+$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}
+$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}
+$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
@@ -135,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
 ```
@@ -157,91 +157,108 @@ 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`
-
----
-
-## Subpatterns
+Output: `[hello from hello]`
 
-Subpatterns are patterns declared *inside* replacement bodies, existing only during parent pattern execution.
+The inner pattern has access to `$x` from the outer pattern's capture.
 
-### 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`
 
-### Example
+Each nested level inherits all patterns from parent scopes.
+
+### Sibling Scopes Don't Share
 ```
-pattern {eval $block code {(}{)}} {
-  $eval{
-    $pattern {undefined} {}
-    $code;
-    return "";
-  }
+$pattern {branch1} {
+  $pattern {x} {A}
+  x
+}
+$pattern {branch2} {
+  x
 }
-eval(console.log(123))
+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`
@@ -254,41 +271,141 @@ Output: `10`
 * `$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
+* 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
-* 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
+```
 
 ---
 
@@ -298,8 +415,9 @@ pattern <<<$x>>> <<<$eval<<<return $x + 1>>>>>>
 |---------|----------|
 | 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 |
+| 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 |
@@ -309,20 +427,59 @@ pattern <<<$x>>> <<<$eval<<<return $x + 1>>>>>>
 ## Syntax Reference
 
 ```
-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
+$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
-* 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
+* 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.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// Detecta o runtime
+const isQuickJS = typeof scriptArgs !== 'undefined';
+const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+
+// ============================================================================
+// MAIN FUNCTION
+// ============================================================================
+async function main() {
+  // ============================================================================
+  // IMPORTS - Branch por runtime
+  // ============================================================================
+  let Papagaio, std, os, fs, pkg;
+
+  if (isQuickJS) {
+    // QuickJS imports
+    const stdModule = await import("std");
+    const osModule = await import("os");
+    std = stdModule;
+    os = osModule;
+    const { Papagaio: P } = await import("../src/papagaio.js");
+    Papagaio = P;
+  } else {
+    // Node.js imports
+    const fsModule = await import("fs");
+    fs = fsModule.default;
+    
+    // Load package.json usando fs ao invés de require
+    const pkgPath = new URL("../package.json", import.meta.url);
+    const pkgContent = fs.readFileSync(pkgPath, "utf8");
+    pkg = JSON.parse(pkgContent);
+    
+    const { Papagaio: P } = await import("../src/papagaio.js");
+    Papagaio = P;
+  }
+
+  // ============================================================================
+  // ABSTRAÇÃO DE CONSOLE/STD
+  // ============================================================================
+  const output = {
+    log: isQuickJS ? (msg) => std.out.puts(msg + "\n") : console.log,
+    error: isQuickJS ? (msg) => std.err.puts(msg + "\n") : console.error,
+    exit: isQuickJS ? std.exit : process.exit
+  };
+
+  // ============================================================================
+  // PARSE ARGUMENTS
+  // ============================================================================
+  const args = isQuickJS ? scriptArgs.slice(1) : process.argv.slice(2);
+  const VERSION = isQuickJS ? "0.6.0" : pkg.version;
+
+  // Help & Version
+  if (args.includes("-v") || args.includes("--version")) {
+    output.log(VERSION);
+    output.exit(0);
+  }
+
+  if (args.includes("-h") || args.includes("--help")) {
+    output.log(`Usage: papagaio [options] <file1> [file2] [...]
+
+Options:
+  -h, --help            Show this help message
+  -v, --version         Show version number
+  --sigil <symbol>      Set sigil symbol
+  --open <symbol>       Set open symbol
+  --close <symbol>      Set close symbol
+
+Examples:
+  papagaio input.txt
+  papagaio file1.txt file2.txt file3.txt
+  papagaio *.txt
+  papagaio --sigil @ --open [ --close ] input.txt`);
+    output.exit(0);
+  }
+
+  // Parse options
+  const sigilIndex = args.findIndex(arg => arg === "--sigil");
+  const openIndex = args.findIndex(arg => arg === "--open");
+  const closeIndex = args.findIndex(arg => arg === "--close");
+
+  const sigil = sigilIndex !== -1 ? args[sigilIndex + 1] : undefined;
+  const open = openIndex !== -1 ? args[openIndex + 1] : undefined;
+  const close = closeIndex !== -1 ? args[closeIndex + 1] : undefined;
+
+  // Get input files
+  const files = args.filter((arg, i) => {
+    if (arg.startsWith("-")) return false;
+    if (i > 0 && (args[i - 1] === "--sigil" || args[i - 1] === "--open" || args[i - 1] === "--close")) return false;
+    return true;
+  });
+
+  if (files.length === 0) {
+    output.error("Error: no input file specified.\nUse --help for usage.");
+    output.exit(1);
+  }
+
+  // ============================================================================
+  // FILE READING ABSTRACTION
+  // ============================================================================
+  function readFile(filepath) {
+    if (isQuickJS) {
+      const f = std.open(filepath, "r");
+      if (!f) {
+        throw new Error(`cannot open file '${filepath}'`);
+      }
+      const content = f.readAsString();
+      f.close();
+      return content;
+    } else {
+      if (!fs.existsSync(filepath)) {
+        throw new Error(`file not found: ${filepath}`);
+      }
+      return fs.readFileSync(filepath, "utf8");
+    }
+  }
+
+  // ============================================================================
+  // READ AND CONCATENATE FILES
+  // ============================================================================
+  let concatenatedSrc = "";
+  let hasErrors = false;
+
+  for (const file of files) {
+    try {
+      const src = readFile(file);
+      concatenatedSrc += src;
+    } catch (error) {
+      output.error(`Error reading ${file}: ${error.message || error}`);
+      hasErrors = true;
+    }
+  }
+
+  if (hasErrors) {
+    output.exit(1);
+  }
+
+  // ============================================================================
+  // PROCESS CONCATENATED INPUT
+  // ============================================================================
+  const p = new Papagaio(sigil, open, close);
+  const out = p.process(concatenatedSrc);
+  output.log(out);
+}
+
+// Executa main
+main().catch(err => {
+  const output = isQuickJS 
+    ? (msg) => std.err.puts(msg + "\n")
+    : console.error;
+  output("Fatal error: " + (err.message || err));
+  const exit = isQuickJS ? std.exit : process.exit;
+  exit(1);
+});

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>