Merge pull request #32 from heydenberk/0.6

Version 0.6

README.md

@@ -1,6 +1,6 @@
-Download the latest compiled version of stochator.js (0.5):
-- [development](https://github.com/heydenberk/stochator/releases/download/0.5/stochator.js) (unminified, 60Kb).
-- [production](https://github.com/heydenberk/stochator/releases/download/0.5/stochator.min.js) (minified, 24Kb).
+Download the latest compiled version of stochator.js (0.6):
+- [development](https://github.com/heydenberk/stochator/releases/download/0.6/stochator.js) (unminified, 60Kb).
+- [production](https://github.com/heydenberk/stochator/releases/download/0.6/stochator.min.js) (minified, 24Kb).
 
 # Stochator
 
@@ -10,11 +10,13 @@ Download the latest compiled version of stochator.js (0.5):
 - [Floats from an interval](#floats-from-an-interval)
 - [Floats from a normal distribution](#floats-from-a-normal-distribution)
 - [Integers](#integers)
+- [Booleans](#booleans)
 - [Multiple results](#multiple-results)
 - [From sets](#from-sets)
 - [From sets with weights](#from-sets-with-weights)
 - [From sets without replacement](#from-sets-without-replacement)
 - [From predefined sets](#from-predefined-sets)
+- [Strings](#strings)
 - [Mutators](#mutators)
 - [Multiple generators](#multiple-generators)
 - [Changelog](#changelog)
@@ -86,6 +88,28 @@ die.roll(); // 1
 die.roll(); // 2
 ````
 
+*New in 0.6*
+*Available as `Stochator.randomByte(prng=Math.random)`*
+
+The special case of generating byte integers has its own shorthand.
+
+```js
+Stochator.randomByte() // 186;
+```
+
+## Booleans
+*New in 0.6*
+*Available as `Stochator.randomBoolean(prng=Math.random)`*
+
+Although trivally composable from other generators, randomBoolean is provided for convenience.
+
+````js
+var bools = new Stochator({kind: "boolean"});
+bools.next(); // false
+bools.next(); // true
+bools.next(); // true
+````
+
 ## Multiple results
 
 If the `next` method (or a method aliased to it) is passed an integer `n`, it will return an n-length array of results. Using the die instance from the previous example:
@@ -172,6 +196,81 @@ characterGenerator.next(25).join(""); // "wdhygotehcfmrkjyuuovztxla"
 characterGenerator.next(25).join(""); // "mbjxkhflycpxgdrtyyyevasga"
 ````
 
+## Strings
+*New in 0.6*
+*Also available as:
+`Stochator.randomCharacterFromRange(range, prng=Math.random)`
+`Stochator.randomAsciiString(expression, ignoreCase, prng=Math.random)`
+`Stochator.randomUnicodeString(expression, ignoreCase, prng=Math.random)`
+`Stochator.randomAsciiCharacter(prng=Math.random)`
+`Stochator.randomLowercaseCharacter(prng=Math.random)`
+`Stochator.randomUnicodeCharacter(prng=Math.random)`
+`Stochator.randomUppercaseCharacter(prng=Math.random)`*
+
+For more flexibility than the pre-defined sets allow, we can use pass a regular expression.
+
+```js
+var hexGenerator = new Stochator({
+    kind: "string",
+    expression: "#[A-F0-9]{6}"
+});
+hexGenerator.next(); // "#57A7BB"
+```
+
+Passing the `ignoreCase` argument with a value of `true` will cause characters in the a-z and A-Z ranges to be randomized in case.
+
+```js
+var coolGreetingGenerator = new Stochator({
+    kind: "string",
+    expression: "Hello, world",
+    ignoreCase: true
+});
+coolGreetingGenerator.next(); // "hELLo, WorlD"
+```
+
+`expression` can also be a true regular expression, in which case the trailing `i` flag will be honored.
+
+```js
+var coolGreetingGenerator = new Stochator({
+    kind: "string",
+    expression: /Hello, world/i,
+    ignoreCase: true
+});
+coolGreetingGenerator.next(); // "HELlO, WorLD"
+```
+
+All features supported by JavaScript regular expressions should work.
+
+```js
+var fruitGenerator = new Stochator({
+    kind: "string",
+    expression: "((Apples|Oranges|Pears)! ?){1,5}"
+});
+fruitGenerator.next(); // "Oranges!Pears! Apples! "
+```
+
+By default, the resulting characters are limited to ASCII. If you want unicode, pass the property `unicode` with a value of `true`.
+
+```js
+var unicodeGenerator = new Stochator({
+    kind: "string",
+    expression: ".{10}",
+    unicode: true
+});
+unicodeGenerator.next(); // "貧㒐⮧Ꮜ�惜攤鎃๵켕"
+```
+
+To override the maximum length of an unbounded match (`*` or `{n,}`), provide `maxWildcard` as `true`.
+
+```js
+var binaryGenerator = new Stochator({
+    kind: "string",
+    expression: "Look at all this binary: ((0|1){256})",
+    maxWildcard: 256
+});
+binaryGenerator.next(); // "Look at all this binary: 1001011001010011100010101000011100010110010100100100000000110011010000000100000111111010110010100000010101001001100110011001111001111000111101000111010101011100010101101100001011110011110001101100001000001100101111110100001110100100000010111101111011111101"
+```
+
 ## Mutators
 The constructor accepts an optional final argument which is passed the output
 of the random value generator. Its return value becomes the return value of
@@ -287,6 +386,9 @@ new Stochator({ seed: 'STOCHATOR' }).next(); // Still always 0.4045178783365678
 ````
 
 ## Changelog
+### 0.6
+[Stochator now supports a `kind` of `string`](#strings), which supports generation of pseudo-random strings that satisfy
+provided regular expressions.
 ### 0.5
 The entire project has been rewritten to use ES6 features, with translation handled by babel and browserify.
 In addition, `Stochator` has been supplemented with static methods to facilitate single-use value generators.

package.json

@@ -21,10 +21,13 @@
     "uglifyify": "^3.0.1"
   },
   "dependencies": {
-    "lodash.identity": ">=3.0",
-    "lodash.isfunction": ">=3.0",
-    "lodash.isstring": ">=3.0",
-    "lodash.range": ">=3.0",
+    "discontinuous-range": "1.0.0",
+    "lodash.identity": "^3.0",
+    "lodash.isfunction": "^3.0",
+    "lodash.isregexp": "^3.0",
+    "lodash.isstring": "^3.0",
+    "lodash.range": "^3.0",
+    "ret": "0.1.10",
     "seedrandom": "^2.4.2"
   },
   "homepage": "https://github.com/heydenberk/stochator",
@@ -60,5 +63,5 @@
     "prepublish": "npm run build",
     "test": "mocha"
   },
-  "version": "0.5.0"
+  "version": "0.6.0"
 }

src/boolean.js

@@ -0,0 +1,6 @@
+import integer from "./integer";
+
+const random = (prng=Math.random) =>
+    Boolean(integer.boundedRandom(0, 1, prng));
+
+export default {random};

src/index.js

@@ -1,7 +1,9 @@
 import identity from "lodash.identity";
 import isFunction from "lodash.isFunction";
+import isRegExp from "lodash.isregexp";
 import isString from "lodash.isString";
 import range from "lodash.range";
+import boolean from "./boolean";
 import color from "./color";
 import distribution from "./distribution";
 import float from "./float";
@@ -10,6 +12,8 @@ import seedrandom from "seedrandom";
 import set from "./set";
 import string from "./string";
 
+const booleanGenerator = ({prng}) => () => boolean.random(prng);
+
 const colorGenerator = ({prng}) => () => color.randomRgb(prng);
 
 const floatGenerator = ({min, max, mean, prng, stdev}) => {
@@ -42,18 +46,25 @@ const setGenerator = ({values, prng, replacement=true, shuffle=false, weights=nu
     }
 };
 
-const stringGenerator = ({kind, prng}) => {
-    return kind === "a-z" ?
-        () => string.randomLowercaseCharacter(prng)
-        : () => string.randomUppercaseCharacter(prng);
+const stringGenerator = ({kind, expression=`[${kind}]`, ignoreCase=false, maxWildcard=100, prng, unicode=false}) => {
+    const isRe = isRegExp(expression);
+    const exprSource = isRe ? expression.source : expression;
+    const options = {
+        ignoreCase: ignoreCase || (isRe && expression.ignoreCase),
+        maxWildcard,
+        prng
+    };
+    return string.generateString(unicode, exprSource, options);
 };
 
 const KIND_GENERATORS = {
+    "boolean": booleanGenerator,
     "float": floatGenerator,
     "integer": integerGenerator,
     "set": setGenerator,
     "color": colorGenerator,
     "rgb": colorGenerator,
+    "string": stringGenerator,
     "a-z": stringGenerator,
     "A-Z": stringGenerator
 };
@@ -111,12 +122,22 @@ const parseArgs = (args) => {
 
 export default class Stochator {
 
-    VERSION = "0.5"
+    VERSION = "0.6"
 
     static fromDistribution = {
         normal: distribution.randomNormallyDistributedFloat
     };
 
+    static randomAsciiCharacter = string.randomAsciiCharacter;
+
+    static randomAsciiString = string.randomAsciiString;
+
+    static randomBoolean = boolean.random;
+
+    static randomByte = integer.randomByte;
+
+    static randomCharacterFromRange = string.randomCharacterFromRange;
+
     static randomColor = color.randomRgb;
 
     static randomFloat = float.boundedRandom;
@@ -125,16 +146,20 @@ export default class Stochator {
 
     static randomLowercaseCharacter = string.randomLowercaseCharacter;
 
-    static randomUppercaseCharacter = string.randomUppercaseCharacter;
-
     static randomSetMember = set.randomMember;
 
     static randomSetMemberWithoutReplacement = set.randomMemberWithoutReplacement;
 
-    static weightedRandomSetMember = set.weightedRandomMember;
+    static randomUnicodeCharacter = string.randomUnicodeCharacter;
+
+    static randomUnicodeString = string.randomUnicodeString;
+
+    static randomUppercaseCharacter = string.randomUppercaseCharacter;
 
     static shuffleSet = set.shuffleSet;
 
+    static weightedRandomSetMember = set.weightedRandomMember;
+
 
     constructor(...args) {
         const {configs, mutator, name} = parseArgs(args);