asciidoc/use/listmodules.adoc

////
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   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

     https://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.
////

[*__since 1.4__*]

Finds the list of modules in the repository matching some criteria and sets a corresponding list of properties in Ant.

The criteria is set by given patterns matching the organisation, name branch and revision of the modules to find.

To know if a module matches the criteria, Ivy will use the configured link:../concept{outfilesuffix}#matcher[pattern matcher].

== Attributes

[options="header",cols="15%,50%,35%"]
|=======
|Attribute|Description|Required
|organisation|the pattern matching the organisation of the modules to list|Yes
|module|the pattern matching the name of the modules to list|Yes
|branch|the pattern matching the branch of the modules to list|No, defaults to `*`
|revision|the pattern matching the revision of the modules to list|Yes
|matcher|the name of the pattern matcher to use for matching the modules fields|No. Defaults to `exactOrRegexp`.
|property|the pattern of the property to set when a module is found|Yes
|value|The pattern of the value to set when a module is found|Yes
|settingsRef|A reference to Ivy settings that must be used by this task (*__since 2.0__*)|No, defaults to `ivy.instance`.
|resolver|The name of the resolver to use for searching the modules (*__since 2.2__*)|No, all available resolvers will be used by default.
|=======

== Examples

[source,xml]
----
<ivy:listmodules organisation="apache" module="ivy" revision="*" property="ivy.[revision]" value="found"/>
----

will find all revisions of the module ivy in the org apache, and create one property for each revision found, the name of the property depending on the revision, the value being always `found`

'''

[source,xml]
----
<ivy:listmodules organisation="*" module="ivy*" revision="1.0" matcher="glob" property="modules.[module]" value="[organisation]"/>
----

use the glob matcher to find all modules which name starts with ivy with revision 1.0, and sets for each a property with module name found  and organisation for value.

Example:
[source,properties]
----
modules.ivy=apache
modules.ivyde=apache
modules.ivytools=ivytools
----