precedent 1.0.14 → 1.0.16

package/.babelrc

@@ -0,0 +1,5 @@
+{
+    "presets": [
+        "@babel/preset-env"
+    ]
+}

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to Retold
+
+We welcome contributions to Retold and its modules. This guide covers the expectations and process for contributing.
+
+## Code of Conduct
+
+The Retold community values **empathy**, **equity**, **kindness**, and **thoughtfulness**. We expect all participants to treat each other with respect, assume good intent, and engage constructively. These values apply to all interactions: pull requests, issues, discussions, and code review.
+
+## How to Contribute
+
+### Pull Requests
+
+Pull requests are the preferred method for contributing changes. To submit one:
+
+1. Fork the module repository you want to change
+2. Create a branch for your work
+3. Make your changes, following the code style of the module you are editing
+4. Ensure your changes have test coverage (see below)
+5. Open a pull request against the module's main branch
+
+**Submitting a pull request does not guarantee it will be accepted.** Maintainers review contributions for fit, quality, and alignment with the project's direction. A PR may be declined, or you may be asked to revise it. This is normal and not a reflection on the quality of your effort.
+
+### Reporting Issues
+
+If you find a bug or have a feature suggestion, open an issue on the relevant module's repository. Include enough detail to reproduce the problem or understand the proposal.
+
+## Test Coverage
+
+Every commit must include test coverage for the changes it introduces. Retold modules use Mocha in TDD style. Before submitting:
+
+- **Write tests** for any new functionality or bug fixes
+- **Run the existing test suite** with `npm test` and confirm all tests pass
+- **Check coverage** with `npm run coverage` if the module supports it
+
+Pull requests that break existing tests or lack coverage for new code will not be merged.
+
+## Code Style
+
+Follow the conventions of the module you are working in. The general Retold style is:
+
+- **Tabs** for indentation, never spaces
+- **Plain JavaScript** only (no TypeScript)
+- **Allman-style braces** (opening brace on its own line)
+- **Variable naming:** `pVariable` for parameters, `tmpVariable` for temporaries, `libSomething` for imports
+
+When in doubt, match what the surrounding code does.
+
+## Repository Structure
+
+Each module is its own git repository. The [retold](https://github.com/stevenvelozo/retold) repository tracks module organization but does not contain module source code. Direct your pull request to the specific module repository where your change belongs.

package/README.md

@@ -1,76 +1,149 @@
 # Precedent
-Precedent meta-templating engine, for when you want templates ... for templates.
 
-[![Code Climate](https://codeclimate.com/github/stevenvelozo/precedent/badges/gpa.svg)](https://codeclimate.com/github/stevenvelozo/precedent) [![Build Status](https://travis-ci.org/stevenvelozo/precedent.svg?branch=master)](https://travis-ci.org/stevenvelozo/precedent) [![Dependency Status](https://david-dm.org/stevenvelozo/precedent.svg)](https://david-dm.org/stevenvelozo/precedent) [![devDependency Status](https://david-dm.org/stevenvelozo/precedent/dev-status.svg)](https://david-dm.org/stevenvelozo/precedent#info=devDependencies)
+A meta-templating engine for processing text streams with pattern-based template expressions. Define start/end pattern markers with string or function parsers, and Precedent handles nested pattern resolution automatically.
 
-## Template Patterns
+[![Coverage Status](https://coveralls.io/repos/github/stevenvelozo/precedent/badge.svg?branch=master)](https://coveralls.io/github/stevenvelozo/precedent?branch=master)
+[![Build Status](https://github.com/stevenvelozo/precedent/workflows/Precedent/badge.svg)](https://github.com/stevenvelozo/precedent/actions)
+[![npm version](https://badge.fury.io/js/precedent.svg)](https://badge.fury.io/js/precedent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Precedent works on the concept of "Template Patterns".  These are regions of text that are replaced by their template function.  Because patterns are defined in a tree data structure, nested patterns (such as `<%`, `<%=`, `<$$` and `<`) properly get parsed in the same process run.
-
-So, for instance, you could create a pattern like so:
+---
 
+## Features
 
-```js
-// Load the precedent library
-var libPrecedent = require('../source/Precedent.js').new();
+- **Pattern-Based Parsing** - Define start/end markers to identify template regions in text
+- **String or Function Parsers** - Replace patterns with static strings or dynamic function output
+- **Nested Pattern Support** - Overlapping pattern prefixes (e.g. `<%`, `<%=`, `<$$`) resolve correctly in a single pass
+- **Word Tree Architecture** - Patterns are stored in a tree structure for efficient matching
+- **Data Passing** - Pass a data object through to parser functions for context-aware rendering
+- **Browser Compatible** - Works in both Node.js and browser environments
+- **Zero Dependencies** - No external runtime dependencies
 
-// Add the pattern
-libPrecedent.addPattern('{Name', '}', 'David Bowie');
+## Installation
 
-// Parse a string with the pattern
-console.log(libPrecedent.parseString('This is just a short message for {Name}.');
-// Anything inbetween the start and end is ignored in this case, since it is a string substitution.
-console.log(libPrecedent.parseString('This is just a short message for {Name THIS TEXT IS IGNORED}.  We hope to ignore the previous text.');
+```bash
+npm install precedent
 ```
 
-This would output the following to the console:
+## Quick Start
+
+```javascript
+const Precedent = require('precedent');
+
+const precedent = new Precedent();
 
+// Add a simple string substitution pattern
+precedent.addPattern('{Name', '}', 'David Bowie');
+
+// Parse a string containing the pattern
+precedent.parseString('Hello, {Name}!');
+// => "Hello, David Bowie!"
 ```
-This is just a short message for David Bowie.
-This is just a short message for David Bowie.  We hope to ignore the previous text.
+
+## Usage
+
+### String Substitution
+
+Replace patterns with a fixed string value. Content between the start and end markers is ignored:
+
+```javascript
+const precedent = new Precedent();
+
+precedent.addPattern('{Name', '}', 'David Bowie');
+
+precedent.parseString('A message for {Name}.');
+// => "A message for David Bowie."
+
+// Content between markers is ignored for string substitutions
+precedent.parseString('A message for {Name IGNORED TEXT}.');
+// => "A message for David Bowie."
 ```
 
----
+### Function-Based Parsing
+
+Pass a function as the parser to dynamically process the content between markers:
+
+```javascript
+const precedent = new Precedent();
 
-## precedent.addPattern(patternStart, patternEnd, parser)
+precedent.addPattern('{Length', '}', (pString) => { return pString.length; });
 
-Add a pattern to the string processor.
+precedent.parseString('The length is {Length some text}.');
+// => "The length is  some text."  (length of " some text")
+```
+
+### Passing Data to Parsers
+
+A data object can be passed as the second argument to `parseString`, which is then available to parser functions:
 
 ```javascript
-// Pass in a string
-libPrecedent.addPattern('{Name', '}', 'David Bowie');
+const precedent = new Precedent();
 
-// Or a function
-libPrecedent.addPattern('{Name', '}', (pString)=>{return pString.length;});
+precedent.addPattern('<%=', '%>', (pContent, pData) =>
+{
+	return pData[pContent.trim()] || '';
+});
+
+precedent.parseString('Hello, <%= username %>!', { username: 'Steven' });
+// => "Hello, Steven!"
 ```
 
-Each time a pattern is matched, anything between the `patternStart` and `patternEnd` will be passed into the parse function.
+## API
 
-#### patternStart
-Type: `String`
+### `addPattern(patternStart, patternEnd, parser)`
 
-The beginning portion of a pattern.
+Add a pattern to the parse tree.
 
-#### patternEnd
-Type: `String`
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `patternStart` | `String` | The opening marker for the pattern |
+| `patternEnd` | `String` | The closing marker for the pattern |
+| `parser` | `String` or `Function` | Replacement string, or function receiving `(content, data)` |
 
-The ending portion of a pattern.
+Returns `true` if the pattern was added successfully.
 
-##### parser
-Type: `String` or `Function`
-Default: Echo content between the pattern start and end.
+### `parseString(contentString, data)`
 
----
+Parse a string against all registered patterns.
 
-## precedent.parseString(contentString)
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `contentString` | `String` | The text to parse |
+| `data` | `Object` | Optional data object passed to parser functions |
 
-Parse a string with the processor.
+Returns the parsed string.
 
-```javascript
-libPrecedent.parseString('This is just a short message for {Name}.'
+## Part of the Retold Framework
+
+Precedent is used throughout the Fable ecosystem for template processing:
+
+- [fable](https://github.com/stevenvelozo/fable) - Application services framework
+- [pict](https://github.com/stevenvelozo/pict) - UI framework
+- [pict-template](https://github.com/stevenvelozo/pict-template) - Template engine built on Precedent
+
+## Testing
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+Run with coverage:
+
+```bash
+npm run coverage
 ```
 
-#### contentString
-Type: `String`
+## Related Packages
+
+- [fable](https://github.com/stevenvelozo/fable) - Application services framework
+- [pict-template](https://github.com/stevenvelozo/pict-template) - Template engine
+
+## License
+
+MIT
+
+## Contributing
 
-The string of content to parseg
+Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the [Retold Contributing Guide](https://github.com/stevenvelozo/retold/blob/main/docs/contributing.md).

package/docs/README.md

@@ -0,0 +1,142 @@
+# Precedent
+
+A meta-templating engine that parses text strings and replaces delimited regions with custom output. Register start/end delimiter pairs, attach a handler function or replacement string, then parse any text through the engine.
+
+Precedent is the foundation beneath Pict's `{~...~}` template expression system and Fable Settings' `${...}` environment variable substitution. It has zero runtime dependencies and works in both Node.js and the browser.
+
+## Install
+
+```bash
+npm install precedent
+```
+
+## Quick Start
+
+```javascript
+const libPrecedent = require('precedent');
+let processor = new libPrecedent();
+
+// Register a pattern: replace anything between << and >> with "REDACTED"
+processor.addPattern('<<', '>>', 'REDACTED');
+
+let result = processor.parseString('The code is <<SECRET123>> end.');
+// => "The code is REDACTED end."
+```
+
+## Core Concepts
+
+### 1. Patterns
+
+A pattern is a pair of delimiter strings (start and end) plus a handler. When the parser encounters the start delimiter in a string, it captures everything until the end delimiter, then calls the handler.
+
+```javascript
+processor.addPattern(startDelimiter, endDelimiter, handler);
+```
+
+### 2. Handlers
+
+The handler can be:
+
+| Type | Behavior |
+|------|----------|
+| **string** | The matched region is replaced with this string |
+| **function** | Called with `(content, data)` — content between delimiters and the data argument from `parseString()` |
+| **omitted** | The content between delimiters is passed through unchanged |
+
+### 3. Data Passing
+
+The second argument to `parseString()` is passed to every handler function as its second parameter:
+
+```javascript
+processor.addPattern('{', '}',
+	(pContent, pData) =>
+	{
+		return pData[pContent];
+	});
+
+let result = processor.parseString('Hello, {name}!', { name: 'Alice' });
+// => "Hello, Alice!"
+```
+
+### 4. Pattern Precedence
+
+Patterns are stored in a character-by-character word tree (directed graph). When multiple patterns share a prefix, the longest matching start delimiter wins:
+
+```javascript
+processor.addPattern('<', '>', 'SHORT');
+processor.addPattern('<<', '>', 'MEDIUM');
+processor.addPattern('<<LONG', '>', 'LONG');
+
+processor.parseString('<x>');        // => "SHORT"
+processor.parseString('<<x>');       // => "MEDIUM"
+processor.parseString('<<LONGx>');   // => "LONG"
+```
+
+If a longer match starts but fails to complete, the parser falls back to the shorter match.
+
+## How It Works
+
+```
+             addPattern('${', '}', fn)
+                       │
+                       ▼
+┌──────────────────────────────────┐
+│  WordTree                        │
+│                                  │
+│  Builds a character-by-character │
+│  tree from start delimiters.     │
+│  End delimiters are stored as    │
+│  subtrees on the terminal node.  │
+│                                  │
+│   $ ──▶ { ──▶ PatternEnd ──▶ }  │
+│                       └─ Parse() │
+└──────────────────────────────────┘
+                       │
+                       ▼
+┌──────────────────────────────────┐
+│  StringParser                    │
+│                                  │
+│  Scans character by character:   │
+│  1. Match start delimiter chars  │
+│  2. Buffer content               │
+│  3. Match end delimiter chars    │
+│  4. Call Parse(content, data)    │
+│  5. Replace matched region       │
+└──────────────────────────────────┘
+```
+
+The parser is stateful and stream-oriented — it processes one character at a time, tracking whether it is in raw mode, matching a start delimiter, buffering content, or matching an end delimiter.
+
+## Architecture
+
+Precedent consists of three classes:
+
+| Class | Responsibility |
+|-------|---------------|
+| **Precedent** | Public facade — exposes `addPattern()` and `parseString()` |
+| **WordTree** | Stores delimiter patterns in a character-based tree structure |
+| **StringParser** | Character-by-character parser that traverses the tree and invokes handlers |
+
+## Browser Usage
+
+The browser shim (`Precedent-Browser-Shim.js`) assigns the constructor to `window.Precedent`:
+
+```html
+<script src="precedent.min.js"></script>
+<script>
+	var processor = new Precedent();
+	processor.addPattern('{{', '}}', function(content) { return content.toUpperCase(); });
+	document.body.innerHTML = processor.parseString('Hello {{world}}');
+	// => "Hello WORLD"
+</script>
+```
+
+Build with Quackage: `npx quack build`
+
+## Where Precedent Is Used
+
+| Consumer | Pattern | Purpose |
+|----------|---------|---------|
+| **Fable Settings** | `${VAR\|default}` | Environment variable substitution in configuration |
+| **Pict** | `{~Prefix:content~}` | 40+ template expression types for data, logic, rendering |
+| **Pict Template** | Custom patterns | Base class for all Pict template expressions |

package/docs/_sidebar.md

@@ -0,0 +1,19 @@
+- Getting Started
+
+  - [Overview](README.md)
+
+- Reference
+
+  - [API Reference](api.md)
+
+- Examples
+
+  - [Usage Patterns](examples.md)
+
+- Retold Ecosystem
+
+  - [Pict](/pict/pict/)
+  - [Pict Template](/pict/pict-template/)
+  - [Fable](/fable/fable/)
+  - [Fable Settings](/fable/fable-settings/)
+  - [Indoctrinate](/utility/indoctrinate/)

package/docs/_topbar.md

@@ -0,0 +1,5 @@
+# Precedent
+
+- [Overview](README.md)
+- [API Reference](api.md)
+- [GitHub](https://github.com/stevenvelozo/precedent)

package/docs/api.md

@@ -0,0 +1,209 @@
+# API Reference
+
+## Class: Precedent
+
+The main public interface. Creates a WordTree for pattern storage and a StringParser for execution.
+
+### Constructor
+
+```javascript
+const libPrecedent = require('precedent');
+let processor = new libPrecedent();
+```
+
+No parameters. The constructor initializes an empty parse tree.
+
+---
+
+## Properties
+
+### ParseTree
+
+The root node of the internal word tree. This is the directed graph that stores all registered patterns as character-by-character paths.
+
+**Type:** `object`
+
+Inspect it to see the current tree structure:
+
+```javascript
+processor.addPattern('${', '}', myHandler);
+console.log(JSON.stringify(processor.ParseTree, null, 2));
+```
+
+### WordTree
+
+The WordTree instance that manages pattern storage.
+
+**Type:** `WordTree`
+
+### StringParser
+
+The StringParser instance that executes pattern matching.
+
+**Type:** `StringParser`
+
+---
+
+## Methods
+
+### addPattern(pPatternStart, pPatternEnd, pParser)
+
+Register a delimiter pair and a handler with the parse tree.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pPatternStart` | string | Yes | The opening delimiter (e.g. `'${'`, `'<%'`, `'<'`) |
+| `pPatternEnd` | string | No | The closing delimiter (e.g. `'}'`, `'%>'`, `'>'`). If omitted, defaults to `pPatternStart` |
+| `pParser` | string \| function | No | The handler (see below) |
+
+**Returns:** `boolean` — `true` if the pattern was added, `false` if the start or end delimiter was empty.
+
+#### Handler Types
+
+**String handler** — Replace the matched region with this literal string:
+
+```javascript
+processor.addPattern('<%', '%>', 'REPLACED');
+processor.parseString('A <%stuff%> B');
+// => "A REPLACED B"
+```
+
+**Function handler** — Called with two arguments:
+
+| Argument | Description |
+|----------|-------------|
+| `pContent` | The text between the start and end delimiters (delimiters stripped) |
+| `pData` | The second argument passed to `parseString()` |
+
+```javascript
+processor.addPattern('<%#', '%>',
+	(pContent, pData) =>
+	{
+		return pContent.length;
+	});
+
+processor.parseString('Count: <%#ABCDE%>');
+// => "Count: 5"
+```
+
+**No handler** — The content between delimiters is passed through (delimiters are stripped):
+
+```javascript
+processor.addPattern('$');
+processor.parseString('A $comment$ B');
+// => "A comment B"
+```
+
+#### Self-Closing Patterns
+
+When only `pPatternStart` is provided (no end delimiter), the start string is used as both the opening and closing delimiter:
+
+```javascript
+processor.addPattern('$');
+// Equivalent to: processor.addPattern('$', '$')
+
+processor.parseString('Hello $World$ Goodbye');
+// => "Hello World Goodbye"
+```
+
+---
+
+### parseString(pString, pData)
+
+Parse a string against all registered patterns, replacing matched regions with handler output.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pString` | string | Yes | The text to parse |
+| `pData` | any | No | Passed as the second argument to every function handler |
+
+**Returns:** `string` — The processed string with all matched patterns replaced.
+
+```javascript
+processor.addPattern('{', '}',
+	(pContent, pData) =>
+	{
+		return pData[pContent] || pContent;
+	});
+
+let result = processor.parseString(
+	'Hello {name}, welcome to {place}.',
+	{ name: 'Alice', place: 'Wonderland' }
+);
+// => "Hello Alice, welcome to Wonderland."
+```
+
+If no patterns match, the input string is returned unchanged.
+
+---
+
+## Class: WordTree
+
+Builds and maintains the internal directed graph for pattern matching. You rarely interact with this directly — `Precedent.addPattern()` delegates to it.
+
+### addPattern(pPatternStart, pPatternEnd, fParser)
+
+Adds a pattern to the tree. Each character of the start delimiter becomes a node. The end delimiter is stored as a subtree (`PatternEnd`) on the terminal start node. The handler function is stored on the terminal end node as `Parse`.
+
+**Returns:** `boolean`
+
+### Tree Structure
+
+For `addPattern('${', '}', fn)`, the tree looks like:
+
+```
+ParseTree
+  └── '$'
+       └── '{'
+            └── PatternEnd
+                 └── '}'
+                      ├── PatternStartString: '${'
+                      ├── PatternEndString: '}'
+                      └── Parse: fn
+```
+
+Multiple patterns sharing a prefix character (e.g. `<`, `<<`, `<<LONG`) branch naturally within the tree, enabling longest-match-first behavior.
+
+---
+
+## Class: StringParser
+
+Character-by-character parser that traverses the WordTree and executes handler functions. You rarely interact with this directly — `Precedent.parseString()` delegates to it.
+
+### parseString(pString, pParseTree, pData)
+
+Scans the input string one character at a time, maintaining a state object that tracks:
+
+| State Property | Purpose |
+|---------------|---------|
+| `Output` | Accumulated final output |
+| `OutputBuffer` | Characters being buffered during a potential match |
+| `Pattern` | Current node in the word tree |
+| `PatternMatch` | Whether we are currently in a pattern match |
+| `StartPatternMatchComplete` | Whether the full start delimiter has been matched |
+| `EndPatternMatchBegan` | Whether end delimiter matching has started |
+
+### Parsing Flow
+
+1. **Raw mode** — Characters are buffered directly to output
+2. **Start match** — A character matches the tree root; parser begins traversing the tree
+3. **Content capture** — Start delimiter fully matched; characters are buffered as content
+4. **End match** — End delimiter characters begin matching the PatternEnd subtree
+5. **Execution** — End delimiter fully matched; handler is called with `(content, data)`
+6. **Replacement** — Handler output replaces the entire matched region (delimiters + content)
+7. **Reset** — Parser returns to raw mode
+
+If a partial start match fails (the next character does not continue the tree path), the buffered characters are flushed as-is and the parser resets to raw mode.
+
+---
+
+## Error Handling
+
+| Condition | Behavior |
+|-----------|----------|
+| Empty start delimiter | `addPattern()` returns `false` |
+| Empty end delimiter | `addPattern()` returns `false` |
+| Empty input string | `parseString()` returns `''` |
+| No matching patterns | Input is returned unchanged |
+| Unmatched start delimiter | Start delimiter characters pass through as-is |
+| Nested start delimiters | Inner start is treated as content, not a new match |

package/docs/cover.md

@@ -0,0 +1,15 @@
+# Precedent
+
+> A zero-dependency meta-templating engine for Node.js and the browser
+
+Define arbitrary delimiter patterns and replace them with strings, computed values, or function output. Precedent powers the `{~...~}` expression system in Pict and the `${...}` environment variable substitution in Fable Settings.
+
+- **Custom Delimiters** -- Register any start/end string pair as a pattern with `addPattern()`
+- **Function Handlers** -- Patterns can replace with static strings or call a function with the matched content and a data argument
+- **Pattern Precedence** -- A word tree ensures longer delimiters match before shorter ones (`<<EXTRA` before `<<` before `<`)
+- **Zero Dependencies** -- No runtime dependencies; under 300 lines of code
+- **Browser Ready** -- Includes a browser shim that assigns `window.Precedent`; builds with Quackage
+
+[Quick Start](README.md)
+[API Reference](api.md)
+[GitHub](https://github.com/stevenvelozo/precedent)