The Most Powerful Multi-Pass Java Preprocessor
Clone or download
Latest commit 069fcf0 Jun 16, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.projectKnowledge started 6.1.5-SNAPSHOT Jun 16, 2018
assets updated readme and diagram Apr 29, 2018
src started 6.1.5-SNAPSHOT Jun 16, 2018
texts started 6.0.2-SNAPSHOT Dec 8, 2015
.gitignore updated plugin versions Sep 23, 2017
LICENSE added license text Feb 28, 2017
README.md updated readme Jun 16, 2018
changelog.txt maintenance release 6.1.4 Jun 16, 2018
logo.svg renamed xml functions and improving in unknown function detection Dec 8, 2014
pom.xml started 6.1.5-SNAPSHOT Jun 16, 2018

README.md

License Apache 2.0 Maven central Codacy Badge Java 6.0+ Maven 3.0+ Ant 1.8.2+ PayPal donation Yandex.Money donation

Changelog

  • 6.1.4 (16 jun 2018)

    • #19 removed dependencies to meta packages (their sources moved into project)
  • 6.1.3 (29 apr 2018)

    • added automatic module name igormaznitsa.jcp
    • CORE: added /U key to turn on mode to interpret unknown variables as FALSE (in Maven and ANT unknownVarAsFalse), #17
  • 6.1.2 (02 apr 2017)

    • CORE: added STR TRIMLINES(STR) function to trim lines represented as string and removing empty lines
    • CORE: added /A command line option (copyFileAttributes in Maven and ANT) to copy file attributes
    • CORE: added /ED: command line option to exclude sub-folders from preprocessing (excludedFolders in Maven and ANT) with ANT pattern support.
    • CORE: added /PI command line option (preserveIndent in Maven and ANT), turn on mode to preserve indent when removing //$ and //$$, thanks to jamuir
    • CORE: comma in split lines in BINFILE function moved from the start of line to the end of the previous line (to increase compatibility with Go)

Full changelog

Introduction

I guess it is most powerful preprocessor for Java because it is a multi-pass one and can work with XML files as data sources. The First version of the preprocessor was published in 2003 and it was very actively used for J2ME developments. Modern version can be used for any kind of Java project because it can be used with ANT, MAVEN and Gradle. Features Because JDK-9 has supported JEP-238, the preprocessor is useful to generate multi-version JARs, there is example of a maven project which generates JEP-238 JAR for two versions of JDK.

How to use

The Full list of the preprocessor directives can be found in the wiki.

The Preprocessor can be used by different ways:

  • as ANT task, and with Android SDK
  • as Maven plugin
  • with Gradle through ANT task
  • as Java framework with direct class calls
  • as external utility through CLI (command line interface) The Preprocessor is published in the Maven Central so that can be added in Maven projects without any problems
    <build>
        <plugins>
...
           <plugin>
                <groupId>com.igormaznitsa</groupId>
                <artifactId>jcp</artifactId>
                <version>6.1.4</version>
                <executions>
                    <execution>
                        <id>preprocessSources</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>preprocess</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>clearGeneratedFolders</id>
                        <goals>
                            <goal>clear</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
...
        </plugins>
    </build>    

How to use from command line

The Preprocessor jar can be started under Java as a console application. Let's take a look at short example below how to start in command line under Linux The Easy variant of usage:

java -jar jcp-6.1.4.jar  --i:./test --o:./result

The Example just preprocess files from ./test folder which extensions allowed to be preprocessed by default, and places result into ./result folder, but keep in your mind that the preprocessor copies not all files, XML files will not be preprocessed by default. Files which extension are not marked for preprocessing will be just copied (of course if the extensions is not in the list of excluded file extensions)

More complex example:

java -jar jcp-6.1.4.jar  --c --r --v --f:java,xml --ef:none --i:./test --o:./result  '--p:HelloWorld=$Hello world$'
  • --c clear the destination folder before work
  • --r remove all Java-style comments from preprocessed result files
  • --v show verbose log about preprocessing process
  • --f include .java and .xml files into preprocessing (by default the preprocessor doesn't preprocess XNL files and the extension should to be defined explicitly)
  • --ef don't exclude any extension from preprocessing
  • --i use ./test as source folder
  • --o use ./result as destination folder
  • --p define named global variable HelloWorld? with the 'Hello world' content
  • --z turn on checking of file content before replacement, if the same content then preprocessor will not replace the file
  • --es allow whitespace between comment and directive (by default it is turned off)

The Main idea

The Java language was born without any preprocessor in creator's mind and even now there are not any plans to include preprocessing into Java. It was good until mass usage Java on mobile and TV devices where we have bunches of half-compatible devices with (sometime) very bizarre standard framework implementations. In the case, preprocessing allows to decrease support of sources dramatically.
The only possible way to include preprocessing directives into Java and to not break standard processes and Java tool chain is to inject them into comments, take a look at the example below:

//#local TESTVAR="TEST LOCAL VARIABLE"
//#echo TESTVAR=/*$TESTVAR$*/
//#include "./test/_MainProcedure.java"

public static final void testproc()
{
 System.out.println(/*$VARHELLO$*/);
 System.out.println("// Hello commentaries");
 //#local counter=10
        //#while counter!=0
        System.out.println("Number /*$counter$*/");
        //#local counter=counter-1
        //#end
 System.out.println("Current file name is /*$SRV_CUR_FILE$*/");
 System.out.println("Output dir is /*$SRV_OUT_DIR$*/");
 //#if issubstr("Hello","Hello world")
 System.out.println("Substring found");
 //#endif
}

Multi-sectioned documents

Java sources usually have sections, there are the import section and the main section thus JCP has support for such case and there are three section where the preprocessor can write results - the prefix, the middle part and the postfix. Usually I use the prefix to form the import section for Java files. You can switch the text output for sections with //#prefix[+|-] and //#postfix[+|-] directives.

//#prefix+
 import java.lang.*;
 //#prefix-
 public class Main {
  //#prefix+
  import java.util.*;
  //#prefix-
  public static void main(String ... args){}
 }

How to remove all coments from sources

Sometime it is very useful to remove all comments from my sources at all, JCP has such feature which can be turned on by special flag or command line switcher (see wiki). The Example of use for comment removing through CLI interface

java -jar ./jcp-6.1.4.jar --i:/sourceFolder --o:/resultFolder -ef:none --r