README.md in regexp-examples-0.3.2 vs README.md in regexp-examples-0.4.0

@@ -7,10 +7,11 @@
 
 This method generates a list of (some\*) strings that will match the given regular expression
 
 \* 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
 
 ```ruby
 /a*/.examples #=> [''. 'a', 'aa']
@@ -61,18 +62,53 @@
 * [Anchors](http://ruby-doc.org/core-2.2.0/Regexp.html#class-Regexp-label-Anchors) (`\b`, `\B`, `\G`, `^`, `\A`, `$`, `\z`, `\Z`), e.g. `/\bword\b/`, `/line1\n^line2/`
   * However, a special case has been made to allow `^` and `\A` at the start of a pattern; and to allow `$`, `\z` and `\Z` at the end of pattern. In such cases, the characters are effectively just ignored.
 
 (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` is equivalent to `[01234]`
+  * `\w` is equivalent to `[abcde]`
+  * `[h-s]` is equivalent to `[hijkl]`
+  * `(1|2|3|4|5|6|7|8)` is equivalent to `[12345]`
+
+To use an alternative value, simply pass the configuration option as follows:
+
+```ruby
+/a*/.examples(max_repeater_variance: 5) #=> [''. 'a', 'aa', 'aaa', 'aaaa' 'aaaaa']
+/[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:
 
 * Various (weird!) legal patterns do not get parsed correctly, such as `/[[wtf]]/.examples` - To solve this, I'll probably have to dig deep into the Ruby source code and imitate the actual Regex parser more closely.
 
-* Not all examples are shown for repeated groups, e.g. `/[ab]{2}/.examples` does not contain `"ab"` or `"ba"`. This is due to a flaw in the current parser design, and will be fixed in the next major release.
-
-* Similarly, examples like `/(a){2} \1/.examples #=> ["aa aa"]` do not quite work properly, as the backreference is saved as `"aa"`, rather than just `"a"`. This bug is closely related to the one above.
+* Backreferences are replaced by the _first_ occurance of the group, not the _last_ (as it should be). This is quite a rare occurance, but for example: `/(a|b){2} \1/.examples` incorrectly includes: `"ba b"` rather than the correct: `"ba a"`
 
 ## Installation
 
 Add this line to your application's Gemfile: