Ptl (Plain Text Legal)

Latest version: v1.1.0

Install

npm install @davidcal/ptl
pnpm add @davidcal/ptl
yarn add @davidcal/ptl

Overview

Ptl is a simple templating library for generating legal documents (like contracts, terms of service, and so on), with first-class support for substituting user-supplied values.

It concerns itself only with plaintext (UTF-8) templates, which is absolutely acceptable for the vast majority of legal documents.

Reliability and consistency is considered a greater concern than stylishness.

It's recommended to render the final Ptl output as monospace in a PDF/HTML document or similar.

Usage

import { ptl } from "@davidcal/ptl";

const output = ptl.fillTemplate({
	template: `
This Agreement is entered into on $$AGREEMENT_DATE$$ between:

1. SELLER: $$SELLER_NAME::L2 r60 i3 Fh$$, $$SELLER_ADDRESS::L4 r60 i3 Fh$$ ("the Seller")
2. BUYER:  $$BUYER_NAME::L2 r60 i3 Fh$$, $$BUYER_ADDRESS::L4 r60 i3 Fh$$ ("the Buyer")

Each individually a "Party" and collectively 
"the Parties."
`,
	replacements: {
		AGREEMENT_DATE: "23 July 2026",
		SELLER_NAME: "John Doe",
		SELLER_ADDRESS: "123 Main St,\nTownville.",
		BUYER_NAME: "Jane Dumpling",
		BUYER_ADDRESS: "456 Elm St,\nViltownne.",
	},
});

Options

Token substitution syntax: $$TOKEN_NAME::<options>$$

The options are space-separated:

| Option | Example | Description | |--------|---------|-------------| | l<n> | l2 | Minimum number of lines to output (padded with blank lines or filler). Defaults to 1. | | L<n> | L4 | Maximum number of lines allowed. Overflows throw an error. Defaults to l value when no wrapping, or unlimited when r is set. | | r<n> | r60 | Wrap the value so no output line exceeds n characters in total width (including any leading text before the token). | | w<n> | w60 | Width used for filler padding. Defaults to the r value if set, otherwise 40. Note that filler will break limits set by r. | | i<n> | i3 | Indent override for continuation lines (in spaces). Defaults to the column position of the token in the template. | | f<c> | f_ | Filler character to pad each line out to w characters. If omitted, lines are not padded. | | F<flags> | Fw | One or more single-character flags (see below). Multiple flags may be combined in any order (e.g. Fwh). |

Flags (used with F<flags>):

| Flag | Description | |------|-------------| | h | Hyphenated wrapping. Each wrapped line is shortened by one character and a - is appended. If the last character of the line is already -, the line is wrapped at the normal width without adding an extra hyphen. | | w | Todo: Word-aware wrapping (not yet implemented). |

Inline tokens ($$TOKEN_NAME$$, no options) substitute the value directly in-place with no wrapping or padding.

Escape sequences ($$\uXXXX$$ or $$\UXXXXXXXX$$) insert a Unicode character by code point.

Future plans

• Currently you must prevalidate lengths for user input and make sure the template is conservative. In future I would like to have a way to generate individual validation functions from a template, depending on how tokens are used.
• Currently only character-wrapping is supported. I would like to add a word-wrapping option that can be enabled via Fw flag.

Contributing

See CONTRIBUTING.md.