!@thi.ng/proctext

![npm version](https://www.npmjs.com/package/@thi.ng/proctext)
!npm downloads
![Mastodon Follow](https://mastodon.thi.ng/@toxi)

> [!NOTE]
> This is one of 214 standalone projects, maintained as part
> of the @thi.ng/umbrella monorepo
> and anti-framework.
>
> 🚀 Please help me to work full-time on these projects by sponsoring me on
> GitHub. Thank you! ❤️

- About
- Features
- Line comments
- Multi-value variables
- Recursive variable expansion
- Variable assignments
- Hidden assignments
- Dynamic, indirect variable references
- Modifiers
- Controlled randomness
- Status
- Installation
- Dependencies
- Usage examples
- API
- Authors
- License

About

Extensible procedural text generation engine with dynamic, mutable state, indirection, randomizable & recursive variable expansions.

> [!NOTE]
> The generated output of the code examples in this readme might vary due to the
> inherent randomness in the system. Please consult the controlled
> randomness section for further information about
> deterministic outputs.

Features

The generator works with a simple plain text format, supporting the following
features:

$3

Lines starting with # are comments and completely ignored, and invisible in
the output. No block comments are available.

$3

Text generation and expansion relies on variables, which are defined inline
(inside the text given to the generator). New variables can be defined as
follows and each variable can define one or more possible values (one value per
line!):

``text [name] alice bob ciara`

If more than a single value is given, a semi-random choice will be made for each instance/occurrence of the var...

Variables are case-sensitive (i.e. NAME is a different var than name) and can also be re-defined overridden in different parts of the document.

Variables are referenced via: . By default, an error will be thrown if a variable cannot be resolved. Via themissing option given to generate()a default fallback value can be defined, which when given will not trigger an error in these cases.

> [!NOTE] > The special variable referencecan be used to produce an empty > string (or used as single value placeholder option inside another variable > definition). This variable can not be redefined.

`ts tangle:export/readme-intro.ts import { generate } from "@thi.ng/proctext";

const { result } = await generate(
[name]
alice
bob

[action]
walked
cycled
ran
swam

[place]
office
shop
cafe
lake

[time]
this morning
last night
a week ago

The actual generated text...

to the .

);
console.log(result);

// last night alice cycled to the cafe.`

`$3`

Variable values can contain cyclic references and/or references to other variables.

> [!IMPORTANT] > In the case of cyclic refs, you MUST provide at least one non-cyclic option > to avoid infinite recursion!

`ts tangle:export/readme-var-recursion.ts import { generate } from "@thi.ng/proctext";

const { result } = await generate(
[activity]
walking and
hiking and

the next option is cyclic...

cycling,

[activity_alt]
sleeping
coding

I enjoy .
);

console.log(result);

// I enjoy cycling, walking and coding.`

`$3`

New variables can be declared & initialized via . This will create a new variablevarname with a choice value of variable existing(which must already be defined).

`ts tangle:export/readme-var-assign.ts import { generate } from "@thi.ng/proctext";

const { result } = await generate(
[name]
Alice
Bob
Charlie
Dora

Let's pick some random names: and .

But now we can use them as constants:
, , & , ,
);

console.log(result);

// Let's pick some random names: Dora and Bob. // // But now we can use them as constants: // Dora, Dora, Dora & Bob, Bob, Bob`

`$3`

Normally, variable assignments are also causing the chosen value to be emitted as part of the generated text. Sometimes it's useful to _not_ do so and suppress/hide output by using the prefix! as part of the assignment, like so:

`ts tangle:export/readme-hidden-var.ts import { generate } from "@thi.ng/proctext";

const { result } = await generate(
[name]
Asterix
Obelix

hidden assignment

My name is .

);
console.log(result);

// My name is Asterix.`

`$3`

Given a variable assignment like , we can use dots in the name to lookup derived variables with their name based on current value(s).

For the following example:

- assume the assignment of picked value a- now the var lookup will look for a var called a.job- there's only one option fora.job, i.e. astronaut- the lookuphero.job.desc will then look for astronaut.desc

`ts tangle:export/readme-indirect.ts import { generate } from "@thi.ng/proctext";

const { result } = await generate(
[name]
A
B

[A.job]
astronaut

[B.job]
baker

[astronaut.desc]
shooting for the stars
flying to the moon

[baker.desc]
baking bread

is a , .);

console.log(result);

// B is a baker, baking bread.`

`$3`

Variable references can be optionally processed via one or more modifiers via or . Each modifier is a simple async function receiving a string and transforming it into another string. These functions are async to allow modifiers consulting external data sources/processes...

The following modifiers are provided by default:

- uc: uppercase -lc: lowercase -cap: capitalize

Custom modifiers can be provided via options given to generate():

`ts tangle:export/readme-modifiers.ts import { generate } from "@thi.ng/proctext";

const DIRECTIONS = { e: "east", w: "west", n: "north", s: "south", d: "down", u: "up", };

const ROOMS = { house: { desc: "very homely", exits: { e: "garden", u: "rafters" }, }, rafters: { desc: "pretty dark", exits: { d: "house" }, }, garden: { desc: "super lush", exits: { w: "house" }, }, };

// partially data-driven template const { result } = await generate(
[room]
${Object.keys(ROOMS).join("\n")}

You're in the (exits: )...
It feels here.
, { // custom modifiers (will be added to existing defaults) mods: { // produce a list of exits for given room ID exits: async (id) => Object.keys(ROOMS[id].exits).map((dir) => DIRECTIONS[dir]).join(", "), // return a room's description desc: async (id) => ROOMS[id].desc } });

console.log(result);

// You're in the house (exits: EAST, UP)... // It feels very homely here.`

`$3`

The selection of variable choices is determined by the configured PRNG instance, the number of recent values selected/memorized and the number of attempts made to pick a new unique choice. All of these can be configured via options given togenerate():

`ts import { generate } from "@thi.ng/proctext"; import { SYSTEM, XsAdd } from "@thi.ng/random";

// here we show default options used generate(..., { rnd: SYSTEM, maxHist: 1, maxTrials: 10 });

// using a seeded PRNG for deterministic behavior/output generate(..., { rnd: new XsAdd(0xdecafbad) });`

The maxHist = 1means that for each variable only the last value picked will be memorized. If more than 1 value options exists for a variable, successive var expansions will not result in duplicates, e.g.

`text [name] a b

...will only ever result in one of these two sequences: a b a or b a b.

`Status`

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

`Installation`

`bash yarn add @thi.ng/proctext`

ESM import:

`ts import * as pro from "@thi.ng/proctext";`

Browser ESM import:

`html`

JSDelivr documentation

For Node.js REPL:

`js const pro = await import("@thi.ng/proctext");`

Package sizes (brotli'd, pre-treeshake): ESM: 1.34 KB

`Dependencies`

- @thi.ng/api - @thi.ng/arrays - @thi.ng/checks - @thi.ng/defmulti - @thi.ng/errors - @thi.ng/object-utils - @thi.ng/parse - @thi.ng/random - @thi.ng/strings

Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)

`Usage examples`

One project in this repo's /examples directory is using this package:

| Screenshot | Description | Live demo | Source | |:-----------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------|:------------------------------------------------------|:-----------------------------------------------------------------------------------| | | Procedural stochastic text generation via custom DSL, parse grammar & AST transformation | Demo | Source |

`API`

Generated API docs

`Authors`

- Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

`bibtex @misc{thing-proctext, title = "@thi.ng/proctext", author = "Karsten Schmidt", note = "https://thi.ng/proctext", year = 2023 }``

License

!@thi.ng/proctext

![npm version](https://www.npmjs.com/package/@thi.ng/proctext)
!npm downloads
![Mastodon Follow](https://mastodon.thi.ng/@toxi)

About

Extensible procedural text generation engine with dynamic, mutable state, indirection, randomizable & recursive variable expansions.

Features

The generator works with a simple plain text format, supporting the following
features:

$3

Lines starting with # are comments and completely ignored, and invisible in
the output. No block comments are available.

$3

``text [name] alice bob ciara`

If more than a single value is given, a semi-random choice will be made for each instance/occurrence of the var...

Variables are case-sensitive (i.e. NAME is a different var than name) and can also be re-defined overridden in different parts of the document.

`ts tangle:export/readme-intro.ts import { generate } from "@thi.ng/proctext";

const { result } = await generate(
[name]
alice
bob

[action]
walked
cycled
ran
swam

[place]
office
shop
cafe
lake

[time]
this morning
last night
a week ago

The actual generated text...

to the .

);
console.log(result);

// last night alice cycled to the cafe.`

`$3`

Variable values can contain cyclic references and/or references to other variables.

> [!IMPORTANT] > In the case of cyclic refs, you MUST provide at least one non-cyclic option > to avoid infinite recursion!

`ts tangle:export/readme-var-recursion.ts import { generate } from "@thi.ng/proctext";

const { result } = await generate(
[activity]
walking and
hiking and

the next option is cyclic...

cycling,

[activity_alt]
sleeping
coding

I enjoy .
);

console.log(result);

// I enjoy cycling, walking and coding.`

`$3`

New variables can be declared & initialized via . This will create a new variablevarname with a choice value of variable existing(which must already be defined).

`ts tangle:export/readme-var-assign.ts import { generate } from "@thi.ng/proctext";

const { result } = await generate(
[name]
Alice
Bob
Charlie
Dora

Let's pick some random names: and .

But now we can use them as constants:
, , & , ,
);

console.log(result);

// Let's pick some random names: Dora and Bob. // // But now we can use them as constants: // Dora, Dora, Dora & Bob, Bob, Bob`

`$3`

`ts tangle:export/readme-hidden-var.ts import { generate } from "@thi.ng/proctext";

const { result } = await generate(
[name]
Asterix
Obelix

hidden assignment

My name is .

);
console.log(result);

// My name is Asterix.`

`$3`

Given a variable assignment like , we can use dots in the name to lookup derived variables with their name based on current value(s).

For the following example:

`ts tangle:export/readme-indirect.ts import { generate } from "@thi.ng/proctext";

const { result } = await generate(
[name]
A
B

[A.job]
astronaut

[B.job]
baker

[astronaut.desc]
shooting for the stars
flying to the moon

[baker.desc]
baking bread

is a , .);

console.log(result);

// B is a baker, baking bread.`

`$3`

The following modifiers are provided by default:

- uc: uppercase -lc: lowercase -cap: capitalize

Custom modifiers can be provided via options given to generate():

`ts tangle:export/readme-modifiers.ts import { generate } from "@thi.ng/proctext";

const DIRECTIONS = { e: "east", w: "west", n: "north", s: "south", d: "down", u: "up", };

// partially data-driven template const { result } = await generate(
[room]
${Object.keys(ROOMS).join("\n")}

console.log(result);

// You're in the house (exits: EAST, UP)... // It feels very homely here.`

`$3`

`ts import { generate } from "@thi.ng/proctext"; import { SYSTEM, XsAdd } from "@thi.ng/random";

// here we show default options used generate(..., { rnd: SYSTEM, maxHist: 1, maxTrials: 10 });

// using a seeded PRNG for deterministic behavior/output generate(..., { rnd: new XsAdd(0xdecafbad) });`

`text [name] a b

...will only ever result in one of these two sequences: a b a or b a b.

`Status`

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

`Installation`

`bash yarn add @thi.ng/proctext`

ESM import:

`ts import * as pro from "@thi.ng/proctext";`

Browser ESM import:

`html`

JSDelivr documentation

For Node.js REPL:

`js const pro = await import("@thi.ng/proctext");`

Package sizes (brotli'd, pre-treeshake): ESM: 1.34 KB

`Dependencies`

- @thi.ng/api - @thi.ng/arrays - @thi.ng/checks - @thi.ng/defmulti - @thi.ng/errors - @thi.ng/object-utils - @thi.ng/parse - @thi.ng/random - @thi.ng/strings

Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)

`Usage examples`

One project in this repo's /examples directory is using this package:

`API`

Generated API docs

`Authors`

- Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

`bibtex @misc{thing-proctext, title = "@thi.ng/proctext", author = "Karsten Schmidt", note = "https://thi.ng/proctext", year = 2023 }``