placeholders change is not backwards compatible

the module has been marked as experimental so making backwards
incompatible changes should be fine, but still we should at least do a
minor release for this.

see #178

.travis.yml

@@ -1,5 +1,5 @@
 language: java
-env: VERSION=2.6.5-SNAPSHOT
+env: VERSION=2.7.0-SNAPSHOT
 matrix:
   include:
     - dist: trusty

RELEASE_NOTES.md

@@ -1,6 +1,13 @@
 # Release Notes
 
-## XMLUnit for Java 2.6.5 - /not released, yet/
+## XMLUnit for Java 2.7.0 - /not released, yet/
+
+This version contains a backwards incompatible change to the
+`PlaceholderHandler` interface that is part of the experimental
+placeholders module: The `evaluate` method now receives a variable
+number of string arguments in addition to the textual content of the
+element/attribute. This allows placeholders like
+`${xmlunit.matchesRegex("some\s*regex")}`.
 
 * the AssertJ tests now pass on non-English locales as well
   Issue [#180](https://github.com/xmlunit/xmlunit/pull/180)
@@ -9,6 +16,10 @@
   caused xmlunit-assertj to be incompatible with AssertJ 3.15.0
   Issue [#181](https://github.com/xmlunit/xmlunit/issues/181)
 
+* added a `matchesRegex` placeholder
+  PR [#178](https://github.com/xmlunit/xmlunit/issues/178) by
+  [@Jazzyekim](https://github.com/Jazzyekim).
+
 ## XMLUnit for Java 2.6.4 - /Released 2020-03-08/
 
 * the dependencies on JAXB implementation and its transitive

pom.xml

@@ -18,7 +18,7 @@
   <groupId>org.xmlunit</groupId>
   <artifactId>xmlunit-parent</artifactId>
   <packaging>pom</packaging>
-  <version>2.6.5-SNAPSHOT</version>
+  <version>2.7.0-SNAPSHOT</version>
   <name>org.xmlunit:xmlunit-parent</name>
   <description>Parent POM for all artifacts of XMLUnit</description>
   <url>https://www.xmlunit.org/</url>

xmlunit-assertj/pom.xml

@@ -18,7 +18,7 @@
   <parent>
     <artifactId>xmlunit-parent</artifactId>
     <groupId>org.xmlunit</groupId>
-    <version>2.6.5-SNAPSHOT</version>
+    <version>2.7.0-SNAPSHOT</version>
   </parent>
   <modelVersion>4.0.0</modelVersion>
 

xmlunit-core/pom.xml

@@ -18,7 +18,7 @@
   <parent>
     <groupId>org.xmlunit</groupId>
     <artifactId>xmlunit-parent</artifactId>
-    <version>2.6.5-SNAPSHOT</version>
+    <version>2.7.0-SNAPSHOT</version>
   </parent>
 
   <groupId>org.xmlunit</groupId>

xmlunit-legacy/pom.xml

@@ -18,7 +18,7 @@
   <parent>
     <groupId>org.xmlunit</groupId>
     <artifactId>xmlunit-parent</artifactId>
-    <version>2.6.5-SNAPSHOT</version>
+    <version>2.7.0-SNAPSHOT</version>
   </parent>
 
   <groupId>org.xmlunit</groupId>

xmlunit-matchers/pom.xml

@@ -18,7 +18,7 @@
   <parent>
     <groupId>org.xmlunit</groupId>
     <artifactId>xmlunit-parent</artifactId>
-    <version>2.6.5-SNAPSHOT</version>
+    <version>2.7.0-SNAPSHOT</version>
   </parent>
 
   <groupId>org.xmlunit</groupId>

xmlunit-placeholders/pom.xml

@@ -18,7 +18,7 @@
     <parent>
         <artifactId>xmlunit-parent</artifactId>
         <groupId>org.xmlunit</groupId>
-        <version>2.6.5-SNAPSHOT</version>
+        <version>2.7.0-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 

xmlunit-placeholders/src/main/java/org/xmlunit/placeholder/MatchesRegexPlaceholderHandler.java

@@ -1,3 +1,16 @@
+/*
+  This file is licensed to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
 package org.xmlunit.placeholder;
 
 import org.xmlunit.XMLUnitException;
@@ -12,6 +25,8 @@
 
 /**
  * Handler for the {@code matchesRegex()} placeholder keyword.
+ *
+ * @since 2.7.0
  */
 public class MatchesRegexPlaceholderHandler implements PlaceholderHandler {
     private static final String PLACEHOLDER_NAME = "matchesRegex";
@@ -25,7 +40,7 @@ public String getKeyword() {
     public ComparisonResult evaluate(String testText, String... param) {
         if (param.length > 0 && param[0] != null && !param[0].equals("")) {
             try {
-                Pattern pattern = Pattern.compile(param[0].trim());
+                final Pattern pattern = Pattern.compile(param[0].trim());
                 if (testText != null && evaluate(testText.trim(), pattern)) {
                     return EQUAL;
                 }
@@ -36,8 +51,7 @@ public ComparisonResult evaluate(String testText, String... param) {
         return DIFFERENT;
     }
 
-    private boolean evaluate(String testText, Pattern pattern) {
-        Matcher matcher = pattern.matcher(testText);
-        return matcher.find();
+    private boolean evaluate(final String testText, final Pattern pattern) {
+        return pattern.matcher(testText).find();
     }
 }

xmlunit-placeholders/src/main/java/org/xmlunit/placeholder/PlaceholderHandler.java

@@ -25,16 +25,22 @@
  * <p>Implementations are expected to be thread-safe, the {@link
  * #evaluate} method may be invoked by multiple threads in
  * parallel.</p>
- * @since 2.6.0
+ * @since 2.7.0
  */
 public interface PlaceholderHandler {
     /**
      * The placeholder keyword this handler is responsible for.
      */
     String getKeyword();
+
     /**
      * Evaluate the test value when control contained the placeholder
      * handled by this class.
+     *
+     * @param testText the textual content of the element or attribute
+     * this placeholder has been added to.
+     * @param placeholderParameters any arguments provided to the
+     * placeholder.
      */
     ComparisonResult evaluate(String testText, String... placeholderParameters);
 }