/* Mutagen: a text generator library Written by Andrew Plotkin This Javascript code is copyright 2009 by Andrew Plotkin. You may copy, distribute, and modify it freely, by any means and under any conditions. Mutagen is a simple Javascript library for generating pseudorandom strings of text, according to a grammar. By "pseudorandom", we mean that if you put in a number, you'll get out an apparently arbitrary string. If you put in a different number, you'll get out a different string. But if you put in the same number twice, you'll get the same string out both times. The generation algorithm is completely deterministic; the number acts as a seed. (The algorithm is patternless enough for ordinary use, but it's not a strong pseudorandom function. It's basically a lot of ((SEED mod P) mod C), where P is a prime near 5000, and C is the list of choices at a given point -- perhaps as few as two.) * Usage To use this library, define a node -- meaning a plain string, or one of the node types described below. This defines a "grammar", in the comp-sci sense: a structure of possible string outputs. Then do: var factory = Factory(NODE); var str = factory(seed); You can call the factory() function as often as you like, with various seeds. See the goreyfate.js source file for an example of use. * Nodes These are the various kinds of node: - "string" A plain string. It always generates itself, regardless of the seed. - null This generates nothing; it has no effect. Sometimes that's handy. The empty string "" is equivalent. - Sequence(NODE, NODE, NODE, ...) A sequence of nodes. It generates each node in turn. (Again, the seed value has no effect.) For example, the node Sequence("hello", "there", "world") would always generate the string "Hello there world." (Note that you get the initial capital letter, final period, and spaces for free.) A sequence can contain any other nodes, not just plain strings. So you could define Sequence(Sequence("hello", "there"), "world") and get the same result, "Hello there world." - Choice(NODE, NODE, NODE, ...) A random (or rather, pseudorandom) choice of nodes. This generates exactly one of the node arguments, as determined by the seed. So Choice("red", "green", "blue") would generate either "Red." or "Green." or "Blue." A Choice can contain Sequences and a Sequence can contain Choices. That gives you most of the system right there. Everything else is details. - Weighted(NUM, NODE, NUM, NODE, ...) This is like a Choice, but with unequal probabilities. If you define Weighted(2, "human", 1, "elf", 1, "dwarf") you'd get a 50% chance of "Human." and a 25% chance of each of the other two options. For tedious reasons (meaning, I was lazy) all of the numbers must be integers. Fractional values won't work right. - Fixed(LABEL, NODE) Sometimes you want random choices that line up. For example, you might define Choice("aunt", "uncle") at one point in your grammar, and Choice("Harriet", "Harold") at another point. But these are not independent choices; you don't want "Aunt Harold" or "Uncle Harriet". To solve this problem, use Fixed("gender", Choice(...)). This applies the label "gender" (for this example) to the Choice node. All Choices with the same label will wind up making the same selection, for a given seed. Either they'll all choose their first argument, or they'll all choose their second argument, or whatever. (Make sure all the Choices for a given label have the same number of options! Otherwise, all bets are off. You can wrap Weighted nodes too, but again, they have to have the same number of options, and the same weight values too.) - Comma This node generates a comma. - Period This node generates a period, and causes the next word to be capitalized. (Putting a Period at the very end of your grammar is optional.) - AAn This node generates "a" or "an", depending on whether the next word starts with a vowel. - Concat This node generates nothing, and skips the space that would normally appear before the next node. * Internals For some reason, I wrote this library in (nearly) purely functional Javascript. Go ahead, laugh. This means it's a big pile of closures, and functions that return functions that return functions. If you're a Lisp programmer, it will be obvious how it works. To everyone else, I apologize. Take it as a learning experience. * Future Directions This library is a weekend hack, and I don't expect to expand it. However, there are some obvious improvements to be made. Primarily, some kind of versioning system. These generators are fragile with respect to grammar changes. That is, if you know that factory(1000000) produces a particular string, but then you think of some extra Choices to throw in, the new factory(1000000) could be a completely different string -- even though you only added possibilities, not removed any. For some uses, of course -- like a silly button on a web page -- that doesn't matter. But if you used this in a persistent game, you might want to store a seed value and have it generate the same string forever. That would require some kind of versioning model. Another thing: this system is profligate with primes, and it has a limited stock built in. This means that, as you develop your grammar, you have to paste in more primes now and then. This is silly. Really there is a lot of opportunity for re-using primes; the various children of a Choice could all use the same cycle value, because they will never occur in the same output. (Unless the Choice is used more than once... but that way lies graph theory.) (For that matter, the system wastes primes on Sequence nodes, which don't use them. A bit of refactoring would take care of that.) */ /* A handful of special nodes which contain no code. These exist only to be compared via identity (===). */ Period = Object(); Comma = Object(); AAn = Object(); Concat = Object(); /* All the Node types -- except the special cases above -- are functions that return functions that return functions. You, the user, call the function with a set of arguments. You get back a node function. The Factory calls that to bind in the prime number (which will be used during generation); it gets back a generator function. Finally, the node's parent calls the generator, passing in the seed and a work array of strings. The generator appends its output to the work array. I know; in a real functional language, the generator should return a consed result, instead of appending to the work array. Live with it. Javascript isn't *that* functional. */ function Sequence(/*...*/) { var argcopy = Array.prototype.slice.call(arguments); return function(build, cycle) { var argls = Array(); for (var ix=0; ix