Progress on set fork rendering

Author: ajyoon

src/choiceFork.ts

@@ -1,8 +1,9 @@
-import { WeightedChoice, Choice } from './weightedChoice'
+import { WeightedChoice, Choice, sumWeights } from './weightedChoice'
 import {
   normalizeWeights,
   weightedChoose
 } from './rand';
+import { NoPossibleChoiceError, InvalidForkWeightsError } from './errors';
 
 export type ChoiceForkCallResult = {
   replacement: Choice,
@@ -11,12 +12,15 @@ export type ChoiceForkCallResult = {
 
 export class ChoiceFork {
   weights: WeightedChoice[];
+  initWeights: number[];
   identifier: string | null;
   isSilent: boolean;
   isSet: boolean;
 
   constructor(weights: WeightedChoice[], identifier: string | null, isSilent: boolean, isSet: boolean) {
     this.weights = normalizeWeights(weights);
+    this.validateWeights();
+    this.initWeights = this.weights.map((w) => (w.weight!));
     this.identifier = identifier;
     this.isSilent = isSilent;
     this.isSet = isSet;
@@ -26,12 +30,38 @@ export class ChoiceFork {
    * returns an object of the form {replacement: String, choiceIndex: Int}
    */
   call(): ChoiceForkCallResult {
-    let result = weightedChoose(this.weights);
+    let result;
+    try {
+      result = weightedChoose(this.weights);
+    } catch (error) {
+      if (error instanceof NoPossibleChoiceError && this.isSet) {
+        console.warn(`Set '${this.identifier}' is exhausted; resetting weights.`)
+        this.resetWeights();
+        return this.call();
+      } else {
+        throw error;
+      }
+    }
+    if (this.isSet) {
+      this.weights[result.choiceIndex].weight = 0;
+    }
     return { replacement: result.choice, choiceIndex: result.choiceIndex };
   }
 
+  private resetWeights() {
+    for (let [idx, val] of this.weights.entries()) {
+      val.weight = this.initWeights[idx];
+    }
+  }
+
+  private validateWeights() {
+    if (sumWeights(this.weights) === 0) {
+      throw new InvalidForkWeightsError();
+    }
+  }
+
   toString(): string {
     return `ChoiceFork{weights: ${this.weights}, `
-      + `identifier: ${this.identifier}, isSilent: ${this.isSilent}}`;
+      + `identifier: ${this.identifier}, isSilent: ${this.isSilent}, isSet: ${this.isSet}}`;
   }
 }

src/errors.ts

@@ -53,23 +53,23 @@ export class BMLDuplicatedRefError extends Error {
 
 export class EvalBoundSettingsError extends Error {
   constructor(field: string, value: any) {
-    super(`Eval binding of settings field '${field}' of '${value}' is invalid`)
+    super(`Eval binding of settings field '${field}' of '${value}' is invalid`);
     this.name = 'EvalBoundSettingsError';
     Object.setPrototypeOf(this, EvalBoundSettingsError.prototype);
   }
 }
 
 export class EvalBindingError extends Error {
   constructor(key: string) {
-    super(`Eval binding ${key} was bound multiple times.`)
+    super(`Eval binding ${key} was bound multiple times.`);
     this.name = 'EvalBindingError';
     Object.setPrototypeOf(this, EvalBindingError.prototype);
   }
 }
 
 export class EvalDisabledError extends Error {
   constructor() {
-    super(`This document includes eval blocks and cannot be rendered with allowEval=false.`)
+    super(`This document includes eval blocks and cannot be rendered with allowEval=false.`);
     this.name = 'EvalDisabledError';
     Object.setPrototypeOf(this, EvalDisabledError.prototype);
   }
@@ -82,3 +82,21 @@ export class IncludeError extends Error {
     Object.setPrototypeOf(this, IncludeError.prototype);
   }
 }
+
+export class InvalidForkWeightsError extends Error {
+  constructor() {
+    super('Fork has invalid weights');
+    this.name = 'InvalidForkWeightsError';
+    Object.setPrototypeOf(this, InvalidForkWeightsError.prototype);
+  }
+}
+
+export class NoPossibleChoiceError extends Error {
+  constructor() {
+    super('Cannot perform weighted choice where the given weights have a sum of zero');
+    this.name = 'NoPossibleWeightsError';
+    Object.setPrototypeOf(this, NoPossibleChoiceError.prototype);
+  }
+}
+
+

src/rand.ts

@@ -1,6 +1,8 @@
-import { WeightedChoice, Choice } from './weightedChoice';
+import { WeightedChoice, Choice, sumWeights } from './weightedChoice';
+import { NoPossibleChoiceError } from './errors';
 import seedrandom from 'seedrandom';
 
+
 // A module-local seedable random number generator
 // The selected seed will be random unless `setRandomSeed()` is called.
 // @ts-ignore
@@ -63,9 +65,9 @@ export function randomInt(min: number, max: number): number {
  * Returns an object of the form {choice, choiceIndex}
  */
 export function weightedChoose(weights: WeightedChoice[]): { choice: Choice, choiceIndex: number } {
-  let sum = 0;
-  for (let wc of weights) {
-    sum += wc.weight ?? 0;
+  let sum = sumWeights(weights);
+  if (sum === 0) {
+    throw new NoPossibleChoiceError();
   }
   let progress = 0;
   let pickedValue = randomFloat(0, sum);

src/renderer.ts

@@ -86,6 +86,12 @@ export class Renderer {
       if (isStr(node)) {
         output += node;
       } else if (node instanceof ChoiceFork) {
+        if (node.isSet && node.isSilent) {
+          // Silent set declarations are *not* immediately executed.
+          this.executedForkMap.set(node.identifier!,
+            { choiceFork: node, choiceIndex: -1, renderedOutput: '' });
+          continue;
+        }
         let { replacement, choiceIndex } = node.call();
         let renderedOutput = this.renderChoice(replacement);
         if (node.isSilent) {

src/weightedChoice.ts

@@ -25,3 +25,9 @@ export class WeightedChoice {
     return new WeightedChoice(this.choice, this.weight);
   }
 }
+
+export function sumWeights(weights: WeightedChoice[]) {
+  // Note that if weights have been normalized, as they are in `ChoiceFork`s,
+  // `wc.weight` will always be non-null here so the default should never occur.
+  return weights.reduce((acc, val) => acc + (val.weight ?? 0), 0);
+}

test/testReplacer.ts renamed to test/testChoiceFork.ts

@@ -28,6 +28,7 @@ describe('ChoiceFork', function() {
     let choiceFork = new ChoiceFork(weights, 'identifier', true, false);
     expect(choiceFork.toString()).toBe(
       'ChoiceFork{weights: WeightedChoice{choice: foo, weight: 40},'
-      + 'WeightedChoice{choice: bar, weight: 60}, identifier: identifier, isSilent: true}');
+      + 'WeightedChoice{choice: bar, weight: 60}, identifier: identifier, '
+      + 'isSilent: true, isSet: false}');
   });
 });

test/testRand.ts

@@ -3,6 +3,7 @@ import sha from 'sha.js';
 import { Buffer } from 'buffer';
 
 import { WeightedChoice } from '../src/weightedChoice';
+import { NoPossibleChoiceError } from '../src/errors';
 let rand = require('../src/rand.ts');
 
 type RandomFunction = (a: number, b: number) => number;
@@ -108,6 +109,7 @@ describe('weightedChoose', function() {
   beforeEach(function() {
     rand.setRandomSeed(0); // pin seed for reproducibility
   });
+
   it('behaves on well-formed weights', function() {
     let weights = [
       new WeightedChoice(['foo'], 40),
@@ -125,4 +127,23 @@ describe('weightedChoose', function() {
     expect(result.choice).toStrictEqual(['bar']);
     expect(result.choiceIndex).toBe(1);
   });
+
+  it('errors when given no weights', function() {
+    expect(() =>
+      rand.weightedChoose([])
+    ).toThrow('Cannot perform weighted choice where the given weights have a sum of zero');
+    // For reasons beyond me, toThrow here fails when I reference the actual error type
+  });
+
+  it('errors when given all-zero weights', function() {
+    expect(() => {
+      let weights = [
+        new WeightedChoice(['foo'], 0),
+        new WeightedChoice(['bar'], 0),
+      ];
+      rand.weightedChoose(weights);
+    }).toThrow('Cannot perform weighted choice where the given weights have a sum of zero');
+    // For reasons beyond me, toThrow here fails when I reference the actual error type
+  });
+
 });

test/testRenderer.ts

@@ -67,6 +67,43 @@ describe('render', function() {
     expect(render(testString, null, null)).toEqual('Foo fff\nfoo fff\nbar bbb\nbar bbb\n');
   });
 
+  it('supports initial set fork declarations', function() {
+    let testString = 'foo {$id: (bar), (biz)}';
+    expect(render(testString, null, null)).toEqual('Foo bar\n');
+  });
+
+  it('supports initial silent set fork declarations', function() {
+    let testString = 'foo {#$id: (bar), (biz)}';
+    expect(render(testString, null, null)).toEqual('Foo\n');
+  });
+
+  it('supports re-executing set forks', function() {
+    let testString = '{$id: (A), (B), (C), (D)} {@!id} {@!id} {@!id}';
+    expect(render(testString, null, null)).toEqual('A B D C\n');
+  });
+
+  it('supports re-executing silent set forks', function() {
+    // Note that silent set forks are *not* immediately executed,
+    // so the initial declaration does not cause a set member to be exhausted
+    let testString = '{#$id: (A), (B), (C), (D)} {@!id} {@!id} {@!id} {@!id}';
+    expect(render(testString, null, null)).toEqual(' A B D C\n');
+  });
+
+  it('gracefully errors trying to map unexecuted silent set forks', function() {
+    // TODO
+  });
+
+  it('resets weights on exhausted sets', function() {
+    let originalConsoleWarn = console.warn;
+    console.warn = jest.fn(); // Mock console.warn with a Jest mock function
+    try {
+      let testString = '{#$id: (A), (B), (C), (D)} {@!id} {@!id} {@!id} {@!id} {@!id}';
+      expect(render(testString, null, null)).toEqual(' A B D C D\n');
+    } finally {
+      console.warn = originalConsoleWarn;
+    }
+  });
+
   it('preserves plaintext parentheses', function() {
     let testString = 'foo (bar)';
     expect(render(testString, null, null)).toEqual('Foo (bar)\n');

test/testWeightedChoice.ts

@@ -1,13 +1,37 @@
 import expect from 'expect';
 
-import { WeightedChoice } from '../src/weightedChoice';
+import { WeightedChoice, sumWeights } from '../src/weightedChoice';
 import { EvalBlock } from '../src/evalBlock';
 
-describe('ChoiceFork', function() {
+describe('WeightedChoice', function() {
   it('has a useful toString for all choice types', function() {
     expect(new WeightedChoice(['foo'], 1).toString())
       .toBe('WeightedChoice{choice: foo, weight: 1}');
     expect(new WeightedChoice(new EvalBlock('foo'), 1).toString())
       .toBe('WeightedChoice{choice: EvalBlock(\'foo\'), weight: 1}');
   });
 });
+
+describe('sumWeights', function() {
+  it('Converts null weights to 0', function() {
+    let weights = [
+      new WeightedChoice(['foo'], null),
+      new WeightedChoice(['bar'], 5),
+    ];
+    expect(sumWeights(weights)).toEqual(5);
+  });
+
+  it('Accepts empty arrays', function() {
+    expect(sumWeights([])).toEqual(0);
+  });
+
+  it('Works on simple cases', function() {
+    let weights = [
+      new WeightedChoice(['foo'], 2),
+      new WeightedChoice(['bar'], 5),
+      new WeightedChoice(['biz'], 6),
+    ];
+    expect(sumWeights(weights)).toEqual(13);
+  });
+
+});