////
   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

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

[*__since 1.4__*]

The `info` task eases the access to some essential data contained in an Ivy file without performing a dependency resolution.

The information is retrieved by setting Ant properties:

[options="header",cols="30%,50%"]
|=======
|Property|Description
|ivy.organisation|The organisation of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
|ivy.module|The name of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
|ivy.branch|The branch of the module if any, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
|ivy.revision|The revision of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
|ivy.status|The status of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed.
|ivy.publication|The publication time of the module, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed. (*__since 2.2__*)
|ivy.extra.__[any extra attribute]__|Corresponding extra attribute value, as found in the link:../ivyfile/info{outfilesuffix}[info] tag of the Ivy file parsed
|ivy.configurations|A comma separated list of configurations of the module, as declared in the link:../ivyfile/configurations{outfilesuffix}[configurations] section
|ivy.public.configurations|A comma separated list of public configurations of the module, as declared in the link:../ivyfile/configurations{outfilesuffix}[configurations] section
|ivy.configuration.__[config name]__.desc|For each configuration with a description, a property is created containing this description. (*__since 2.2__*)
|ivy.artifact.__[index]__.name|For each published artifact, a property is created containing its name. (*__since 2.2__*)
|ivy.artifact.__[index]__.type|For each published artifact, a property is created containing its type. (*__since 2.2__*)
|ivy.artifact.__[index]__.ext|For each published artifact, a property is created containing its ext. (*__since 2.2__*)
|ivy.artifact.__[index]__.conf|For each published artifact, a property is created containing its conf. (*__since 2.2__*)
|ivy.artifact.__[index]__.extra.__[any extra attribute]__|For each extra attribute of the published artifact, a property is created containing its name. (*__since 2.2__*)
|=======

[*__since 2.0__*]

This task has been enhanced to allow you to retrieve information about Ivy modules in a repository.  Instead of specifying a local Ivy file you may specify the organisation, module, revision pattern and (optionally) the branch of the Ivy module in the repository you wish to retrieve the information for.

The revision pattern is what is used when declaring a link:../ivyfile/dependency{outfilesuffix}[dependency] on a module, identical to how the link:findrevision{outfilesuffix}[findrevision] task works.  In fact, this task can now be used in place of the findrevision task.

If no matching module is found then no property values are set.

You may now also set the property attribute to change the first part of the property names that are set by this task e.g. if you set the property attribute to `mymodule` this task will set the Ant properties `mymodule.organisation`, `mymodule.module`, `mymodule.revision` etc.

(*__since 2.2__*) This task has been enhanced to also retrieve detailed information about the module's published artifacts, as well as the publication time.

== Attributes

[options="header",cols="15%,50%,35%"]
|=======
|Attribute|Description|Required
|file|the Ivy file to parse|Yes, if you wish to parse an Ivy file.
No, if you are retrieving information about a module from an Ivy repository.
|organisation|the organisation of the module to find (*__since 2.0__*)|No, if you wish to parse an Ivy file.
Yes, if you are retrieving information about a module from an Ivy repository.
|module|the the name of the module to find (*__since 2.0__*)|No, if you wish to parse an Ivy file.
Yes, if you are retrieving information about a module from an Ivy repository.
|branch|the branch of the module to find (*__since 2.0__*)|No, defaults to the default branch for the given module if you are retrieving information about a module from an Ivy repository.
|revision|the revision constraint to apply (*__since 2.0__*)|No, if you wish to parse an Ivy file.
Yes, if you are retrieving information about a module from an Ivy repository.
|property|the name to use as the base of the property names set by this task (*__since 2.0__*)|No, will default to `ivy` if not set.
|settingsRef|A reference to Ivy settings that must be used by this task (*__since 2.0__*)|No, defaults to `ivy.instance`.
|=======

== Examples

Given this `ivy.xml` file:

[source,xml]
----
<ivy-module version="1.0" xmlns:e="http://ant.apache.org/ivy/extra">
    <info organisation="apache"
          module="info-all"
          branch="trunk"
          revision="1.0"
          status="release"
          e:myextraatt="myvalue"/>
    <configurations>
        <conf name="default"/>
        <conf name="test"/>
        <conf name="private" visibility="private"/>
    </configurations>
    <publications>
        <artifact name="thing1" type="jar" ext="jar" conf="default" e:data="main"/>
        <artifact name="thing2" type="jar" ext="jar" conf="default" e:data="client"/>
    </publications>
    <dependencies>
        <dependency org="org1" name="mod1.2" rev="2.0"/>
    </dependencies>
</ivy-module>
----

[source,xml]
----
<ivy:info file="${basedir}/path/to/ivy.xml"/>
----

Parses `+++${basedir}/path/to/ivy.xml+++` and set properties as described above accordingly:

[source,properties]
----
ivy.organisation=apache
ivy.module=info-all
ivy.branch=trunk
ivy.revision=1.0
ivy.status=release
ivy.extra.myextraatt=myvalue
ivy.configurations=default, test, private
ivy.public.configurations=default, test
ivy.artifact.1.name=thing1
ivy.artifact.1.type=jar
ivy.artifact.1.ext=jar
ivy.artifact.1.conf=default
ivy.artifact.1.extra.data=main
ivy.artifact.2.name=thing2
ivy.artifact.2.type=jar
ivy.artifact.2.ext=jar
ivy.artifact.2.conf=default
ivy.artifact.2.extra.data=client
----

Given the same Ivy module in a repository:

[source,xml]
----
<ivy:info organisation="apache" module="info-all" revision="1.0"/>
----

will set the exact same set of properties as above.  Using:

[source,xml]
----
<ivy:info organisation="apache" module="info-all" revision="1.0" property="infotest"/>
----

will set:

[source,properties]
----
infotest.organisation=apache
infotest.module=info-all
infotest.branch=trunk
infotest.revision=1.0
infotest.status=release
infotest.extra.myextraatt=myvalue
infotest.configurations=default, test, private
infotest.public.configurations=default, test
infotest.artifact.1.name=thing1
infotest.artifact.1.type=jar
infotest.artifact.1.ext=jar
infotest.artifact.1.conf=default
infotest.artifact.1.extra.data=main
infotest.artifact.2.name=thing2
infotest.artifact.2.type=jar
infotest.artifact.2.ext=jar
infotest.artifact.2.conf=default
infotest.artifact.2.extra.data=client
----
