add doc for <matches>

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@449826 13f79535-47bb-0310-9956-ffa450edef68

docs/manual/CoreTasks/conditions.html

@@ -311,10 +311,10 @@ that is "true","yes", or "on"</p>
     <td valign="top" align="center">Yes</td>
   </tr>
 </table>
-<pre>
-    &lt;istrue value=&quot;${someproperty}&quot;/&gt;
-    &lt;istrue value=&quot;false&quot;/&gt;
-</pre>
+<blockquote><pre>
+&lt;istrue value=&quot;${someproperty}&quot;/&gt;
+&lt;istrue value=&quot;false&quot;/&gt;
+</pre></blockquote>
 
 <h4>isfalse</h4>
 <p>Tests whether a string is not true, the negation of &lt;istrue&gt;
@@ -331,10 +331,10 @@ that is "true","yes", or "on"</p>
     <td valign="top" align="center">Yes</td>
   </tr>
 </table>
-<pre>
-    &lt;isfalse value=&quot;${someproperty}&quot;/&gt;
-    &lt;isfalse value=&quot;false&quot;/&gt;
-</pre>
+<blockquote><pre>
+&lt;isfalse value=&quot;${someproperty}&quot;/&gt;
+&lt;isfalse value=&quot;false&quot;/&gt;
+</pre></blockquote>
 
 <h4>isreference</h4>
 
@@ -424,12 +424,11 @@ that is "true","yes", or "on"</p>
   <p>
     Example usage:
   </p>
-  <blockquote>
-  <pre>
-    &lt;isfileselected file="a.xml"&gt;
-      &lt;date datetime="06/28/2000 2:02 pm" when="equal"/&gt;
-    &lt;/isfileselected&gt;
-  </pre></blockquote>
+<blockquote><pre>
+&lt;isfileselected file="a.xml"&gt;
+  &lt;date datetime="06/28/2000 2:02 pm" when="equal"/&gt;
+&lt;/isfileselected&gt;
+</pre></blockquote>
 <h4>typefound</h4>
 
 <p>Test whether a given type is defined, and that
@@ -461,11 +460,10 @@ tasks, datatypes, scriptdefs, macrodefs and presetdefs.</p>
   <p>
     Example usages:
   </p>
-  <blockquote>
-  <pre>
-    &lt;typefound name="junit"/&gt;
-    &lt;typefound uri="antlib:org.apache.maven.artifact.ant" name="artifact"/&gt;
-  </pre></blockquote>
+<blockquote><pre>
+&lt;typefound name="junit"/&gt;
+&lt;typefound uri="antlib:org.apache.maven.artifact.ant" name="artifact"/&gt;
+</pre></blockquote>
 
 <h4>scriptcondition</h4>
 
@@ -510,12 +508,12 @@ self</code> bean, which refers back to the condition itself. The
 <p>
 Example:
 </p>
-<pre>
-    &lt;scriptcondition language=&quot;javascript&quot;
-            value=&quot;true&quot;&gt;
-        self.setValue(false);
-    &lt;/scriptcondition&gt;
-</pre>
+<blockquote><pre>
+&lt;scriptcondition language=&quot;javascript&quot;
+        value=&quot;true&quot;&gt;
+    self.setValue(false);
+&lt;/scriptcondition&gt;
+</pre></blockquote>
 
 Sets the default value of the condition to true, then in the script, 
 sets the value to false. This condition always evaluates to "false"
@@ -551,27 +549,26 @@ attempting to set the appropriate property/feature/</p>
   </tr>
 </table>
 
-<pre>
+<blockquote><pre>
 &lt;parsersupports feature="http://xml.org/sax/features/namespaces"/&gt;
-</pre>
+</pre></blockquote>
 Check for namespace support. All SAX2 parsers should have this.
-<pre>
+<blockquote><pre>
 &lt;or&gt;
   &lt;parsersupports
     feature="http://apache.org/xml/features/validation/schema"/&gt;
   &lt;parsersupports
     feature="http://java.sun.com/xml/jaxp/properties/schemaSource"/&gt;
 &lt;/or&gt;
-</pre>
+</pre></blockquote>
 
 Check for XML Schema support.
 
-<pre>
-
+<blockquote><pre>
 &lt;parsersupports
   property="http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation"
   value="document.xsd"/&gt;
-</pre>
+</pre></blockquote>
 
 Check for Xerces-specific definition of the location of the no namespace schema.
 
@@ -628,21 +625,21 @@ This condition was added in Apache Ant 1.7.</p>
   </tr>
 </table>
 
-<pre>
+<blockquote><pre>
 &lt;condition property="offline"&gt;
   &lt;isreachable url="http://ibiblio.org/maven/" /&gt;
 &lt;/condition&gt;
-</pre>
+</pre></blockquote>
 
 <p>
 Probe for the maven repository being reachable.
 </p>
 
-<pre>
+<blockquote><pre>
 &lt;condition property="offline"&gt;
   &lt;isreachable host="ibiblio.org" timeout="10" /&gt;
 &lt;/condition&gt;
-</pre>
+</pre></blockquote>
 
 <p>
 Probe for the maven repository being reachable using the hostname, ten second timeout..
@@ -654,14 +651,14 @@ Probe for the maven repository being reachable using the hostname, ten second ti
   <b>Since Ant 1.6.3</b>
 </p>
 
-<pre>
-&lt;length string=&quot; foo &quot; trim="true" length=&quot;3&quot; /&gt;
-</pre>
+<blockquote><pre>
+&lt;length string=" foo " trim="true" length="3" /&gt;
+</pre></blockquote>
 <p>Verify a string is of a certain length.</p>
 
-<pre>
+<blockquote><pre>
 &lt;length file=&quot;foo&quot; when=&quot;greater&quot; length=&quot;0&quot; /&gt;
-</pre>
+</pre></blockquote>
 <p>Verify that file <i>foo</i> is not empty.</p>
 
 <h4>isfailure</h4>
@@ -690,9 +687,9 @@ Probe for the maven repository being reachable using the hostname, ten second ti
   <b>Since Ant 1.7</b>
 </p>
 
-<pre>
+<blockquote><pre>
 &lt;resourcecount refid=&quot;myresourcecollection&quot; when=&quot;greater&quot; length=&quot;0&quot; /&gt;
-</pre>
+</pre></blockquote>
 <p>Verify that a resource collection is not empty.</p>
 
 <h4>resourcesmatch</h4>
@@ -773,14 +770,116 @@ must match. <b>Since Ant 1.7</b>
     There is also a nested &lt;classpath&gt; element, which can be used to specify 
     a classpath.
 </p>
-<pre>
-    &lt;hasmethod classname="java.util.ArrayList" method="trimToSize"  /&gt;
-</pre>
+<blockquote><pre>
+&lt;hasmethod classname="java.util.ArrayList" method="trimToSize"  /&gt;
+</pre></blockquote>
 
 <p>Looks for the method trimToSize in the ArrayList class.</p>
 
+<h4>matches</h4>
 
+<p>
+  Test if the specified string matches the specified regular
+  expression pattern.
+  <b>Since Ant 1.7</b></p>
 
+<table border="1" cellpadding="2" cellspacing="0">
+  <tr>
+    <td valign="top"><b>Attribute</b></td>
+    <td valign="top"><b>Description</b></td>
+    <td align="center" valign="top"><b>Required</b></td>
+  </tr>
+  <tr>
+    <td valign="top">string</td>
+    <td valign="top">The string to test.</td>
+    <td valign="top" align="center">Yes</td>
+  </tr>
+  <tr>
+    <td valign="top">match</td>
+    <td valign="top">The regular expression pattern used to test.</td>
+    <td valign="top" align="center">Yes, unless there is a nested
+      <code>&lt;regexp&gt;</code> element.</td>
+  </tr>
+  <tr>
+    <td valign="top">casesensitive</td>
+    <td valign="top">Perform a case sensitive match.  Default is
+        true.</td>
+    <td valign="top" align="center">No</td>
+  </tr>
+  <tr>
+    <td valign="top">multiline</td>
+    <td valign="top">
+      Perform a multi line match.
+      Default is false.</td>
+    <td valign="top" align="center">No</td>
+  </tr>
+  <tr>
+    <td valign="top">singleline</td>
+    <td valign="top">
+      This allows '.' to match new lines.
+      SingleLine is not to be confused with multiline, SingleLine is a perl
+      regex term, it corresponds to dotall in java regex.
+      Default is false.</td>
+    <td valign="top" align="center">No</td>
+  </tr>
+</table>
 
+  <p>
+    There is also an optional &lt;regexp&gt; element, which can be used to specify
+    a regular expression instead of the "pattern" attribute.
+    See <a href="../CoreTypes/regexp.html">Regexp Type</a> for the description
+    of the nested element regexp and of
+    the choice of regular expression implementation.
+  </p>
+  <p>
+    An example:
+  </p>
+<blockquote><pre>
+&lt;condition propery="legal-password"&gt;
+  &lt;matches pattern="[1-9]" string="${user-input}"/&gt;
+&lt;/condition&gt;
+&lt;fail message="Your password should at least contain one number"
+      unless="legal-password"/&gt;
+</pre></blockquote>
+  <p>
+    The following example sets the property "ok" if
+    the property "input" is three characters long, starting
+    with 'a' and ending with 'b'.
+  </p>
+<blockquote><pre>
+&lt;condition property="ok"&gt;
+  &lt;matches string="${input}" pattern="^a.b$"/&gt;
+&lt;/condition&gt;
+</pre></blockquote>
+  <p>
+    The following defines a reference regular expression for
+    matching dates and then uses antunit to check if the
+    property "today" is in the correct format:
+  </p>
+<blockquote><pre>
+&lt;regexp id="date.pattern" pattern="^[0123]\d-[01]\d-[12]\d\d\d$"/&gt;
+
+&lt;au:assertTrue xmlns:au="antlib:org.apache.ant.antunit"&gt;
+  &lt;matches string="${today}"&gt;
+    &lt;regexp refid="date.pattern"/&gt;
+  &lt;/matches&gt;
+&lt;/au:assertTrue&gt;
+</pre></blockquote>
+  <p>
+    The following example shows the use of the singleline and the casesensitive
+    flags.
+  </p>
+<blockquote><pre>
+&lt;au:assertTrue&gt;
+  &lt;matches string="AB${line.separator}C" pattern="^ab.*C$"
+           casesensitive="false"
+           singleline="true"/&gt;
+&lt;/au:assertTrue&gt;
+&lt;au:assertFalse&gt;
+  &lt;matches string="AB${line.separator}C" pattern="^ab.*C$"
+           casesensitive="false"
+           singleline="false"/&gt;
+&lt;/au:assertFalse&gt;
+</pre></blockquote>
 </body>
 </html>