Merge pull request #19 from jhorneman/tracery2

Added support for setting random number generator, to make Tracery deterministic

js/test.js

@@ -32,7 +32,10 @@ function runTests() {
 
 	grammar.addModifiers(baseEngModifiers);
 
-	Math.seedrandom(Math.random());
+	// Use fixed number instead of random.
+	// Math.seedrandom(Math.random());
+	tracery.setRng(function() { return 0; });
+
 	// Create all the test cases
 	var tests = {
 

js/tracery/tracery.js

@@ -3,6 +3,11 @@
  */
 
 var tracery = function() {
+	var rng = Math.random;
+
+	var setRng = function setRng(newRng) {
+		rng = newRng;
+	};
 
 	var TraceryNode = function(parent, childIndex, settings) {
 		this.errors = [];
@@ -363,7 +368,7 @@ var tracery = function() {
 				break;
 			default:
 
-				index = Math.floor(Math.pow(Math.random(), this.falloff) * this.defaultRules.length);
+				index = Math.floor(Math.pow(rng(), this.falloff) * this.defaultRules.length);
 				break;
 			}
 
@@ -394,7 +399,7 @@ var tracery = function() {
 		while (0 !== currentIndex) {
 
 			// Pick a remaining element...
-			randomIndex = Math.floor(Math.random() * currentIndex);
+			randomIndex = Math.floor(rng() * currentIndex);
 			currentIndex -= 1;
 
 			// And swap it with the current element.
@@ -737,6 +742,9 @@ var tracery = function() {
 	tracery.Grammar = Grammar;
 	tracery.Symbol = Symbol;
 	tracery.RuleSet = RuleSet;
+
+	tracery.setRng = setRng;
+
 	return tracery;
 }();
 

readme.md

@@ -15,7 +15,7 @@ Create an empty grammar:
     grammar = tracery.createGrammar();
 
 Create a grammar from a Tracery-formatted object:
-
+
     grammar = tracery.createGrammar({origin:"foo"});
 
 Add modifiers to the grammar (import "mods-eng-basic.js" for basic English modifiers, or write your own)
@@ -45,6 +45,19 @@ Get the root node from a rule *not* fully expanded (this allows for animating th
                    refreshGrammarOutput();
                 }, 40);
 
+
+### Making Tracery deterministic
+
+By default, Tracery uses Math.random() to generate random numbers. If you need Tracery to be deterministic, you can make it use your own random number generator using:
+
+    tracery.setRng(myRng);
+
+where myRng is a function that, [like Math.random()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random), returns a floating-point, pseudo-random number in the range [0, 1).
+
+By using a local random number generator that takes a seed and controlling this seed, you can make Tracery's behavior completely deterministic.
+
+(Alternatively, you could use something like [seedrandom](https://github.com/davidbau/seedrandom) to make Math.random() seedable, but then you need to be very careful about who uses Math.random() - it effectively becomes a global variable that anyone can modify. Using a local random number generator - perhaps from seedrandom - instead of replacing Math.random() avoids this problem.)
+
 ## Library Concepts
 ### Grammar
 
@@ -113,4 +126,7 @@ Some attributes of this object can be:
 * distribution: a new distribution to override the default)
 * conditionRule: a rule to expand
 * conditionValue: a value to match the expansion against
-* conditionSuccess: a ruleset to use if expanding *conditionRule* returns *conditionValue*, otherwise use *baseRules*  These can be nested, so it is possible to make a ruleset 
+* conditionSuccess: a ruleset to use if expanding *conditionRule* returns *conditionValue*, otherwise use *baseRules*  
+
+
+These can be nested, so it is possible to make a ruleset