add - method to add another regex builder to current regex

add - unnamed group method and shortcuts for capture* methods
rft - non backward compatibility - make Builder constructor package-private

Author: MerkushevKirill

src/main/java/ru/lanwen/verbalregex/VerbalExpression.java

@@ -14,10 +14,33 @@ public static class Builder {
         private StringBuilder suffixes = new StringBuilder();
         private int modifiers = Pattern.MULTILINE;
 
+        /**
+         * Package private. Use {@link #regex()} to build a new one
+         * @since 1.2
+         */
+        Builder() {
+        }
+
+        /**
+         * Escapes any non-word char with two backslashes
+         * used by any method, except {@link #add(String)}
+         *
+         * @param pValue - the string for char escaping
+         * @return sanitized string value
+         */
         private String sanitize(final String pValue) {
             return pValue.replaceAll("[\\W]", "\\\\$0");
         }
 
+        /**
+         * Counts occurrences of some substring in whole string
+         * Same as org.apache.commons.lang3.StringUtils#countMatches(String, java.lang.String)
+         * by effect. Used to count braces for {@link #or(String)} method
+         *
+         * @param where - where to find
+         * @param what  - what needs to count matches
+         * @return 0 if nothing found, count of occurrences instead
+         */
         private int countOccurrencesOf(String where, String what) {
             return (where.length() - where.replace(what, "").length()) / what.length();
         }
@@ -40,11 +63,21 @@ public VerbalExpression build() {
          * @param pValue - literal expression, not sanitized
          * @return this builder
          */
-        public Builder add(String pValue) {
+        public Builder add(final String pValue) {
             this.source.append(pValue);
             return this;
         }
 
+        /**
+         * Append a regex from builder and wrap it with unnamed group (?: ... )
+         * @param regex - VerbalExpression.Builder, that not changed
+         * @return this builder
+         * @since 1.2
+         */
+        public Builder add(final Builder regex) {
+            return this.group().add(regex.build().toString()).endGr();
+        }
+
         /**
          * Enable or disable the expression to start at the beginning of the line
          *
@@ -147,7 +180,7 @@ public Builder anything() {
          * Add expression that matches anything, but not passed argument
          *
          * @param pValue - the string not to match
-         * @return
+         * @return this builder
          */
         public Builder anythingButNot(final String pValue) {
             return this.add("(?:[^" + sanitize(pValue) + "]*)");
@@ -273,6 +306,12 @@ public Builder anyOf(final String pValue) {
             return this;
         }
 
+        /**
+         * Shortcut to {@link #anyOf(String)}
+         *
+         * @param value - CharSequence every char from can be matched
+         * @return this builder
+         */
         public Builder any(final String value) {
             return this.anyOf(value);
         }
@@ -452,6 +491,35 @@ public Builder capture() {
             return this.add("(");
         }
 
+        /**
+         * Shortcut for {@link #capture()}
+         *
+         * @return this builder
+         * @since 1.2
+         */
+        public Builder capt() {
+            return this.capture();
+        }
+
+        /**
+         * Same as {@link #capture()}, but don't save result
+         * May be used to set count of duplicated captures, without creating a new saved capture
+         * Example:
+         *      // Without group() - count(2) applies only to second capture
+         *      regex().group()
+         *          .capt().range("0", "1").endCapt().tab()
+         *          .capt().digit().count(5).endCapt()
+         *          .endGr().count(2);
+         *
+         *
+         * @return this builder
+         * @since 1.2
+         */
+        public Builder group() {
+            this.suffixes.append(")");
+            return this.add("(?:");
+        }
+
         /**
          * Close brace for previous capture and remove last closed brace from suffixes
          * Can be used to continue build regex after capture or to add multiply captures
@@ -463,12 +531,39 @@ public Builder endCapture() {
                 this.suffixes.setLength(suffixes.length() - 1);
                 return this.add(")");
             } else {
-                throw new IllegalStateException("Can't end capture when it not started");
+                throw new IllegalStateException("Can't end capture (group) when it not started");
             }
         }
-    }
 
+        /**
+         * Shortcut for {@link #endCapture()}
+         * @return this builder
+         * @since 1.2
+         */
+        public Builder endCapt() {
+            return this.endCapture();
+        }
+
+        /**
+         * Closes current unnamed and unsaved group
+         * Shortcut for {@link #endCapture()}
+         * Use it with {@link #group()} for prettify code
+         * Example:
+         *      regex().group().maybe("word").count(2).endGr()
+         * @return this builder
+         * @since 1.2
+         */
+        public Builder endGr() {
+            return this.endCapture();
+        }
+    }
 
+    /**
+     * Use builder {@link #regex()} (or {@link #regex(ru.lanwen.verbalregex.VerbalExpression.Builder)})
+     * to create new instance of VerbalExpression
+     *
+     * @param pattern - {@link java.util.regex.Pattern} that constructed by builder
+     */
     private VerbalExpression(final Pattern pattern) {
         this.pattern = pattern;
     }
@@ -518,6 +613,7 @@ public String getText(final String toTest) {
      * @param toTest - string to extract from
      * @param group  - group to extract
      * @return extracted group
+     * @since 1.1
      */
     public String getText(final String toTest, final int group) {
         Matcher m = pattern.matcher(toTest);
@@ -539,6 +635,7 @@ public String toString() {
      *
      * @param pBuilder - instance to clone
      * @return new VerbalExpression.Builder copied from passed
+     * @since 1.1
      */
     public static Builder regex(final Builder pBuilder) {
         Builder builder = new Builder();
@@ -555,6 +652,7 @@ public static Builder regex(final Builder pBuilder) {
      * Creates new instance of VerbalExpression builder
      *
      * @return new VerbalExpression.Builder
+     * @since 1.1
      */
     public static Builder regex() {
         return new Builder();

src/test/java/ru/lanwen/verbalregex/BasicFunctionalityUnitTest.java

@@ -2,9 +2,10 @@
 
 import org.junit.Test;
 
-import static org.hamcrest.CoreMatchers.equalTo;
-import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.CoreMatchers.*;
 import static org.junit.Assert.*;
+import static ru.lanwen.verbalregex.VerbalExpression.regex;
+import static ru.lanwen.verbalregex.matchers.TestsExactMatcher.matchesExactly;
 
 public class BasicFunctionalityUnitTest {
     @Test
@@ -69,7 +70,7 @@ public void testStartOfLine() {
 
     @Test
     public void testStartOfLineFalse() {
-        VerbalExpression testRegex = VerbalExpression.regex()
+        VerbalExpression testRegex = regex()
                 .startOfLine(false)
                 .then("a")
                 .build();
@@ -79,7 +80,7 @@ public void testStartOfLineFalse() {
 
     @Test
     public void testRangeWithMultiplyRanges() throws Exception {
-        VerbalExpression regex = VerbalExpression.regex().range("a", "z", "A", "Z").build();
+        VerbalExpression regex = regex().range("a", "z", "A", "Z").build();
 
         assertThat("Regex with multi-range differs from expected", regex.toString(), equalTo("[a-zA-Z]"));
         assertThat("Regex don't matches letter", regex.test("b"), is(true));
@@ -102,7 +103,7 @@ public void testEndOfLine() {
 
     @Test
     public void testEndOfLineIsFalse() {
-        VerbalExpression testRegex = VerbalExpression.regex()
+        VerbalExpression testRegex = regex()
                 .find("a")
                 .endOfLine(false)
                 .build();
@@ -141,8 +142,8 @@ public void testAnyOf() {
 
     @Test
     public void testAnySameAsAnyOf() {
-        VerbalExpression any = VerbalExpression.regex().any("abc").build();
-        VerbalExpression anyOf = VerbalExpression.regex().anyOf("abc").build();
+        VerbalExpression any = regex().any("abc").build();
+        VerbalExpression anyOf = regex().anyOf("abc").build();
 
         assertThat("any differs from anyOf", any.toString(), equalTo(anyOf.toString()));
     }
@@ -189,7 +190,7 @@ public void testBr() {
                 .then("def")
                 .build();
 
-       assertThat(".br() differs from .lineBreak()", testRegexBr.toString(), equalTo(testRegexLineBr.toString()));
+        assertThat(".br() differs from .lineBreak()", testRegexBr.toString(), equalTo(testRegexLineBr.toString()));
     }
 
     @Test
@@ -224,7 +225,7 @@ public void testWithAnyCase() {
 
     @Test
     public void testWithAnyCaseIsFalse() {
-        VerbalExpression testRegex = VerbalExpression.regex()
+        VerbalExpression testRegex = regex()
                 .withAnyCase()
                 .startOfLine()
                 .then("a")
@@ -236,7 +237,7 @@ public void testWithAnyCaseIsFalse() {
 
     @Test
     public void testSearchOneLine() {
-        VerbalExpression testRegex = VerbalExpression.regex()
+        VerbalExpression testRegex = regex()
                 .startOfLine()
                 .then("a")
                 .br()
@@ -274,18 +275,24 @@ public void testGetText() {
     @Test
     public void testStartCapture() {
         String text = "aaabcd";
-        VerbalExpression regex = VerbalExpression.regex()
+        VerbalExpression regex = regex()
                 .find("a").count(3)
                 .capture().find("b").anything().build();
 
         assertThat("regex don't match string", regex.getText(text), equalTo(text));
         assertThat("can't get first captured group", regex.getText(text, 1), equalTo("bcd"));
     }
 
+    @Test
+    public void captIsSameAsCapture() {
+        assertThat("Capt produce defferent than capture regex", regex().capt().build().toString(),
+                equalTo(regex().capture().build().toString()));
+    }
+
     @Test
     public void shouldReturnEmptyStringWhenNoGroupFound() {
         String text = "abc";
-        VerbalExpression regex = VerbalExpression.regex().find("d").capture().find("e").build();
+        VerbalExpression regex = regex().find("d").capture().find("e").build();
 
         assertThat("regex don't match string", regex.getText(text), equalTo(""));
         assertThat("first captured group not empty string", regex.getText(text, 1), equalTo(""));
@@ -298,17 +305,17 @@ public void testCountWithRange() {
         String text2c = "abcce";
         String text1c = "abce";
 
-        VerbalExpression regex = VerbalExpression.regex().find("c").count(2, 3).build();
+        VerbalExpression regex = regex().find("c").count(2, 3).build();
 
         assertThat("regex don't match string", regex.getText(text4c), equalTo("ccc"));
         assertThat("regex don't match string", regex.getText(text2c), equalTo("cc"));
         assertThat("regex don't match string", regex.test(text1c), is(false));
     }
 
-   @Test
+    @Test
     public void testEndCapture() {
         String text = "aaabcd";
-        VerbalExpression regex = VerbalExpression.regex()
+        VerbalExpression regex = regex()
                 .find("a")
                 .capture().find("b").anything().endCapture().then("cd").build();
 
@@ -320,16 +327,17 @@ public void testEndCapture() {
     @Test
     public void testMultiplyCapture() {
         String text = "aaabcd";
-        VerbalExpression regex = VerbalExpression.regex()
+        VerbalExpression regex = regex()
                 .find("a").count(1)
                 .capture().find("b").endCapture().anything().capture().find("d").build();
 
         assertThat("can't get first captured group", regex.getText(text, 1), equalTo("b"));
         assertThat("can't get second captured group", regex.getText(text, 2), equalTo("d"));
     }
+
     @Test
     public void testOrWithCapture() {
-        VerbalExpression testRegex = VerbalExpression.regex()
+        VerbalExpression testRegex = regex()
                 .capture()
                 .find("abc")
                 .or("def")
@@ -343,4 +351,18 @@ public void testOrWithCapture() {
         assertThat(testRegex.getText("xxxabcdefzzz", 2), equalTo("abcnull"));
     }
 
+    @Test
+    public void addRegexBuilderWrapsItWithUnsavedGroup() throws Exception {
+        VerbalExpression regex = regex()
+                .add(regex().capt().find("string").count(2).endCapt().count(1).digit()).count(2).build();
+
+        assertThat("Added regex builder don't wrapped with unsaved group",
+                regex.toString(), startsWith("(?:((?:string"));
+
+        String example = "stringstring1";
+        String example2digit = "stringstring11";
+
+        assertThat(regex, matchesExactly(example + example));
+        assertThat(regex, not(matchesExactly(example2digit)));
+    }
 }

src/test/java/ru/lanwen/verbalregex/matchers/TestMatchMatcher.java

@@ -0,0 +1,40 @@
+package ru.lanwen.verbalregex.matchers;
+
+import org.hamcrest.Description;
+import org.hamcrest.Factory;
+import org.hamcrest.TypeSafeMatcher;
+import ru.lanwen.verbalregex.VerbalExpression;
+
+/**
+ * User: lanwen
+ * Date: 29.05.14
+ * Time: 20:06
+ */
+public class TestMatchMatcher extends TypeSafeMatcher<VerbalExpression> {
+
+    private String toTest;
+
+    private TestMatchMatcher(String toTest) {
+        this.toTest = toTest;
+    }
+
+    @Override
+    protected boolean matchesSafely(VerbalExpression verbalExpression) {
+        return verbalExpression.test(toTest);
+    }
+
+    @Override
+    public void describeTo(Description description) {
+        description.appendText("regex should match to ").appendValue(toTest);
+    }
+
+    @Override
+    protected void describeMismatchSafely(VerbalExpression item, Description mismatchDescription) {
+        mismatchDescription.appendText(item.toString()).appendText(" don't matches this string");
+    }
+
+    @Factory
+    public static TestMatchMatcher matchesTo(String test) {
+        return new TestMatchMatcher(test);
+    }
+}