Skip to content

Latest commit

 

History

History
162 lines (118 loc) · 7.25 KB

README.adoc

File metadata and controls

162 lines (118 loc) · 7.25 KB

Jamal Maven Plugin

Jamal maven plugin is a Maven plugin that executes Jamal for several files in the project directory and creates output files processing the Jamal macros.

You can use the plugin configured into a project or independent of the project.

Starting from the command line

You can use the plugin even without any Maven project, just executing the command line

mvn com.javax0.jamal:jamal-maven-plugin:2.8.3-SNAPSHOT:jamal

You can also leave the version out, and the plugin will use the latest version. You can add the lines

	<pluginGroups>
		<pluginGroup>com.javax0.jamal</pluginGroup>
	</pluginGroups>

to your ~/.m2/settings.xml maven configuration file. After that, you can invoke the plugin typing

mvn jamal:jamal

The plugin will process all files having the extension .jam except pom.jam and extensions.jam files. Converting these files, the output file will be named using the same name, chopping off the extension .jam.

The macro opening string will be {%, and the macro closing string will be `%}.

Note
 It is only a convention in Jamal, and Jamal itself does not have any default value. The plugin sets these default values. Jamal will create the processed files in the same directory where the source file is with the .jam extension chopped off.

Using the plugin in a Maven project

If you have an actual Maven project, then you can configure the plugin in the pom.xml.

<plugin>
    <groupId>com.javax0.jamal</groupId>
    <artifactId>jamal-maven-plugin</artifactId>
    <version>2.8.3-SNAPSHOT</version>
    <executions>
        <execution>
            <goals>
                <goal>jamal</goal>
            </goals>
        </execution>
        <configuration>
            <source>${basedir}/</source>
            <include>.*\.jam$</include>
            <exclude>.*(?:pom|extensions)\.jam$</exclude>
            <transform>/\.jam$//</transform>
            <open>{%</open>
            <close>%}</close>
            <pass>false</pass>
        </configuration>
    </executions>
</plugin>

The execution section is mandatory. If you know any way to make it optional, please let me know. The default phase is generate-sources, which means it runs before the compilation of the sources.

The configuration has decent default values. You can safely ignore the configuration parameters if you are happy with the defaults. The above sample uses the default values.

The configuration values are the following:

  • source is where the jamal source files are. The processing will search this and all subdirectories for files to process. The default value is the project base directory.

  • include can define a regular expression that matches the file names to be processed. The default value is \.jam$, which means that the files with the extension .jam are processed only. If this configuration value is empty, all files are processed, not excluded by the regular expression defined in the exclude configuration parameter.

  • exclude can define a regular expression to exclude certain files from the processing. Any file with a name that matches the regular expression will be excluded from the processing. The default value is an empty string which also means that no file is excluded from the processing.

  • transform can define a regular-expression based transformation. The format is usually /from/to/. from is a regular expression possibly including groups. to is a string that can contain references to the groups in the from regular expression. When calculating the output file name, these two strings are used as arguments to the Java String replaceAll() method. The default value is /\.jam$// which means that the .jam extension is removed from the file name. It is a convention to use the / character as the delimiter of the regular expression. You can use any character that does not appear inside the from and to strings. However, this character bast be the first character, the last character, and it is also used to separate the two strings.

  • open can define the macro opening string. The default value is the conventional {%.

  • close can define the macro closing string. The default value is the conventional %}.

  • pass can be true or false. The default value is false meaning that any Jamal error will stop the compilation. Setting this value to true will make the plugin to ignore any error and continue the processing.

Each of these construction values can also be set on the command line as a property. The command line property name is the same as the configuration parameter name with a jamal. prefix.

For example, you can ignore the errors temporarily using the command line

mvn jamal:jamal -Djamal.pass=true
Note
 The plugin functionality greatly changed from version 1.x.x to version 2.x.x. The reason for this is that the purpose of the plugin greatly changed. The version 1.x.x was a plugin that was used to process the pom.xml file. In the versions 2.x.x the plugin is more used as a general purpose Jamal processor. The envisioned use is to process documentation and code generating Jamal files. In versions 2.x.x pom.xml.jam files are deprecated and followed by pom.jam files directly processed by the Jamal Maven extension.

Jamalizing a Java Project

The Jamal Maven plugin can be used to modify a Java Maven project to use Jamal. The modification does not alter any existing file, it only adds new files.

To star the jamalization of a project, you can use the command line

mvn jamal:jamalize

or

mvn com.javax0.jamal:jamal-maven-plugin:2.8.3-SNAPSHOT:jamalize

Jamalization will use the version of Jamal executing it. If this version is a -SNAPSHOT version the process will not be able to download the Asciidoctor extension. Only the released versions are available in the Maven repository.

To override the version of Jamal used for the jamalization, you can use the command line

mvn jamal:jamalize -Djamal.version=needed-version

Jamalization is available since 2.1.0, but it is capable of installing any earlier released version.

The new files jamalization creates are:

  • every pom.xml file is copied to pom.xml.jam. Since Jamal is non-intrusive, the original content processed with Jamal will result in the same XML. After this initial state the new pom.jam file can gradually be modified. The size of the pom.jam is usually 20% to 30% of the original pom.xml file.

  • a new .mvn/extensions.xml file is created in the current directory. The content of this extension will instruct Maven to use the Jamal Maven extension.

  • a new .asciidoctor/lib directory is created in the current directory. The process also downloads the

    https://repo.maven.apache.org/maven2/com/javax0/jamal/jamal-asciidoc/{VERSION}/jamal-asciidoc-{VERSION}-jamal-asciidoc-distribution.zip

    file and unzips it into the .asciidoctor/lib directory. The {VERSION} is the version of Jamal used for the jamalization or the one defined in the system variable jamal.version. This way, the Jamal preprocessor extension is available for the IntelliJ IDEA AsciiDoc plugin. You also have to remember to configure IntelliJ to handle .jam files as AsciiDoc files and restart it. For more information, please read the documentation of the Jamal AsciiDoc extension.