- NEW: added built-in versionmatcher: 'Version Pattern Matcher' (IVY-871)
[ant-ivy.git] / doc / settings / version-matchers.html
index b2bed76..e31c8ca 100644 (file)
@@ -32,8 +32,6 @@ The child tag used for the version matcher must be equal to a name of a report o
 
 A version matcher is used to evaluate if a a dependency version contraint matches a dependency version.
 
-See <a href="../ivyfile/dependency.html">dependency</a> doc for details about built-in version matchers.
-
 <h1>Child elements</h1>
 <table class="ivy-children">
 <thead>
@@ -45,7 +43,86 @@ See <a href="../ivyfile/dependency.html">dependency</a> doc for details about bu
 </tbody>
 </table>
 
-       </textarea>
+<h1>Built-in Version Matchers</h1>
+<h2>Exact Revesion Matcher</h2>
+A matcher that matches a dependency revision id to the module revision id using simple string equality.
+
+<h2>Sub Revision Matcher</h2>
+A matcher that matches all revisions starting with a specific prefix. The syntax is: [prefix]+
+
+<table class="ivy-children">
+<thead>
+    <tr><th class="ivy-chld">Revision</th><th class="ivy-chld-desc">Matches</th></tr>
+</thead>
+<tbody>
+
+<tr><td>1.0.+</td><td>all revisions starting with '1.0.', like 1.0.1, 1.0.5, 1.0.a</td></tr>
+<tr><td>1.1+</td><td>all revisions starting with '1.1', like 1.1, 1.1.5, but also 1.10, 1.11</td></tr>
+</table>
+
+<h2>Latest (Status) Matcher</h2>
+
+A matcher that can matches versions based on their status. The predefined statuses in Ivy are 'release', 'milestone' and 'integration'. It's possible to define your own statuses, see [[settings/statuses]] for more detais.
+
+<table class="ivy-children">
+<thead>
+    <tr><th class="ivy-chld">Revision</th><th class="ivy-chld-desc">Matches</th></tr>
+</thead>
+<tbody>
+
+<tr><td>latest.integration</td><td>all versions</td></tr>
+<tr><td>latest.milestone</td><td>all modules having at least 'milestone' as status</td></tr>
+<tr><td>latest.release</td><td>all modules having at least 'release' as status</td></tr>
+<tr><td>latest.[any status]</td><td>all modules having at least the specified status</td></tr>
+</table>
+
+<h2>Version Range Matcher</h2>
+
+Range types are exhaustively listed by example in the table below.
+
+<table class="ivy-children">
+<thead>
+    <tr><th class="ivy-chld">Revision</th><th class="ivy-chld-desc">Matches</th></tr>
+</thead>
+<tbody>
+
+<tr><td> [1.0,2.0] </td><td> all versions greater or equal to 1.0 and lower or equal to 2.0</td></tr>
+
+<tr><td> [1.0,2.0[ </td><td> all versions greater or equal to 1.0 and lower than 2.0</td></tr>
+
+<tr><td> ]1.0,2.0] </td><td> all versions greater than 1.0 and lower or equal to 2.0<tr>
+
+<tr><td> ]1.0,2.0[ </td><td> all versions greater than 1.0 and lower than 2.0</td></tr>
+
+<tr><td> [1.0,) </td><td> all versions greater or equal to 1.0 </td></tr>
+
+<tr><td> ]1.0,) </td><td> all versions greater than 1.0</td></tr>
+
+<tr><td> (,2.0] </td><td> all versions lower or equal to 2.0</td></tr>
+
+<tr><td> (,2.0[ </td><td> all versions lower than 2.0 </td></tr>
+
+</tbody>
+</table>
+
+<h2>Version Pattern Matcher</h2>
+
+The version pattern matcher allows for more flexibility in pattern matching at the cost of adding a matcher declaration in Ivy settings.  A simple example is given below.
+
+<h3>Settings.xml</h3>
+<code type="xml">
+<pattern-vm>
+  <match revision="foo" pattern="${major}\.${minor}\.\d+" args="major, minor" matcher="regexp" />
+</pattern-vm>
+</code>
+
+<h3>Ivy.xml</h3>
+<code type="xml">
+<dependency org="acme" name="tool" rev="foo(1, 3)" />
+</code>
+
+The version pattern matcher may contain more than one match element.  The matcher will attempt to match a dependency revision against each match in sequence, checking the revision tag (e.g. foo(..)) and then the pattern.
+Matcher types may be one of "regexp", "exact", "glob", or "exactOrRegexp".  Glob pattern matching requires Apache ORO 2.0.8 or higher to be on the classpath.</textarea>
 <script type="text/javascript">xooki.postProcess();</script>
 </body>
 </html>