Documented configuration options

Author: Tom Lord

README.md

@@ -9,6 +9,7 @@ This method generates a list of (some\*) strings that will match the given regul
 
 \* If the regex has an infinite number of possible srings that match it, such as `/a*b+c{2,}/`,
 or a huge number of possible matches, such as `/.\w/`, then only a subset of these will be listed.
+For more detail on this, see [configuration options](#configuration_options)
 
 ## Usage
 
@@ -63,6 +64,39 @@ Using any of the following will raise a RegexpExamples::IllegalSyntax exception:
 
 (Note: Backreferences are not really "regular" either, but I got these to work with a bit of hackery!)
 
+<a name="configuration_options"/>
+##Configuration Options
+
+When generating examples, the gem uses 2 configurable values to limit how many examples are listed:
+
+* `max_repeater_variance` (default = `2`) restricts how many examples to return for each repeater. For example:
+  * .\* is equivalent to .{0,2}
+  * .+ is equivalent to .{1,3}
+  * .{2,} is equivalent to .{2,4}
+  * .{,3} is equivalent to .{0,2}
+  * .{3,8} is equivalent to .{3,5}
+
+* `max_group_results` (default = `5`) restricts how many characters to return for each "set". For example:
+  * \d = ["0", "1", "2", "3", "4"]
+  * \w = ["a", "b", "c", "d", "e"]
+  * [h-s] = ["h", "i", "j", "k", "l"]
+  * (1|2|3|4|5|6|7|8) = ["1", "2", "3", "4", "5"]
+
+To use an alternative value, simply pass the configuration option as follows:
+
+```ruby
+/a*/.examples(max_repeater_variance: 5) #=> [''. 'a', 'aa', 'aaa', 'aaaa']
+/[F-X]/.examples(max_group_results: 10) #=> ['F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O']
+```
+
+**_WARNING_**: Choosing huge numbers, along with a "complex" regex, could easily cause your system to freeze!
+
+For example, if you try to generate a list of _all_ 5-letter words: `/\w{5}/.examples(max_group_results: 999)`, then - since there are actually `63` "word" characters (upper/lower case letters, numbers and "\_"), this will try to generate `63**5 #=> 992436543` (almost 1 trillion) examples!
+
+In other words, think twice before playing around with this config!
+
+A more sensible use case might be, for example, to generate one random 1-4 digit string: `/\d{1,4}/.examples(max_repeater_variance: 3, max_group_results: 10).sample(1)`. (Note: I may develop a much more efficient way to "generate one example" in a later release of this gem.)
+
 ## Known Bugs
 
 There are a few obscure bugs that have yet to be resolved: