This file defines the macros that can be used to set up a pom.xml.jam file.

This is a file imported and everything that is not a macro, like this text, will be discarded by Jamal, thus it is
essentially comment.

When this file is imported the macro start and end strings should be the characters U+007B and U+007D as you can see in
the code below.

In the comment parts the examples are using the [ and the ] characters as macro start and macro end strings.

To import this file the pom.xml.jam file should use the macro

   [@import ../pom.jim]

and this file as a resource should be available on the class path.

------------------------------------------------------------------------------------------------------------------------

The macros can handle optional parameters, like GAV that stands for GroupId, ArtifactId Version, but it also can handle
scope optionally. Therefore the use of these macros is lenient.

{@options lenient}

------------------------------------------------------------------------------------------------------------------------
You start a project definition with the name and at the end of the file there is an [end project].

{@define project($name)=
  <project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
                 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
      <modelVersion>4.0.0</modelVersion>
      <name>$name</name>}

------------------------------------------------------------------------------------------------------------------------

Tags that contain a lot of elements inside are supported by macros that start only the tag. These tags have to be closed
with an [end tag] element. For example

[project name]

  the whole content of the jamalified pom file

[end project]

{@define end($x)=</$x>}

------------------------------------------------------------------------------------------------------------------------

The tags listed below in the for loop can be used in two different ways. Either as

    [tag
          some
          content
          here
    ]

or as

   [tag]
          some
          content
          here
   [end tag]

if there is a lot of content and it is more readable to have an end tag. If you want to have a <tag></tag> with no
content then you just write <tag></tag> or <tag/>. There is no need for a macro if it makes nothing better.

{@define $forsep=\s*,\s*} this lets us to split the list of the tags into multiple lines

Define all the macros that are to be used as XML tags. After that instead of writing

                   <long_tag_nam>some long content</long_tag_name>

you write [long_tag_nam some long content] (where [ and ] are the actual macro brackets).

Because the macro "eval" is preceded with the character # first the macro "for" is evaluated
the result (output) of the macro "for" is a series of "define" macros. Each defines a new macro
with the name of the tag. When this is ready then this output is processed by the macro "eval"
essentially executing the "define" macros and at this point the tags are defined as macros.

{!@for $tag in (annotationProcessor,
                annotationProcessorPath,
                annotationProcessorPaths,
                annotationProcessors,
                arg,
                argLine,
                artifactId,
                build,
                compilerArgs,
                configuration,
                connection,
                dependencies,
                dependencyManagement,
                description,
                developerConnection,
                directory,
                distributionManagement,
                encoding,
                exclude,
                excludes,
                execution,
                executions,
                extensions,
                filtering,
                goal,
                goals,
                groupId,
                id,
                name,
                packaging,
                phase,
                plugin,
                pluginManagement,
                plugins,
                profile,
                profiles,
                properties,
                quiet,
                release,
                repositories,
                resource,
                resources,
                scm,
                scope,
                type,
                show,
                source,
                target,
                url,
                version)=
{@define $tag($x)=<$tag>{#if |$x|$x</$tag>}}}


detectJavaApiLink has 'true' or 'false' as argument that way it cannot be tested in IF

{@define detectJavaApiLink($x)=<detectJavaApiLink>$x</detectJavaApiLink>}
{@define detectOfflineLinks($x)=<detectOfflineLinks>$x</detectOfflineLinks>}

------------------------------------------------------------------------------------------------------------------------
{@define profile($id,$content)=<profile><id>$id</id>content</profile>}
{@define snapshotRepository($id,$url)=<snapshotRepository><id>$id</id><url>$url</url></snapshotRepository>}
{@define repository($id,$url)=<repository><id>$id</id><url>$url</url></repository>}
{@define profile($id)=<profile><id>$id</id>} end a profile with an [end profile]

------------------------------------------------------------------------------------------------------------------------

The GAV macro can be used to define groupId, artifactId and version tags for the project. Each of the elements may be
missing, it is checked by the macro definitions using the 'if' macro. It is recommended to use : as argument separators
for this macro in the pom.xml.jam

The macro also defines the user defined macros GROUP_ID, ARTIFACT_ID and VERSION_ID that is used by other macros, like
parent, when the group id, artifact id or version is not defined. Usually the parent has the same groupId and version
as a subproject.

To skip the groupId, for example, you can write [GAV ::artifa-ct:1.0.0]

{@define GAV($groupId,$artifactId,$version)=
    {#if|$groupId|{groupId $groupId}}{@define GROUP_ID=$groupId}
    {#if|$artifactId|{artifactId $artifactId}}{@define ARTIFACT_ID=$artifactId}
    {#if|$version|{version $version}}{@define VERSION_ID=$version}
}

------------------------------------------------------------------------------------------------------------------------

{@define parent($groupId,$artifactId,$version)=<parent>
    {groupId {#if|$groupId|$groupId|{GROUP_ID}}}
    {artifactId {#if|$artifactId|$artifactId|{ARTIFACT_ID}}}
    {version {#if|$version|$version|{VERSION_ID}}}
</parent>}

------------------------------------------------------------------------------------------------------------------------

Define a dependency. The arguments are the ... you see. Each of the arguments are
optional. If one is missing there will be no corresponding XML tag generated.

{@define dependency($groupId,$artifactId,$version,$scope,$type)=
<dependency>
    {#if|$groupId|{groupId $groupId}}
    {#if|$artifactId|{artifactId $artifactId}}
    {#if|$version|{version $version}}
    {#if|$scope|{scope $scope}}
    {#if|$type|{type $type}}
</dependency>
}

------------------------------------------------------------------------------------------------------------------------

Use this marco to define the modules in a multi module project parent pom.xml.jam. Simply list the names of the modules
comma separated, like [modules module1,module2,module3]

{@define modules($Z)=<modules>{@for $M in ($Z)=<module>$M</module>}</modules>}

------------------------------------------------------------------------------------------------------------------------

Define a license type with the name and the URL. There is no support in this macro package to specify multiple licenses.

{@define license($name,$url)=<licenses><license><name>$name</name><url>$url</url></license></licenses>}

------------------------------------------------------------------------------------------------------------------------

------------------------------------------------------------------------------------------------------------------------

Use this macro to define that the source encoding is whatever it is. Usually UTF8. If there is no argument to the macro
then the encoding will be UTF-8.

NOTE that this

{@define sourceEncoding($x)=
<properties>
    <project.build.sourceEncoding>{#if |$x|$x|UTF-8}</project.build.sourceEncoding>
</properties>}

{@define properties($x)={@define sourceEncoding($y)=<project.build.sourceEncoding>{#if |$y|$y|UTF-8}</project.build.sourceEncoding>}<properties>{#if|$x|
$x
</properties>}}


------------------------------------------------------------------------------------------------------------------------

Use this macro to define properties inside the <properties> ...</properties> tags (for which you should use the
[properties] macro. Use if this macro you can write

         property(name,value)

or just simply

         prop(name,value)

instead of

         <name>value</name>


{@define property($name,$value)=<$name>$value</$name>}
{@define prop($name,$value)=<$name>$value</$name>}

------------------------------------------------------------------------------------------------------------------------

Use this macro to define a single developer. There is no need to specify the <developers></developers> tags or even to
use the [developers ...] macro. If you want to us specify more than one developer then use the

[developers]
   [developer ...]
   [developer ...]
[end developers]

construct. The use of the macro [developers] will overwrite the developer macro and after that it will not include the
enclosing <developers> and </developers> tags.

{@define developer($name,$email)=<developers>
    <developer>
        <name>$name</name>
        <email>$email</email>
    </developer>
</developers>}

{@define developers($y)=<developers>{@define developer($name,$email)=    <developer>
        <name>$name</name>
        <email>$email</email>
    </developer>}}

------------------------------------------------------------------------------------------------------------------------

Define the scm connections when you project is on github. All you have to specify is the developer github name and the
project github id.

{@define github($developer,$project)=
    {scm|
        {connection  scm:git:git://github.com/$developer/$project.git}
        {developerConnection scm:git:ssh://github.com/$developer/$project.git}
        {url https:/github.com/$developer/$project/tree/master}
    }
    {url https:/github.com/$developer/$project/tree/master}
}

------------------------------------------------------------------------------------------------------------------------

Defines an --add-opens and --add-exports options to the compiler. This may be needed when you use modules and the tests
need reflective access. If you define the user defined macros MODULE_PREFIX and PACKAGE_PREFIX they will be used in
fromt of the $module and $package parameters.

{@define opens($module,$package,$to)=--add-opens {?MODULE_PREFIX}$module/{?PACKAGE_PREFIX}$package={#if/$to/$to/ALL-UNNAMED}}
{@define exports($module,$package,$to)=--add-exports {?MODULE_PREFIX}$module/{?PACKAGE_PREFIX}$package={#if/$to/$to/ALL-UNNAMED}}

------------------------------------------------------------------------------------------------------------------------