Supported ruby versions

MRI 2.0.x

MRI 2.1.x

MRI 2.2.x

MRI 2.3.x

MRI 2.4.0-dev

MRI ≤ 1.9.3 are not supported. This is primarily because MRI 2.0.0 introduced a new
regexp engine (Oniguruma was replaced by Onigmo). Whilst most of this gem could
be made to work with MRI 1.9.x (or even 1.8.x), I feel the changes are too significant
to implement backwards compatability (especially since long-term support for MRI
1.9.3 has now ended).

For example, named properties (e.g. /\p{Alpha}/) are illegal syntax on MRI 1.9.3.

Other implementations, such as JRuby, could probably work fine -
but I haven't fully tried/tested it. Pull requests are welcome.

Installation

Add this line to your application's Gemfile:

gem'regexp-examples'

And then execute:

$ bundle

Or install it yourself as:

$ geminstallregexp-examples

Supported syntax

Short answer: Everything is supported, apart from "irregular" aspects of the regexp language -- see impossible features.

Bugs and Not-Yet-Supported syntax

There are some (rare) edge cases where backreferences do not work properly, e.g. /(a*)a* \1/.examples - which includes "aaaa aa". This is because each repeater is not context-aware, so the "greediness" logic is flawed. (E.g. in this case, the second a* should always evaluate to an empty string, because the previous a* was greedy!) However, patterns like this are highly unusual...

Since the Regexp language is so vast, it's quite likely I've missed something (please raise an issue if you find something)! The only missing feature that I'm currently aware of is:

Some of the most obscure regexp features are not even mentioned in the ruby docs! However, full documentation on all the intricate obscurities in the ruby (version 2.x) regexp parser can be found here.

Impossible features ("illegal syntax")

The following features in the regex language can never be properly implemented into this gem because, put simply, they are not technically "regular"!
If you'd like to understand this in more detail, check out what I had to say in my blog post about this gem.

Using any of the following will raise a RegexpExamples::IllegalSyntax exception:

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 billion) examples!

In other words, think twice before playing around with this config!

A more sensible use case might be, for example, to generate all 1-4 digit strings:

/\d{1,4}/.examples(max_repeater_variance: 3, max_group_results: 10)

Due to code optimisation, this is not something you need to worry about (much) for Regexp#random_example. For instance, the following takes no more than ~ 1 second on my machine:

/.*\w+\d{100}/.random_example(max_repeater_variance: 1000)

TODO

Performance improvements:

(Maybe?) add a max_examples configuration option and use lazy evaluation, to ensure the method never "freezes".