regexp-examples 1.3.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7ce9ae460670e7c7525a38992990271751c311d4
-  data.tar.gz: f9501da52ba2b57b6ef92324f43ba7252a8d70f8
+  metadata.gz: e7ea454116c6367dba39b57fb8ca5fdd6b1e5062
+  data.tar.gz: a41c56176c0bbf007e99780790f3e196d4605190
 SHA512:
-  metadata.gz: 5fabfe8bf9dcb41d4e1a6ceba7b8c98278ea44f12ea657409821abd25fbf856b11effc726d67d06c0d2c67e728caf24853a89e2e73f26f1c5fba58ea397478e9
-  data.tar.gz: 717755a835ca5f0a611c4a62ba4d8f4b90b7a422ce8d80136f79a97a71ee2f439b027c3fbd42f68ac79e65884940f0004b9f35a72197e8748cc6c7fef2680891
+  metadata.gz: 41f307047bbd5ca1539d6eda5d4035b91649187fdb015c449c2f56a64353c601911b1da465df0e891d01fed3344e70b3bc1efbfeaa8bfd61d371b0e1a0bf5c12
+  data.tar.gz: 2c126a5b52842b9c2b5b13fbf3243e09f6ae29d0d290561e050566bf6fa94401fa3d33a6d492bdec177ce1be9bacd49cee363ff0ce552b2986b1e0da22eea9ce

data/README.md

@@ -10,9 +10,8 @@ Extends the `Regexp` class with the methods: `Regexp#examples` and `Regexp#rando
 
 `Regexp#random_example` returns one, random string (from all possible strings!!) that matches the regex.
 
-\* If the regex has an infinite number of possible srings that match it, such as `/a*b+c{2,}/`,
+\* If the regex has an infinite number of possible strings 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).
 
 If you'd like to understand how/why this gem works, please check out my [blog post](https://tom-lord.github.io/Reverse-Engineering-Regular-Expressions/) about it.
@@ -112,11 +111,11 @@ Long answer:
   * 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")}/`
+* 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"), `/\P{^Canadian\_Aboriginal}/` ("Not not a Canadian aboriginal character")
+, `/\p{^Ll}/` ("Not a lowercase letter"), `/\P{^Canadian_Aboriginal}/` ("Not not a Canadian aboriginal character")
   * ...Even between different ruby versions!! (e.g. `/\p{Arabic}/.examples(max_group_results: 999)` will give you a different answer in ruby v2.1.x and v2.2.x)
 * **Arbitrarily complex combinations of all the above!**
 
@@ -126,7 +125,7 @@ Long answer:
   * Extended form examples: `/line1 #comment \n line2/x.examples #=> ["line1line2"]`
   * Options toggling supported: `/before(?imx-imx)after/`, `/before(?imx-imx:subexpr)after/`
 
-##Configuration Options
+## Configuration Options
 
 When generating examples, the gem uses 3 configurable values to limit how many examples are listed:
 
@@ -149,7 +148,9 @@ When generating examples, the gem uses 3 configurable values to limit how many e
 
 `Rexexp#examples` makes use of *all* these options; `Rexexp#random_example` only uses `max_repeater_variance`, since the other options are redundant.
 
-To use an alternative value, simply pass the configuration option as follows:
+### Defining custom configuration values
+
+To use an alternative value, you can either pass the configuration option as a parameter:
 
 ```ruby
 /a*/.examples(max_repeater_variance: 5)
@@ -162,6 +163,24 @@ To use an alternative value, simply pass the configuration option as follows:
   #=> "A very unlikely result!"
 ```
 
+Or, set an alternative value *within a block*:
+
+```ruby
+RegexpExamples::Config.with_configuration(max_repeater_variance: 5) do
+  # ...
+end
+```
+
+Or, globally set a different default value:
+
+```ruby
+# e.g In a rails project, you may wish to place this in
+# config/initializers/regexp_examples.rb
+RegexpExamples::Config.max_repeater_variance = 5
+RegexpExamples::Config.max_group_results = 10
+RegexpExamples::Config.max_results_limit = 20000
+```
+
 A sensible use case might be, for example, to generate all 1-5 digit strings:
 
 ```ruby
@@ -169,12 +188,16 @@ A sensible use case might be, for example, to generate all 1-5 digit strings:
   #=> ['0', '1', '2', ..., '99998', '99999']
 ```
 
+### Configuration Notes
+
 Due to code optimisation, `Regexp#random_example` runs pretty fast even on very complex patterns.
 (I.e. It's typically a _lot_ faster than using `/pattern/.examples.sample(1)`.)
 For instance, the following takes no more than ~ 1 second on my machine:
 
 `/.*\w+\d{100}/.random_example(max_repeater_variance: 1000)`
 
+All forms of configuration mentioned above **are thread safe**.
+
 ## Bugs and TODOs
 
 There are no known major bugs with this library. However, there are a few obscure issues that you *may* encounter:

data/lib/core_extensions/regexp/examples.rb

@@ -5,19 +5,15 @@ module CoreExtensions
     # No core classes are extended in any way, other than the above two methods.
     module Examples
       def examples(**config_options)
-        RegexpExamples::ResultCountLimiters.configure!(
-          max_repeater_variance: config_options[:max_repeater_variance],
-          max_group_results: config_options[:max_group_results],
-          max_results_limit: config_options[:max_results_limit]
-        )
-        examples_by_method(:result)
+        RegexpExamples::Config.with_configuration(config_options) do
+          examples_by_method(:result)
+        end
       end
 
       def random_example(**config_options)
-        RegexpExamples::ResultCountLimiters.configure!(
-          max_repeater_variance: config_options[:max_repeater_variance]
-        )
-        examples_by_method(:random_result).sample(1).first
+        RegexpExamples::Config.with_configuration(config_options) do
+          examples_by_method(:random_result).sample
+        end
       end
 
       private

data/lib/regexp-examples/constants.rb

@@ -1,9 +1,47 @@
 # :nodoc:
 module RegexpExamples
   # Configuration settings to limit the number/length of Regexp examples generated
-  class ResultCountLimiters
+  class Config
+    class << self
+      def with_configuration(**new_config)
+        original_config = config.dup
+
+        begin
+          self.config = new_config
+          result = yield
+        ensure
+          self.config = original_config
+        end
+
+        result
+      end
+
+      # Thread-safe getters and setters
+      %i[max_repeater_variance max_group_results max_results_limit].each do |m|
+        define_method(m) do
+          config[m]
+        end
+        define_method("#{m}=") do |value|
+          config[m] = value
+        end
+      end
+
+      private
+
+      def config=(**args)
+        Thread.current[:regexp_examples_config].merge!(args)
+      end
+
+      def config
+        Thread.current[:regexp_examples_config] ||= {
+          max_repeater_variance: MAX_REPEATER_VARIANCE_DEFAULT,
+          max_group_results: MAX_GROUP_RESULTS_DEFAULT,
+          max_results_limit: MAX_RESULTS_LIMIT_DEFAULT
+        }
+      end
+    end
     # The maximum variance for any given repeater, to prevent a huge/infinite number of
-    # examples from being listed. For example, if @@max_repeater_variance = 2 then:
+    # examples from being listed. For example, if self.max_repeater_variance = 2 then:
     # .* is equivalent to .{0,2}
     # .+ is equivalent to .{1,3}
     # .{2,} is equivalent to .{2,4}
@@ -12,7 +50,7 @@ module RegexpExamples
     MAX_REPEATER_VARIANCE_DEFAULT = 2
 
     # Maximum number of characters returned from a char set, to reduce output spam
-    # For example, if @@max_group_results = 5 then:
+    # For example, if self.max_group_results = 5 then:
     # \d is equivalent to [01234]
     # \w is equivalent to [abcde]
     MAX_GROUP_RESULTS_DEFAULT = 5
@@ -22,28 +60,6 @@ module RegexpExamples
     # /[ab]{30}/.examples
     # (Which would attempt to generate 2**30 == 1073741824 examples!!!)
     MAX_RESULTS_LIMIT_DEFAULT = 10_000
-    class << self
-      attr_reader :max_repeater_variance, :max_group_results, :max_results_limit
-      def configure!(max_repeater_variance: nil,
-                     max_group_results: nil,
-                     max_results_limit: nil)
-        @max_repeater_variance = (max_repeater_variance || MAX_REPEATER_VARIANCE_DEFAULT)
-        @max_group_results = (max_group_results || MAX_GROUP_RESULTS_DEFAULT)
-        @max_results_limit = (max_results_limit || MAX_RESULTS_LIMIT_DEFAULT)
-      end
-    end
-  end
-
-  def self.max_repeater_variance
-    ResultCountLimiters.max_repeater_variance
-  end
-
-  def self.max_group_results
-    ResultCountLimiters.max_group_results
-  end
-
-  def self.max_results_limit
-    ResultCountLimiters.max_results_limit
   end
 
   # Definitions of various special characters, used in regular expressions.

data/lib/regexp-examples/helpers.rb

@@ -10,10 +10,13 @@ module RegexpExamples
   # Edge case:
   # permutations_of_strings [ [] ] #=> nil
   # (For example, ths occurs during /[^\d\D]/.examples #=> [])
-  def self.permutations_of_strings(arrays_of_strings, max_results_limiter = MaxResultsLimiterByProduct.new)
+  def self.permutations_of_strings(arrays_of_strings,
+                                   max_results_limiter = MaxResultsLimiterByProduct.new)
     partial_result = max_results_limiter.limit_results(arrays_of_strings.shift)
     return partial_result if arrays_of_strings.empty?
-    partial_result.product(permutations_of_strings(arrays_of_strings, max_results_limiter)).map do |result|
+    partial_result.product(
+      permutations_of_strings(arrays_of_strings, max_results_limiter)
+    ).map do |result|
       join_preserving_capture_groups(result)
     end
   end

data/lib/regexp-examples/max_results_limiter.rb

@@ -1,5 +1,6 @@
 module RegexpExamples
-  class MaxResultsLimiter # Base class
+  # Abstract (base) class to assist limiting Regexp.examples max results
+  class MaxResultsLimiter
     def initialize(initial_results_count)
       @results_count = initial_results_count
     end
@@ -25,7 +26,8 @@ module RegexpExamples
 
     def results_allowed_from(partial_results, limiter_method)
       partial_results.first(
-        RegexpExamples.max_results_limit.public_send(limiter_method, @results_count)
+        RegexpExamples::Config.max_results_limit
+          .public_send(limiter_method, @results_count)
       )
     end
   end

data/lib/regexp-examples/repeaters.rb

@@ -10,7 +10,7 @@ module RegexpExamples
     end
 
     def result
-      group_results = group.result.first(RegexpExamples.max_group_results)
+      group_results = group.result.first(RegexpExamples::Config.max_group_results)
       results = []
       max_results_limiter = MaxResultsLimiterBySum.new
       min_repeats.upto(max_repeats) do |repeats|
@@ -51,7 +51,7 @@ module RegexpExamples
     def initialize(group)
       super
       @min_repeats = 0
-      @max_repeats = RegexpExamples.max_repeater_variance
+      @max_repeats = RegexpExamples::Config.max_repeater_variance
     end
   end
 
@@ -61,7 +61,7 @@ module RegexpExamples
     def initialize(group)
       super
       @min_repeats = 1
-      @max_repeats = RegexpExamples.max_repeater_variance + 1
+      @max_repeats = RegexpExamples::Config.max_repeater_variance + 1
     end
   end
 
@@ -80,19 +80,14 @@ module RegexpExamples
     def initialize(group, min, has_comma, max)
       super(group)
       @min_repeats = min || 0
-      if max # e.g. {1,100} --> Treat as {1,3} (by default max_repeater_variance)
-        @max_repeats = smallest(max, @min_repeats + RegexpExamples.max_repeater_variance)
-      elsif has_comma # e.g. {2,} --> Treat as {2,4} (by default max_repeater_variance)
-        @max_repeats = @min_repeats + RegexpExamples.max_repeater_variance
-      else # e.g. {3} --> Treat as {3,3}
-        @max_repeats = @min_repeats
-      end
-    end
-
-    private
-
-    def smallest(x, y)
-      x < y ? x : y
+      @max_repeats = if !has_comma
+                       @min_repeats
+                     else
+                       [
+                         max,
+                         @min_repeats + RegexpExamples::Config.max_repeater_variance
+                       ].compact.min
+                     end
     end
   end
 end

data/lib/regexp-examples/version.rb

@@ -1,4 +1,4 @@
 # Gem version
 module RegexpExamples
-  VERSION = '1.3.2'.freeze
+  VERSION = '1.4.0'.freeze
 end

data/spec/config_spec.rb

@@ -0,0 +1,135 @@
+RSpec.describe RegexpExamples::Config do
+
+  describe 'max_repeater_variance' do
+    context 'as a passed parameter' do
+      it 'with low limit' do
+        expect(/[A-Z]/.examples(max_results_limit: 5))
+          .to match_array %w(A B C D E)
+      end
+      it 'with (default) high limit' do
+        expect(/[ab]{14}/.examples.length)
+          .to be <= 10000 # NOT 2**14 == 16384, because it's been limited
+      end
+      it 'with (custom) high limit' do
+        expect(/[ab]{14}/.examples(max_results_limit: 20000).length)
+          .to eq 16384 # NOT 10000, because it's below the limit
+      end
+      it 'for boolean or groups' do
+        expect(/[ab]{3}|[cd]{3}/.examples(max_results_limit: 10).length)
+          .to eq 10
+      end
+      it 'for case insensitive examples' do
+        expect(/[ab]{3}/i.examples(max_results_limit: 10).length)
+          .to be <= 10
+      end
+      it 'for range repeaters' do
+        expect(/[ab]{2,3}/.examples(max_results_limit: 10).length)
+          .to be <= 10 # NOT 4 + 8 = 12
+      end
+      it 'for backreferences' do
+        expect(/([ab]{3})\1?/.examples(max_results_limit: 10).length)
+          .to be <= 10 # NOT 8 * 2 = 16
+      end
+      it 'for a complex pattern' do
+        expect(/(a|[bc]{2})\1{1,3}/.examples(max_results_limit: 14).length)
+          .to be <= 14 # NOT (1 + 4) * 3 = 15
+      end
+    end
+
+    context 'as a global setting' do
+      before do
+        @original = RegexpExamples::Config.max_results_limit
+        RegexpExamples::Config.max_results_limit = 5
+      end
+      after do
+        RegexpExamples::Config.max_results_limit = @original
+      end
+
+      it 'sets limit without passing explicitly' do
+        expect(/[A-Z]/.examples)
+          .to match_array %w(A B C D E)
+      end
+    end
+  end # describe 'max_results_limit'
+
+  describe 'max_repeater_variance' do
+    context 'as a passed parameter' do
+      it 'with a larger value' do
+        expect(/a+/.examples(max_repeater_variance: 5))
+          .to match_array %w(a aa aaa aaaa aaaaa aaaaaa)
+      end
+      it 'with a lower value' do
+        expect(/a{4,8}/.examples(max_repeater_variance: 0))
+          .to eq %w(aaaa)
+      end
+    end
+
+    context 'as a global setting' do
+      before do
+        @original = RegexpExamples::Config.max_repeater_variance
+        RegexpExamples::Config.max_repeater_variance = 5
+      end
+      after do
+        RegexpExamples::Config.max_repeater_variance = @original
+      end
+
+      it 'sets limit without passing explicitly' do
+        expect(/a+/.examples)
+          .to match_array %w(a aa aaa aaaa aaaaa aaaaaa)
+      end
+    end
+  end # describe 'max_repeater_variance'
+
+  describe 'max_group_results' do
+    context 'as a passed parameter' do
+      it 'with a larger value' do
+        expect(/\d/.examples(max_group_results: 10))
+          .to match_array %w(0 1 2 3 4 5 6 7 8 9)
+      end
+      it 'with a lower value' do
+        expect(/\d/.examples(max_group_results: 3))
+          .to match_array %w(0 1 2)
+      end
+    end
+
+    context 'as a global setting' do
+      before do
+        @original = RegexpExamples::Config.max_group_results
+        RegexpExamples::Config.max_group_results = 10
+      end
+      after do
+        RegexpExamples::Config.max_group_results = @original
+      end
+
+      it 'sets limit without passing explicitly' do
+        expect(/\d/.examples)
+          .to match_array %w(0 1 2 3 4 5 6 7 8 9)
+      end
+    end
+  end # describe 'max_group_results'
+
+  describe 'thread safety' do
+    it 'uses thread-local global config values' do
+      thread = Thread.new do
+        RegexpExamples::Config.max_group_results = 1
+        expect(/\d/.examples).to eq %w(0)
+      end
+      sleep 0.1 # Give the above thread time to run
+      expect(/\d/.examples).to eq %w(0 1 2 3 4)
+      thread.join
+    end
+
+    it 'uses thread-local block config values' do
+      thread = Thread.new do
+        RegexpExamples::Config.with_configuration(max_group_results: 1) do
+          expect(/\d/.examples).to eq %w(0)
+          sleep 0.2 # Give the below thread time to run while this block is open
+        end
+      end
+      sleep 0.1 # Give the above thread time to run
+      expect(/\d/.examples).to eq %w(0 1 2 3 4)
+      thread.join
+    end
+  end # describe 'thread safety'
+
+end

data/spec/regexp-examples_spec.rb

@@ -316,24 +316,6 @@ RSpec.describe Regexp, '#examples' do
         end
       end
 
-      context 'max_repeater_variance config option' do
-        it do
-          expect(/a+/.examples(max_repeater_variance: 5))
-            .to match_array %w(a aa aaa aaaa aaaaa aaaaaa)
-        end
-        it do
-          expect(/a{4,8}/.examples(max_repeater_variance: 0))
-            .to eq %w(aaaa)
-        end
-      end
-
-      context 'max_group_results config option' do
-        it do
-          expect(/\d/.examples(max_group_results: 10))
-            .to match_array %w(0 1 2 3 4 5 6 7 8 9)
-        end
-      end
-
       context 'case insensitive' do
         it { expect(/ab/i.examples).to match_array %w(ab aB Ab AB) }
         it do
@@ -377,39 +359,4 @@ RSpec.describe Regexp, '#examples' do
       end
     end # context 'exact examples match'
   end # context 'returns matching strings'
-
-  context 'max_results_limit config option' do
-    it 'with low limit' do
-      expect(/[A-Z]/.examples(max_results_limit: 5))
-        .to match_array %w(A B C D E)
-    end
-    it 'with (default) high limit' do
-      expect(/[ab]{14}/.examples.length)
-        .to be <= 10000 # NOT 2**14 == 16384, because it's been limited
-    end
-    it 'with (custom) high limit' do
-      expect(/[ab]{14}/.examples(max_results_limit: 20000).length)
-        .to eq 16384 # NOT 10000, because it's below the limit
-    end
-    it 'for boolean or groups' do
-      expect(/[ab]{3}|[cd]{3}/.examples(max_results_limit: 10).length)
-        .to eq 10
-    end
-    it 'for case insensitive examples' do
-      expect(/[ab]{3}/i.examples(max_results_limit: 10).length)
-        .to be <= 10
-    end
-    it 'for range repeaters' do
-      expect(/[ab]{2,3}/.examples(max_results_limit: 10).length)
-        .to be <= 10 # NOT 4 + 8 = 12
-    end
-    it 'for backreferences' do
-      expect(/([ab]{3})\1?/.examples(max_results_limit: 10).length)
-        .to be <= 10 # NOT 8 * 2 = 16
-    end
-    it 'for a complex pattern' do
-      expect(/(a|[bc]{2})\1{1,3}/.examples(max_results_limit: 14).length)
-        .to be <= 14 # NOT (1 + 4) * 3 = 15
-    end
-  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: regexp-examples
 version: !ruby/object:Gem::Version
-  version: 1.3.2
+  version: 1.4.0
 platform: ruby
 authors:
 - Tom Lord
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-06 00:00:00.000000000 Z
+date: 2017-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -76,6 +76,7 @@ files:
 - lib/regexp-examples/version.rb
 - regexp-examples.gemspec
 - scripts/unicode_lister.rb
+- spec/config_spec.rb
 - spec/helpers.rb
 - spec/regexp-examples_spec.rb
 - spec/regexp-random_example_spec.rb
@@ -105,6 +106,7 @@ signing_key:
 specification_version: 4
 summary: Extends the Regexp class with '#examples' and '#random_example'
 test_files:
+- spec/config_spec.rb
 - spec/helpers.rb
 - spec/regexp-examples_spec.rb
 - spec/regexp-random_example_spec.rb