Merge pull request hamcrest#57 from josephw/pattern-matcher

Add a matcher to check a string against a regular expression

hamcrest-library/matchers.xml

@@ -45,6 +45,7 @@
     <factory class="org.hamcrest.text.IsEqualIgnoringWhiteSpace"/>
     <factory class="org.hamcrest.text.IsEmptyString"/>
     <factory class="org.hamcrest.text.IsBlankString"/>
+    <factory class="org.hamcrest.text.MatchesPattern"/>
     <factory class="org.hamcrest.text.StringContainsInOrder"/>
 
     <!-- Object -->

hamcrest-library/src/main/java/org/hamcrest/text/MatchesPattern.java

@@ -0,0 +1,44 @@
+package org.hamcrest.text;
+
+import java.util.regex.Pattern;
+
+import org.hamcrest.Description;
+import org.hamcrest.Factory;
+import org.hamcrest.Matcher;
+import org.hamcrest.TypeSafeMatcher;
+
+public class MatchesPattern extends TypeSafeMatcher<String> {
+    private final Pattern pattern;
+
+    public MatchesPattern(Pattern pattern) {
+        this.pattern = pattern;
+    }
+
+    @Override
+    protected boolean matchesSafely(String item) {
+        return pattern.matcher(item).matches();
+    }
+
+    @Override
+    public void describeTo(Description description) {
+        description.appendText("a string matching the pattern '" + pattern + "'");
+    }
+
+    /**
+     * Creates a matcher of {@link String} that matches when the examined string
+     * exactly matches the given {@link Pattern}.
+     */
+    @Factory
+    public static Matcher<String> matchesPattern(Pattern pattern) {
+        return new MatchesPattern(pattern);
+    }
+
+    /**
+     * Creates a matcher of {@link String} that matches when the examined string
+     * exactly matches the given regular expression, treated as a {@link Pattern}.
+     */
+    @Factory
+    public static Matcher<String> matchesPattern(String regex) {
+        return new MatchesPattern(Pattern.compile(regex));
+    }
+}

hamcrest-library/src/test/java/org/hamcrest/object/MatchesPatternTest.java

@@ -0,0 +1,63 @@
+package org.hamcrest.object;
+
+import static org.hamcrest.AbstractMatcherTest.assertDescription;
+import static org.hamcrest.AbstractMatcherTest.assertDoesNotMatch;
+import static org.hamcrest.AbstractMatcherTest.assertMismatchDescription;
+import static org.hamcrest.AbstractMatcherTest.assertNullSafe;
+import static org.hamcrest.AbstractMatcherTest.assertUnknownTypeSafe;
+import static org.junit.Assert.assertThat;
+
+import java.util.regex.Pattern;
+
+import org.hamcrest.Matcher;
+import org.hamcrest.text.MatchesPattern;
+import org.junit.Test;
+
+public class MatchesPatternTest {
+    @Test
+    public void copesWithNullsAndUnknownTypes() {
+        Matcher<String> matcher = new MatchesPattern(Pattern.compile("."));
+
+        assertNullSafe(matcher);
+        assertUnknownTypeSafe(matcher);
+    }
+
+    @Test
+    public void matchesExactString() {
+        assertThat("a", new MatchesPattern(Pattern.compile("a")));
+    }
+
+    @Test
+    public void doesNotMatchADifferentString() {
+        assertDoesNotMatch("A different string does not match", new MatchesPattern(Pattern.compile("a")), "b");
+    }
+
+    @Test
+    public void doesNotMatchSubstring() {
+        assertDoesNotMatch("A substring does not match", new MatchesPattern(Pattern.compile("a")), "ab");
+    }
+
+    @Test
+    public void hasAReadableDescription() {
+        Matcher<?> m = new MatchesPattern(Pattern.compile("a[bc](d|e)"));
+        assertDescription("a string matching the pattern 'a[bc](d|e)'", m );
+    }
+
+    @Test
+    public void describesAMismatch() {
+        final Matcher<String> matcher = new MatchesPattern(Pattern.compile("a"));
+        assertMismatchDescription("was \"Cheese\"", matcher, "Cheese");
+    }
+
+    @Test
+    public void factoryMethodAllowsCreationWithPattern() {
+        Matcher<?> m = MatchesPattern.matchesPattern(Pattern.compile("a[bc](d|e)"));
+        assertDescription("a string matching the pattern 'a[bc](d|e)'", m );
+    }
+
+    @Test
+    public void factoryMethodAllowsCreationWithString() {
+        Matcher<?> m = MatchesPattern.matchesPattern("a[bc](d|e)");
+        assertDescription("a string matching the pattern 'a[bc](d|e)'", m );
+    }
+}