Rework using GenOptions to allow more control over "." matches

Author: kerrykimbrough

README.md

@@ -7,6 +7,7 @@
   * [How Does It Work?](#how-does-it-work)
     * [The basics](#the-basics)
     * [Exact matches vs. substring matches](#exact-matches-vs-substring-matches)
+    * [What matches "dot"?](#what-matches-dot)
     * [How to create longer matching strings](#how-to-create-longer-matching-strings)
     * [How to generate random matches repeatably](#how-to-generate-random-matches-repeatably)
     * [How to limit match length to a specific range](#how-to-limit-match-length-to-a-specific-range)
@@ -84,7 +85,7 @@ l^Ȩú(¹C³TÂI6ÓQaª}f*Allô, world!p±!éÇ'>aDÙ
 ```
 
 These strings contain not only a substring that matches the regular expression, but also some
-extraneous characters before and/or after the match. If the consumer of these strings recognizes a
+[extraneous characters](#what-matches-dot) before and/or after the match. If the consumer of these strings recognizes a
 general "substring match", that's exactly what you want to give it.
 
 But what if you need to generate only "exact" matches? In other words, strings containing only the matching characters.
@@ -108,6 +109,47 @@ Allô, world!
 Howdy, world!
 ```
 
+### What matches "dot"? ###
+
+What matches the regular expression `.`? In general, any printable character. For a `RegExpGen`, by default, that means "any printable character
+from the Latin-1 basic and supplemental Unicode blocks". But what if that includes characters that your application is not designed to handle?
+You can define exactly what "any printable character" means using the `GenOptions` for a `RegExpGen`.
+
+For example, you could make a ridiculously narrow definition like this:
+
+```java
+...
+// Given a JavaScript regular expression...
+String regexp = regexp( "<< My secret is [^\\d\\s]{8,32} >>");
+
+// ...and a random number generator...
+RandomGen random = getRandomGen();
+
+// ...create a RegExpGen instance...
+RegExpGen generator = Parser.parseRegExp( regexp);
+
+// ...matching "." with specific characters...
+generator.getOptions().setAnyPrintableChars( "1001 Anagrams!");
+...
+```
+
+Run this example and the result will be something like this:
+
+```
+Aag<< My secret is sgnggag!amm! >>s!Ag
+s11aa0Agra<< My secret is rsm!!nA!!Aanmnsgmmr >>m
+0m1ra! !n1gr 1<< My secret is mangAmr!!!m >>
+```
+
+Notice how the implicit `.*` expressions that generate the beginning and ending of [substring
+matches](#exact-matches-vs-substring-matches) draw only from the characters specified by
+`GenOptions.setAnyPrintableChars()`. And notice something else: the definition of "any printable"
+also affects how matches are generated for exclusionary character classes of the form `[^...]`.
+That's because these classes are interpreted to mean "any printable char *except* for...".
+
+For convenience, `GenOptions` defines some common candidates for "any printable", such as
+`GenOptions.ANY_LATIN_1` and `GenOptions.ANY_ASCII`.
+
 ### How to create longer matching strings ###
 
 For any regular expression, there is always a miniumum length for any matching string.  Sometimes
@@ -231,6 +273,7 @@ matches will always lie between the given limits. Instead, `RegExpGen` makes a s
   * **I'm getting strings with lots of crazy extra characters. What's the deal?**
 
     You should read about the difference between ["exact" matches and "substring" matches](#exact-matches-vs-substring-matches).
+    And if that's too crazy for you, try changing the definition of [what matches "dot"](#what-matches-dot).
 
   * **Where's the Javadoc?**
 

src/main/java/org/cornutum/regexpgen/GenOptions.java

@@ -0,0 +1,103 @@
+//////////////////////////////////////////////////////////////////////////////
+// 
+//                    Copyright 2020, Cornutum Project
+//                             www.cornutum.org
+//
+//////////////////////////////////////////////////////////////////////////////
+
+package org.cornutum.regexpgen;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Set;
+import java.util.stream.IntStream;
+
+import org.cornutum.regexpgen.util.ToString;
+
+import static java.util.stream.Collectors.toSet;
+
+/**
+ * Defines options for generating regular expression matches.
+ */
+public class GenOptions
+  {
+  /**
+   * Creates a new GenOptions instance.
+   */
+  public GenOptions()
+    {
+    setAnyPrintableChars( ANY_LATIN_1);
+    }
+
+  /**
+   * Changes the set of characters used to generate matches for the "." expression.
+   */
+  public void setAnyPrintableChars( Set<Character> chars)
+    {
+    anyPrintable_ = chars;
+    }
+
+  /**
+   * Changes the set of characters used to generate matches for the "." expression.
+   */
+  public void setAnyPrintableChars( String chars)
+    {
+    setAnyPrintableChars(
+      IntStream.range( 0, chars.length())
+      .mapToObj( i -> chars.charAt( i))
+      .collect( toSet()));
+    }
+
+  /**
+   * Returns the set of characters used to generate matches for the "." expression.
+   */
+  public Set<Character> getAnyPrintableChars()
+    {
+    return anyPrintable_;
+    }
+
+  public String toString()
+    {
+    return
+      ToString.getBuilder( this)
+      .toString();
+    }
+  
+  private Set<Character> anyPrintable_;
+
+  /**
+   * Return true if the character with the given code point is printable.
+   */
+  private static boolean isPrintable( int codePoint)
+    {
+    return
+      Character.toChars( codePoint)[0] == ' '
+      || !(Character.isSpaceChar( codePoint) || notVisible_.contains( Character.getType( codePoint))) ;
+    }
+
+  private static final List<Integer> notVisible_ =
+    Arrays.asList(
+      (int) Character.CONTROL,
+      (int) Character.SURROGATE,
+      (int) Character.UNASSIGNED);
+
+  private static Set<Character> printableChars( int startPoint, int endPoint)
+    {
+    return
+      IntStream.range( startPoint, endPoint)
+      .filter( GenOptions::isPrintable)
+      .mapToObj( i -> Character.valueOf( (char) i))
+      .collect( toSet());
+    }
+
+  /**
+   * All printable characters in the basic and supplemental Latin-1 code blocks
+   */
+  public static final Set<Character> ANY_LATIN_1 = Collections.unmodifiableSet( printableChars( 0, 256));
+
+  /**
+   * All printable characters in the ASCII code block
+   */
+  public static final Set<Character> ANY_ASCII = Collections.unmodifiableSet( printableChars( 0, 128));
+  }

src/main/java/org/cornutum/regexpgen/RegExpGen.java

@@ -22,6 +22,11 @@ public interface RegExpGen
    */
   public int getMaxLength();
 
+  /**
+   * Returns the {@link GenOptions options} for this generator.
+   */
+  public GenOptions getOptions();
+
   /**
    * Returns a random string within the given bounds that matches this regular expression.
    */

src/main/java/org/cornutum/regexpgen/js/AbstractRegExpGen.java

@@ -8,6 +8,7 @@
 package org.cornutum.regexpgen.js;
 
 import org.cornutum.regexpgen.Bounds;
+import org.cornutum.regexpgen.GenOptions;
 import org.cornutum.regexpgen.RandomGen;
 import org.cornutum.regexpgen.RegExpGen;
 import org.cornutum.regexpgen.util.ToString;
@@ -22,24 +23,25 @@ public abstract class AbstractRegExpGen implements RegExpGen
   /**
    * Creates a new AbstractRegExpGen instance.
    */
-  protected AbstractRegExpGen()
+  protected AbstractRegExpGen( GenOptions options)
     {
-    this( 1);
+    this( options, 1);
     }
 
   /**
    * Creates a new AbstractRegExpGen instance.
    */
-  protected AbstractRegExpGen( int length)
+  protected AbstractRegExpGen( GenOptions options, int length)
     {
-    this( length, length);
+    this( options, length, length);
     }
 
   /**
    * Creates a new AbstractRegExpGen instance.
    */
-  protected AbstractRegExpGen( Integer minOccur, Integer maxOccur)
+  protected AbstractRegExpGen( GenOptions options, Integer minOccur, Integer maxOccur)
     {
+    options_ = options;
     setOccurrences( minOccur, maxOccur);
     }
 
@@ -83,6 +85,14 @@ public int getMaxOccur()
     return occurrences_.getMaxValue();
     }
 
+  /**
+   * Returns the {@link GenOptions options} for this generator.
+   */
+  public GenOptions getOptions()
+    {
+    return options_;
+    }
+
   /**
    * Returns a random string within the given bounds that matches this regular expression.
    */
@@ -195,7 +205,10 @@ public int hashCode()
   private Bounds occurrences_;
   private boolean anchoredStart_ = false;
   private boolean anchoredEnd_ = false;
+  private final GenOptions options_;
 
+  public static final GenOptions BUILDER_OPTIONS = new GenOptions();
+  
   /**
    * Builds an {@link AbstractRegExpGen} instance.
    */

src/main/java/org/cornutum/regexpgen/js/AlternativeGen.java

@@ -8,6 +8,7 @@
 package org.cornutum.regexpgen.js;
 
 import org.cornutum.regexpgen.Bounds;
+import org.cornutum.regexpgen.GenOptions;
 import org.cornutum.regexpgen.RandomGen;
 import org.cornutum.regexpgen.RegExpGen;
 import org.cornutum.regexpgen.util.ToString;
@@ -30,16 +31,17 @@ public class AlternativeGen extends AbstractRegExpGen
   /**
    * Creates a new AlternativeGen instance.
    */
-  public AlternativeGen()
+  public AlternativeGen( GenOptions options)
     {
-    super();
+    super( options);
     }
 
   /**
    * Creates a new AlternativeGen instance.
    */
-  public AlternativeGen( RegExpGen... members)
+  public AlternativeGen( GenOptions options, RegExpGen... members)
     {
+    this( options);
     for( RegExpGen member : members)
       {
       add( member);
@@ -49,8 +51,9 @@ public AlternativeGen( RegExpGen... members)
   /**
    * Creates a new AlternativeGen instance.
    */
-  public <T extends RegExpGen> AlternativeGen( Iterable<T> members)
+  public <T extends RegExpGen> AlternativeGen( GenOptions options, Iterable<T> members)
     {
+    this( options);
     for( RegExpGen member : members)
       {
       add( member);
@@ -262,6 +265,14 @@ public static Builder builder()
     return new Builder();
     }
 
+  /**
+   * Returns an {@link AlternativeGen} builder.
+   */
+  public static Builder builder( GenOptions options)
+    {
+    return new Builder( options);
+    }
+
   public String toString()
     {
     return
@@ -298,6 +309,16 @@ public int hashCode()
    */
   public static class Builder extends BaseBuilder<Builder>
     {
+    public Builder()
+      {
+      this( BUILDER_OPTIONS);
+      }
+
+    public Builder( GenOptions options)
+      {
+      alternative_ = new AlternativeGen( options);
+      }
+    
     /**
      * Returns the {@link AbstractRegExpGen} instance for this builder.
      */
@@ -329,6 +350,6 @@ public AlternativeGen build()
       return alternative_;
       }
 
-    private AlternativeGen alternative_ = new AlternativeGen();
+    private AlternativeGen alternative_; 
     }
   }