README.md in regexp-examples-1.0.0 vs README.md in regexp-examples-1.0.1

- old
+ new

@@ -13,19 +13,20 @@ For more detail on this, see [configuration options](#configuration-options). ## Usage ```ruby -/a*/.examples #=> [''. 'a', 'aa'] +/a*/.examples #=> ['', 'a', 'aa'] /ab+/.examples #=> ['ab', 'abb', 'abbb'] /this|is|awesome/.examples #=> ['this', 'is', 'awesome'] /https?:\/\/(www\.)?github\.com/.examples #=> ['http://github.com', # 'http://www.github.com', 'https://github.com', 'https://www.github.com'] /(I(N(C(E(P(T(I(O(N)))))))))*/.examples #=> ["", "INCEPTION", "INCEPTIONINCEPTION"] /\x74\x68\x69\x73/.examples #=> ["this"] /\u6829/.examples #=> ["цай"] -/what about (backreferences\?) \1/.examples #=> ['what about backreferences? backreferences?'] +/what about (backreferences\?) \1/.examples + #=> ['what about backreferences? backreferences?'] ``` ## Installation Add this line to your application's Gemfile: @@ -43,30 +44,31 @@ $ gem install regexp-examples ## Supported syntax * All forms of repeaters (quantifiers), e.g. `/a*/`, `/a+/`, `/a?/`, `/a{1,4}/`, `/a{3,}/`, `/a{,2}/` - * Reluctant and possissive repeaters work fine, too - e.g. `/a*?/`, `/a*+/` + * Reluctant and possissive repeaters work fine, too, e.g. `/a*?/`, `/a*+/` * Boolean "Or" groups, e.g. `/a|b|c/` -* Character sets e.g. `/[abc]/` - including: +* Character sets, e.g. `/[abc]/` - including: * Ranges, e.g.`/[A-Z0-9]/` * Negation, e.g. `/[^a-z]/` * Escaped characters, e.g. `/[\w\s\b]/` * POSIX bracket expressions, e.g. `/[[:alnum:]]/`, `/[[:^space:]]/` * Set intersection, e.g. `/[[a-h]&&[f-z]]/` * Escaped characters, e.g. `/\n/`, `/\w/`, `/\D/` (and so on...) * Capture groups, e.g. `/(group)/` * Including named groups, e.g. `/(?<name>group)/` * ...And backreferences(!!!), e.g. `/(this|that) \1/` `/(?<name>foo) \k<name>/` - * Groups work fine, even if nested or optional e.g. `/(even(this(works?))) \1 \2 \3/`, `/what about (this)? \1/` + * Groups work fine, even if nested or optional, e.g. `/(even(this(works?))) \1 \2 \3/`, `/what about (this)? \1/` * Non-capture groups, e.g. `/(?:foo)/` * Comment groups, e.g. `/foo(?#comment)bar/` * Control characters, e.g. `/\ca/`, `/\cZ/`, `/\C-9/` * Escape sequences, e.g. `/\x42/`, `/\x5word/`, `/#{"\x80".force_encoding("ASCII-8BIT")}/` * Unicode characters, e.g. `/\u0123/`, `/\uabcd/`, `/\u{789}/` * Octal characters, e.g. `/\10/`, `/\177/` -* Named properties, e.g. `/\p{L}/` ("Letter"), `/\p{Arabic}/` ("Arabic character"), `/\p{^Ll}/` ("Not a lowercase letter") +* Named properties, e.g. `/\p{L}/` ("Letter"), `/\p{Arabic}/` ("Arabic character") +, `/\p{^Ll}/` ("Not a lowercase letter"), `\P{^Canadian_Aboriginal}` ("Not not a Canadian aboriginal character") * **Arbitrarily complex combinations of all the above!** * Regexp options can also be used: * Case insensitive examples: `/cool/i.examples #=> ["cool", "cooL", "coOl", "coOL", ...]` * Multiline examples: `/./m.examples #=> ["\n", "a", "b", "c", "d"]` @@ -74,15 +76,16 @@ * Options toggling supported: `/before(?imx-imx)after/`, `/before(?imx-imx:subexpr)after/` ## 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... -* Some named properties, e.g. `/\p{Arabic}/`, list non-matching examples for ruby 2.0/2.1 (as the definitions changed in ruby 2.2). This would be "easy" to fix, but I can't be bothered... Feel free to make a pull request! +* Some named properties, e.g. `/\p{Arabic}/`, list non-matching examples for ruby 2.0/2.1 (as the definitions changed in ruby 2.2). This will be fixed in version 1.1.0 (see the pending pull request)! -There are also some various (increasingly obscure) unsupported bits of syntax, which I cannot be bothered to write out fully here. Full documentation on all the intricate obscurities in the ruby (version 2.x) regexp parser can be found [here](https://raw.githubusercontent.com/k-takata/Onigmo/master/doc/RE). To name a couple: +There are also some various (increasingly obscure) unsupported bits of syntax; some of which I haven't yet investigated. Much of this is not even mentioned in the ruby docs! Full documentation on all the intricate obscurities in the ruby (version 2.x) regexp parser can be found [here](https://raw.githubusercontent.com/k-takata/Onigmo/master/doc/RE). To name a few: * Conditional capture groups, e.g. `/(group1)? (?(1)yes|no)/.examples` (which *should* return: `["group1 yes", " no"]`) -* Back reference by relatve group number, e.g. `/(a)(b)(c)(d) \k<-2>/.examples` (which *should* return: `["abcd c"]`) +* Back reference by relative group number, e.g. `/(a)(b)(c)(d) \k<-2>/.examples` (which *should* return: `["abcd c"]`) +* Back reference using single quotes, and for group numbers, e.g. `/(a) \k'1'/.examples` (which is really just alternative syntax for `/(a) \1/`!) ## 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, there are many good blog posts out on the internet. The [wikipedia entry](http://en.wikipedia.org/wiki/Regular_expression)'s not bad either. @@ -90,11 +93,11 @@ Using any of the following will raise a RegexpExamples::IllegalSyntax exception: * Lookarounds, e.g. `/foo(?=bar)/`, `/foo(?!bar)/`, `/(?<=foo)bar/`, `/(?<!foo)bar/` * [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 `^`, `\A` and `\G` 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. -* Subexpression calls, e.g. `/(?<name> ... \g<name>* )/` +* Subexpression calls (`\g`), e.g. `/(?<name> ... \g<name>* )/` (Note: Backreferences are not really "regular" either, but I got these to work with a bit of hackery!) ##Configuration Options @@ -135,11 +138,12 @@ (Note: I may develop a much more efficient way to "generate one example" in a later release of this gem.) ## TODO * Performance improvements: - * Use of lambdas/something (in [constants.rb](lib/regexp-examples/constants.rb)) to improve the library load time. - * (Maybe?) add a `max_examples` configuration option and use lazy evaluation, to ensure the method never "freezes" + * Use of lambdas/something (in [constants.rb](lib/regexp-examples/constants.rb)) to improve the library load time. See the pending pull request. + * (Maybe?) add a `max_examples` configuration option and use lazy evaluation, to ensure the method never "freezes". +* Potential future feature: `Regexp#random_example` - but implementing this properly is non-trivial, due to performance issues that need addressing first! * Write a blog post about how this amazing gem works! :) ## Contributing 1. Fork it ( https://github.com/[my-github-username]/regexp-examples/fork )