fable 3.1.71 → 3.1.73

package/docs/services/meta-template.md

@@ -1,26 +1,54 @@
 # MetaTemplate Service
 
+The MetaTemplate service is a **low-level pattern-replacement primitive**.
+You register one or more `(start, end, parserFn)` patterns; `parseString()`
+then walks the template string character by character, hands each
+between-tag region to the matching parser function, and emits the
+function's return value into the output.
+
+It is intentionally minimal: there are no built-in tags. The `{~Name~}`
+syntax shown below is just convention — every pattern is something you
+wire up yourself with `addPattern()`. End markers are short by design
+(typically 1–2 characters such as `~}`, `>>`, `}`); the engine's
+character-by-character WordTree match is built around that.
+
 ## Access
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'MetaTemplateDemo', ProductVersion: '1.0.0' });
+
 // On-demand service - instantiate when needed
 const metaTemplate = fable.instantiateServiceProvider('MetaTemplate');
+console.log('parseString:', typeof metaTemplate.parseString);
+console.log('addPattern:',  typeof metaTemplate.addPattern);
 ```
 
 ## Basic Usage
 
-### Simple Template
+### Register a Substitution Pattern
+
+The minimum useful setup: one `{~name~}` pattern whose parser function
+resolves `name` against the data object using dot/bracket notation.
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'MetaTemplateDemo', ProductVersion: '1.0.0' });
 const metaTemplate = fable.instantiateServiceProvider('MetaTemplate');
 
-const result = metaTemplate.render('Hello, {~Name~}!', { Name: 'World' });
-// Returns 'Hello, World!'
+metaTemplate.addPattern('{~', '~}', (pInner, pData) => {
+    const value = fable.Utility.getValueByHash(pData, pInner.trim());
+    return value == null ? '' : String(value);
+});
+
+const result = metaTemplate.parseString('Hello, {~Name~}!', { Name: 'World' });
+console.log(result);  // 'Hello, World!'
 ```
 
-### Template Syntax
+### Template Syntax (this convention)
 
-MetaTemplate uses a different syntax from the standard Template service:
+With the `{~ ~}` pattern registered above, these all work because
+`fable.Utility.getValueByHash` understands dot/bracket paths:
 
 | Pattern | Description | Example |
 |---------|-------------|---------|
@@ -28,125 +56,185 @@ MetaTemplate uses a different syntax from the standard Template service:
 | `{~Object.Property~}` | Nested property | `{~User.Name~}` |
 | `{~Array[0]~}` | Array access | `{~Items[0]~}` |
 
-## Advanced Features
-
-### Conditional Rendering
-
 ```javascript
-const template = `
-{~Begin:If:ShowGreeting~}
-Hello, {~Name~}!
-{~End:If:ShowGreeting~}
-`;
+const libFable = require('fable');
+const fable = new libFable({ Product: 'MetaTemplateDemo', ProductVersion: '1.0.0' });
+const metaTemplate = fable.instantiateServiceProvider('MetaTemplate');
 
-metaTemplate.render(template, { ShowGreeting: true, Name: 'World' });
-// Returns 'Hello, World!'
+metaTemplate.addPattern('{~', '~}', (pInner, pData) => {
+    const value = fable.Utility.getValueByHash(pData, pInner.trim());
+    return value == null ? '' : String(value);
+});
 
-metaTemplate.render(template, { ShowGreeting: false, Name: 'World' });
-// Returns ''
+const data = {
+    User:  { Name: 'Alice' },
+    Items: ['first', 'second', 'third']
+};
+
+console.log(metaTemplate.parseString('Name: {~User.Name~}, Item 1: {~Items[0]~}, Item 3: {~Items[2]~}', data));
 ```
 
-### Iteration
+## Iteration (via parser-function logic)
+
+The parser function receives the iterator address and inline body
+separated by `|`, looks up the array, and joins the rendered bodies:
 
 ```javascript
-const template = `
-{~Begin:Each:Items~}
-- {~Record.Name~}: {~Record.Value~}
-{~End:Each:Items~}
-`;
+const libFable = require('fable');
+const fable = new libFable({ Product: 'MetaTemplateDemo', ProductVersion: '1.0.0' });
+const metaTemplate = fable.instantiateServiceProvider('MetaTemplate');
+
+// {~each ItemsAddress|template-using-{{Record.Field}}~}
+// Use {{ }} inside the body to reference per-row fields; the parser
+// substitutes them per iteration.
+metaTemplate.addPattern('{~each ', '~}', (pInner, pData) => {
+    const sepIndex = pInner.indexOf('|');
+    const address  = pInner.slice(0, sepIndex).trim();
+    const body     = pInner.slice(sepIndex + 1);
+    const list     = fable.Utility.getValueByHash(pData, address) || [];
+
+    return list.map((Record) =>
+        body.replace(/\{\{([^}]+)\}\}/g, (_, hash) => {
+            const v = fable.Utility.getValueByHash({ Record }, hash.trim());
+            return v == null ? '' : String(v);
+        })
+    ).join('');
+});
 
 const data = {
     Items: [
-        { Name: 'Apple', Value: 1.50 },
+        { Name: 'Apple',  Value: 1.50 },
         { Name: 'Banana', Value: 0.75 }
     ]
 };
 
-metaTemplate.render(template, data);
-// Returns:
-// - Apple: 1.50
-// - Banana: 0.75
+const out = metaTemplate.parseString('{~each Items|- {{Record.Name}}: {{Record.Value}}\n~}', data);
+console.log(out);
 ```
 
-### Nested Templates
+## Nested Templates (two-pass rendering)
+
+`parseString` is sync when no callback is provided. Render the inner
+fragment first, then drop the result into the outer template's data:
 
 ```javascript
-const outerTemplate = `
-<div class="container">
-{~InnerContent~}
-</div>
-`;
+const libFable = require('fable');
+const fable = new libFable({ Product: 'MetaTemplateDemo', ProductVersion: '1.0.0' });
+const metaTemplate = fable.instantiateServiceProvider('MetaTemplate');
 
-const innerContent = '<p>Hello, {~Name~}!</p>';
+metaTemplate.addPattern('{~', '~}', (pInner, pData) => {
+    const value = fable.Utility.getValueByHash(pData, pInner.trim());
+    return value == null ? '' : String(value);
+});
 
-// First render inner
-const inner = metaTemplate.render(innerContent, { Name: 'World' });
+const innerContent = '<p>Hello, {~Name~}!</p>';
+const outerTemplate = '<div class="container">\n{~InnerContent~}\n</div>';
 
-// Then render outer
-const outer = metaTemplate.render(outerTemplate, { InnerContent: inner });
+const inner = metaTemplate.parseString(innerContent, { Name: 'World' });
+const outer = metaTemplate.parseString(outerTemplate, { InnerContent: inner });
+console.log(outer);
 ```
 
-## Template Inheritance
+## Template Inheritance (compose strings, render once)
 
-### Define Base Template
+There is no native template-inheritance system — the same effect is
+achieved by composing the final template string in JS, then calling
+`parseString` once.
+
+### Define a Base Template
 
 ```javascript
-const baseTemplate = `
-<!DOCTYPE html>
-<html>
-<head><title>{~Title~}</title></head>
-<body>
-    <header>{~Header~}</header>
-    <main>{~Content~}</main>
-    <footer>{~Footer~}</footer>
-</body>
-</html>
-`;
+const baseTemplate = [
+    '<!DOCTYPE html>',
+    '<html>',
+    '<head><title>{~Title~}</title></head>',
+    '<body>',
+    '    <header>{~Header~}</header>',
+    '    <main>{~Content~}</main>',
+    '    <footer>{~Footer~}</footer>',
+    '</body>',
+    '</html>'
+].join('\n');
+
+console.log('baseTemplate length:', baseTemplate.length, 'chars');
 ```
 
-### Extend Template
+### Use the Base Template
 
 ```javascript
+const libFable = require('fable');
+const fable = new libFable({ Product: 'MetaTemplateDemo', ProductVersion: '1.0.0' });
+const metaTemplate = fable.instantiateServiceProvider('MetaTemplate');
+
+metaTemplate.addPattern('{~', '~}', (pInner, pData) => {
+    const value = fable.Utility.getValueByHash(pData, pInner.trim());
+    return value == null ? '' : String(value);
+});
+
+const baseTemplate = [
+    '<!DOCTYPE html>',
+    '<html>',
+    '<head><title>{~Title~}</title></head>',
+    '<body>',
+    '    <header>{~Header~}</header>',
+    '    <main>{~Content~}</main>',
+    '    <footer>{~Footer~}</footer>',
+    '</body>',
+    '</html>'
+].join('\n');
+
 const pageData = {
-    Title: 'My Page',
-    Header: '<h1>Welcome</h1>',
+    Title:   'My Page',
+    Header:  '<h1>Welcome</h1>',
     Content: '<p>Main content here</p>',
-    Footer: '<p>&copy; 2024</p>'
+    Footer:  '<p>&copy; 2024</p>'
 };
 
-const page = metaTemplate.render(baseTemplate, pageData);
+const page = metaTemplate.parseString(baseTemplate, pageData);
+console.log(page);
 ```
 
 ## Use Cases
 
-### Email Templates
+### Email Templates (substitution + iteration patterns)
 
 ```javascript
-const emailTemplate = `
-Dear {~Recipient.Name~},
-
-{~Begin:If:HasOrder~}
-Your order #{~Order.Number~} has been {~Order.Status~}.
-
-Items:
-{~Begin:Each:Order.Items~}
-- {~Record.Name~} x {~Record.Quantity~}: ${~Record.Price~}
-{~End:Each:Order.Items~}
-
-Total: ${~Order.Total~}
-{~End:If:HasOrder~}
+const libFable = require('fable');
+const fable = new libFable({ Product: 'MetaTemplateDemo', ProductVersion: '1.0.0' });
+const metaTemplate = fable.instantiateServiceProvider('MetaTemplate');
 
-{~Begin:If:IsPromotion~}
-Special offer: {~Promotion.Message~}
-{~End:If:IsPromotion~}
+metaTemplate.addPattern('{~', '~}', (pInner, pData) => {
+    const value = fable.Utility.getValueByHash(pData, pInner.trim());
+    return value == null ? '' : String(value);
+});
+metaTemplate.addPattern('{~each ', '~}', (pInner, pData) => {
+    const sepIndex = pInner.indexOf('|');
+    const address  = pInner.slice(0, sepIndex).trim();
+    const body     = pInner.slice(sepIndex + 1);
+    const list     = fable.Utility.getValueByHash(pData, address) || [];
+    return list.map((Record) =>
+        body.replace(/\{\{([^}]+)\}\}/g, (_, hash) => {
+            const v = fable.Utility.getValueByHash({ Record }, hash.trim());
+            return v == null ? '' : String(v);
+        })
+    ).join('');
+});
 
-Best regards,
-{~Sender.Name~}
-`;
+const emailTemplate = [
+    'Dear {~Recipient.Name~},',
+    '',
+    'Your order #{~Order.Number~} has been {~Order.Status~}.',
+    '',
+    'Items:',
+    '{~each Order.Items|- {{Record.Name}} x {{Record.Quantity}}: ${{Record.Price}}\n~}',
+    'Total: ${~Order.Total~}',
+    '',
+    'Best regards,',
+    '{~Sender.Name~}'
+].join('\n');
 
 const emailData = {
     Recipient: { Name: 'John' },
-    HasOrder: true,
     Order: {
         Number: '12345',
         Status: 'shipped',
@@ -156,113 +244,179 @@ const emailData = {
         ],
         Total: '109.97'
     },
-    IsPromotion: false,
     Sender: { Name: 'Support Team' }
 };
 
-const email = metaTemplate.render(emailTemplate, emailData);
+console.log(metaTemplate.parseString(emailTemplate, emailData));
 ```
 
-### Report Generation
+### Report Generation (substitution + iteration)
 
 ```javascript
-const reportTemplate = `
-# {~Report.Title~}
-Generated: {~Report.Date~}
-
-## Summary
-- Total Records: {~Summary.TotalRecords~}
-- Processed: {~Summary.Processed~}
-- Errors: {~Summary.Errors~}
-
-## Details
-{~Begin:Each:Details~}
-### {~Record.Category~}
-{~Record.Description~}
-Count: {~Record.Count~}
-{~End:Each:Details~}
-
-{~Begin:If:HasWarnings~}
-## Warnings
-{~Begin:Each:Warnings~}
-- {~Record~}
-{~End:Each:Warnings~}
-{~End:If:HasWarnings~}
-`;
+const libFable = require('fable');
+const fable = new libFable({ Product: 'MetaTemplateDemo', ProductVersion: '1.0.0' });
+const metaTemplate = fable.instantiateServiceProvider('MetaTemplate');
+
+metaTemplate.addPattern('{~', '~}', (pInner, pData) => {
+    const value = fable.Utility.getValueByHash(pData, pInner.trim());
+    return value == null ? '' : String(value);
+});
+metaTemplate.addPattern('{~each ', '~}', (pInner, pData) => {
+    const sepIndex = pInner.indexOf('|');
+    const address  = pInner.slice(0, sepIndex).trim();
+    const body     = pInner.slice(sepIndex + 1);
+    const list     = fable.Utility.getValueByHash(pData, address) || [];
+    return list.map((Record) =>
+        body.replace(/\{\{([^}]+)\}\}/g, (_, hash) => {
+            const v = fable.Utility.getValueByHash({ Record }, hash.trim());
+            return v == null ? '' : String(v);
+        })
+    ).join('');
+});
+
+const reportTemplate = [
+    '# {~Report.Title~}',
+    'Generated: {~Report.Date~}',
+    '',
+    '## Summary',
+    '- Total Records: {~Summary.TotalRecords~}',
+    '- Processed: {~Summary.Processed~}',
+    '- Errors: {~Summary.Errors~}',
+    '',
+    '## Details',
+    '{~each Details|### {{Record.Category}}\n{{Record.Description}}\nCount: {{Record.Count}}\n\n~}'
+].join('\n');
+
+const reportData = {
+    Report:  { Title: 'Sales Report', Date: '2024-01-15' },
+    Summary: { TotalRecords: 1000, Processed: 980, Errors: 20 },
+    Details: [
+        { Category: 'Q1', Description: 'First-quarter results',  Count: 240 },
+        { Category: 'Q2', Description: 'Second-quarter results', Count: 260 }
+    ]
+};
+
+console.log(metaTemplate.parseString(reportTemplate, reportData));
 ```
 
 ### Configuration File Generation
 
 ```javascript
-const configTemplate = `
-# Application Configuration
-# Generated for {~Environment~}
-
-server:
-  host: {~Server.Host~}
-  port: {~Server.Port~}
-
-database:
-  host: {~Database.Host~}
-  name: {~Database.Name~}
-  {~Begin:If:Database.UseSSL~}
-  ssl: true
-  {~End:If:Database.UseSSL~}
-
-{~Begin:Each:Features~}
-{~Record.Name~}:
-  enabled: {~Record.Enabled~}
-{~End:Each:Features~}
-`;
-
-const config = metaTemplate.render(configTemplate, {
+const libFable = require('fable');
+const fable = new libFable({ Product: 'MetaTemplateDemo', ProductVersion: '1.0.0' });
+const metaTemplate = fable.instantiateServiceProvider('MetaTemplate');
+
+metaTemplate.addPattern('{~', '~}', (pInner, pData) => {
+    const value = fable.Utility.getValueByHash(pData, pInner.trim());
+    return value == null ? '' : String(value);
+});
+metaTemplate.addPattern('{~each ', '~}', (pInner, pData) => {
+    const sepIndex = pInner.indexOf('|');
+    const address  = pInner.slice(0, sepIndex).trim();
+    const body     = pInner.slice(sepIndex + 1);
+    const list     = fable.Utility.getValueByHash(pData, address) || [];
+    return list.map((Record) =>
+        body.replace(/\{\{([^}]+)\}\}/g, (_, hash) => {
+            const v = fable.Utility.getValueByHash({ Record }, hash.trim());
+            return v == null ? '' : String(v);
+        })
+    ).join('');
+});
+
+const configTemplate = [
+    '# Application Configuration',
+    '# Generated for {~Environment~}',
+    '',
+    'server:',
+    '  host: {~Server.Host~}',
+    '  port: {~Server.Port~}',
+    '',
+    'database:',
+    '  host: {~Database.Host~}',
+    '  name: {~Database.Name~}',
+    '',
+    '{~each Features|{{Record.Name}}:\n  enabled: {{Record.Enabled}}\n\n~}'
+].join('\n');
+
+const config = metaTemplate.parseString(configTemplate, {
     Environment: 'production',
-    Server: { Host: '0.0.0.0', Port: 8080 },
-    Database: { Host: 'db.example.com', Name: 'myapp', UseSSL: true },
+    Server:   { Host: '0.0.0.0', Port: 8080 },
+    Database: { Host: 'db.example.com', Name: 'myapp' },
     Features: [
         { Name: 'cache', Enabled: true },
         { Name: 'debug', Enabled: false }
     ]
 });
+
+console.log(config);
 ```
 
 ### Dynamic Forms
 
 ```javascript
-const formTemplate = `
-<form action="{~Form.Action~}" method="{~Form.Method~}">
-{~Begin:Each:Form.Fields~}
-    <div class="field">
-        <label for="{~Record.Id~}">{~Record.Label~}</label>
-        <input type="{~Record.Type~}" id="{~Record.Id~}" name="{~Record.Name~}"
-               {~Begin:If:Record.Required~}required{~End:If:Record.Required~}>
-    </div>
-{~End:Each:Form.Fields~}
-    <button type="submit">{~Form.SubmitText~}</button>
-</form>
-`;
+const libFable = require('fable');
+const fable = new libFable({ Product: 'MetaTemplateDemo', ProductVersion: '1.0.0' });
+const metaTemplate = fable.instantiateServiceProvider('MetaTemplate');
+
+metaTemplate.addPattern('{~', '~}', (pInner, pData) => {
+    const value = fable.Utility.getValueByHash(pData, pInner.trim());
+    return value == null ? '' : String(value);
+});
+metaTemplate.addPattern('{~each ', '~}', (pInner, pData) => {
+    const sepIndex = pInner.indexOf('|');
+    const address  = pInner.slice(0, sepIndex).trim();
+    const body     = pInner.slice(sepIndex + 1);
+    const list     = fable.Utility.getValueByHash(pData, address) || [];
+    return list.map((Record) =>
+        body.replace(/\{\{([^}]+)\}\}/g, (_, hash) => {
+            const v = fable.Utility.getValueByHash({ Record }, hash.trim());
+            return v == null ? '' : String(v);
+        })
+    ).join('');
+});
+
+const formTemplate = [
+    '<form action="{~Form.Action~}" method="{~Form.Method~}">',
+    '{~each Form.Fields|    <div class="field"><label for="{{Record.Id}}">{{Record.Label}}</label><input type="{{Record.Type}}" id="{{Record.Id}}" name="{{Record.Name}}"></div>\n~}',
+    '    <button type="submit">{~Form.SubmitText~}</button>',
+    '</form>'
+].join('\n');
+
+console.log(metaTemplate.parseString(formTemplate, {
+    Form: {
+        Action:     '/signup',
+        Method:     'POST',
+        SubmitText: 'Sign Up',
+        Fields: [
+            { Id: 'email', Name: 'email', Label: 'Email', Type: 'email' },
+            { Id: 'name',  Name: 'name',  Label: 'Name',  Type: 'text'  }
+        ]
+    }
+}));
 ```
 
-## Comparison with Template Service
+## Async Mode
 
-| Feature | Template | MetaTemplate |
-|---------|----------|--------------|
-| Syntax | `<%= %>` / `<% %>` | `{~ ~}` |
-| Conditionals | JavaScript `if` | `{~Begin:If~}` |
-| Loops | JavaScript `for` | `{~Begin:Each~}` |
-| JavaScript execution | Yes | Limited |
-| Use case | Code-heavy templates | Data-driven templates |
+Pass a callback to `parseString` to run asynchronously — parser
+functions can complete on their own schedule (via the WordTree's
+`addPatternBoth` async-parser slot). The sync mode used above is
+selected automatically when no callback is supplied.
 
-## Best Practices
+## Comparison with Template Service
 
-1. **Use MetaTemplate for data-driven content**: When templates are mostly about inserting values
-2. **Use Template for logic-heavy content**: When you need complex JavaScript logic
-3. **Keep templates readable**: Use clear section names
-4. **Validate data before rendering**: Ensure required properties exist
+| Feature | Template (`fable.Utility.template`) | MetaTemplate |
+|---------|-------------------------------------|--------------|
+| Syntax | `<%= %>` / `<% %>` (underscore) | Whatever you register via `addPattern` |
+| Control flow | JavaScript `<% if %>` / `<% for %>` | None built in; write parser-function logic for what you need |
+| JavaScript execution | Yes (compiled function body) | No — pure callbacks |
+| Use case | Code-heavy templates | Custom tag syntaxes, replacement-only templates |
 
 ## Notes
 
-- MetaTemplate is designed for safer, more declarative templates
-- Less JavaScript execution means less risk of injection
-- Templates can be stored in files and loaded dynamically
-- The `Record` variable is special within `Each` blocks
+- MetaTemplate has no built-in tag vocabulary; everything is `addPattern`.
+- `parseString` is synchronous unless you pass a callback.
+- The `Record` variable convention used in the iteration examples above
+  is a JS-side helper inside the iteration parser function — there is
+  nothing in MetaTemplate that names it.
+- Keep end markers short (1–2 characters); the WordTree match is built
+  around that.