raydac / java-comment-preprocessor Goto Github PK

Hi,

I am using JCP for a product line. If a feature is included (e.g. for the feature belt) //#define belt is added.
Currently //#if belt && dev fails, if belt or dev is unknown. Note that this is possible to rewrite as 2 //#ifdef after each other, which is not possible with //#if belt || dev. It would be great to have a way to treat all undefined variables as false in the #if...

Thanks!

In Wiki's gradle example there are several excluded extensions in the resources.
When building an android project most of the drawable resources are ignored and not copied to preprocess destination dir.
I suggest you change the example's exclusion list to 'none'.

Could you please add an option to ignore (treat as empty string?) variables that are set to empty or undeclared properties?

Here's an example:

I have plugin

                <groupId>io.github.git-commit-id</groupId>
                <artifactId>git-commit-id-maven-plugin</artifactId>
                <version>7.0.0</version>

Which sets properties including "${git.build.time}"

I have your plugin with

                    <vars>
                        <GIT_BUILD_TIME>${git.build.time}</GIT_BUILD_TIME>

Which is then used in the source like that

log.info("Build time: /*$GIT_BUILD_TIME$*/");

Everything works as intended

Now try to change it to

                        <GIT_BUILD_TIME></GIT_BUILD_TIME>

or

                        <GIT_BUILD_TIME>${git.build.timeUNDECLARED}</GIT_BUILD_TIME>

Both result in error:

Failed to execute goal com.igormaznitsa:jcp:7.1.0:preprocess (preprocess-sources) on project lbnet-maven-plugins-launch4j-wrp: Parameter is null -> [Help 1]

I tried < unknownVarAsFalse > true < /unknownVarAsFalse > but apparently it doesn't affect var declarations in pom, only var usage in sources.

Could you please add an option to handle that? " < allowEmptyVarDeclarations > " or something, to have them resolve to empty strings "" instead of throwing an error at buildtime?

p.s. Have I mentioned I really appreciate your work? I never understood why Java devs decided preprocessing is unnecessary.

I've searched through half of the code in order to understand how the //#action directive works. As far as I understood one can plug in your own preprocessing macros through extending the PreprocessorExtension. But how can I set my own extension class so that the preprocessor uses it? Neither the documap nor the gradle task give any information about that. In addition to that, a PreprocessorContext.setPreprocessorExtension(PreprocessorExtension) method is defined but never used (at least I couldn't find any usages with IntelliJ decompiler & find usages). Is the feature not ready yet or did I just miss something?

Many Maven plugins have a skip parameter with an associated property to skip the execution. Having such parameter and property is convenient as it allows a) temporarily disabling plugin in command line by adding a -D option; b) configuring plugin in a parent POM and redefining a property in a child POM to change behavior (enable or disable execution).

Please add such parameter to the JCP Maven plugin.

I can create a pull request if it helps.

Currently java-comment-preprocessor always overwrites files, so java compiler always recompiles all the files.

Can JCP doublecheck if output is good enough and avoid file overwrites?

relative paths as arguments work well, but evalfile(mvn.project.build.sourcedirectory+"/somefile.txt") throws exception and can't find the file

The current design allows having at most one jcp task per project which might be not enough.

What do you think if the task had its own parameters while the extension serves as the set of default values?

What a cool concept this is!
Not only does it allow me to change source code for Java files, but also for Kotlin and Scala files (which is what I use it for at the moment).

However, I do seem to have some issues to make IntelliJ understand what's happening in my multi-module maven project.

The current problem I'm having: when running mvn compile, all works well. The tests work, I can hit run in IntelliJ on a file (which is not delegated to maven because that fails in multi module projects because of the other module's package being "not available on maven central") and I get the properly modified sources.
However, when I change the source code in a module that contains bits that need preprocessing and I hit run on a file in another module that uses it, the preprocessing won't take place and it won't work anymore (since IntelliJ then skips maven).

Is there any way to make IntelliJ somehow aware of this preprocessor, like it is for annotation processors, so that it always gets preprocessed before executing?
Or would I for instance have to switch to Gradle for better multi-module support?

If a plugin would be needed for this, something similar already exists for a JCP-like preprocessor:
https://github.com/FalseHonesty/intellij-preprocessor which also does nice highlighting and such. It's just a bit out of date, but autocomplete and highlighting might actually be a nice feature for JCP too :).

Hi, i find this tool very useful, but cannot make it to run with Maven, when i put your sample code in my pom file im getting the following error "Plugin execution not covered by lifecycle configuration: com.igormaznitsa:jcp:6.1.2:preprocess (execution: preprocessSources, phase: generate-sources)" if i put this code in "pluginManagement" part of pom it gives no errors, but im not getting expected results. What maven goal should i run to get it compiled with this tool? I assumed it will run with standard install goals ? Maybe im using this wrong ?

We are migrating our codebase from some old persistence technology to JPA. We have to support both technologies in the transition phase. After evaluating some options, we chose JCP to build our code for one of the persistence technologies.

JCP works for us perfectly in most cases, the only trouble is IDE (which is not JCP's fault of course). Usually we use only #ifdef JPA directive. IDE ignores the directive and we effectively get JPA code compiled. There are however some cases where we have to use something similar to the following:

//#ifdef JPA
    doOneThing();
//#else
    doOtherThing();
//#endif

If there are some workarounds for the case above, the following is even worse:

class SomeClass
//#ifdef JPA
        extends OneBase
//#else
        extends OtherBase
//#endif

I have an idea for one-liners:

//#ifdef JPA
    doOneThing();
//#endif
//#ifndef JPA: doOtherThing();

//#ifdef JPA
    doOneThing();
//else: doOtherThing();
//#endif

IDE will recognize the second part as comment and will ignore it. Do you think it's possible to have something like this?

It seems that override from command line is ignored:

mvn -Dmy.property=false compile

  <properties>
    <my.property>true</my.property>
  </properties>

	//#if mvn.project.property.my.property == "true"
...
	//#endif

I uses a profile to bypass.

Typical Maven plugins have separate goals for the main and test sources, for example compile and testCompile, resources and testResources. Having a testPreprocess goal bound to the generate-test-sources goal may greatly reduce configuration. The following

<executions>
    <execution>
        <id>preprocess-sources</id>
        <goals>
            <goal>preprocess</goal>
        </goals>
    </execution>
    <execution>
        <id>preprocess-test-sources</id>
        <configuration>
            <useTestSources>true</useTestSources>
        </configuration>
        <goals>
            <goal>preprocess</goal>
        </goals>
        <phase>generate-test-sources</phase>
    </execution>
</executions>

may be then replaced with

<executions>
    <execution>
        <goals>
            <goal>preprocess</goal>
            <goal>testPreprocess</goal>
        </goals>
    </execution>
</executions>

All existing properties may be supported, the testProcess goal may just have different defaults.

This is a minor improvement. I could create a pull request if you think that this feature has a value.

Hi!

I was wondering whether it would/could be possible to define a //#local variable using a multiline string.
I want to use JCP to reuse documentation for many function overloads and while I can define the documentation in gradle, I think it would be better to define them in the same file they are reused.
This is already possible:

//#local ADD = " * Original [DataFrame] is not modified.\n *\n * @throws [DuplicateColumnNamesException] if columns in expected result have repeated names\n * @throws [UnequalColumnSizesException] if columns in expected result have different sizes\n * @return new [DataFrame] with added columns"

/**
 * Creates new [DataFrame] with given columns added to the end of original [DataFrame.columns] list.
 *
/*$ADD$*/
 * @param columns columns to add
 */
public fun <T> DataFrame<T>.add(vararg columns: AnyBaseCol): DataFrame<T> = addAll(columns.asIterable())

But you can imagine that writing long documentation on the same line would be a hassle. Is there a notation possible with JCP that allows for something like this?

//#local ADD = """ * Original [DataFrame] is not modified.
//# *
//# * @throws [DuplicateColumnNamesException] if columns in expected result have repeated names
//# * @throws [UnequalColumnSizesException] if columns in expected result have different sizes
//# * @return new [DataFrame] with added columns"""

I am using jcp with gradle in android studio
I declared a global variable (TEST_VAR) in preprocess.gradle.
When preprocessing the source TEST_VAR is known...
When preprocessing the resources TEST_VAR is unknown and an exception is thrown.
When declaring TEST_VAR as global in the xml the file is preprocessed correctly.

When using maven-source-plugin, it forcefully executes generate-sources phase.
That causes:

1. reprocessing of already processed sources
2. failures if certain non-existent folders are present in "project source directories". For instance, maven-compiler-plugin seems to add /generated-sources/annotations folder to "project source directories" yet it might never be created.

While those might be bugs related to sources & compiler plugins, it will take a while for them to be fixed & released.

Am I doing something wrong? Does it make sense to elaborate JCP readme on the subject?

I switched to binding JCP to preprocess-sources to workaround maven-source-plugin.

The list of valid variables is very helpful for initial usage of JCP, so it is good it is enabled by default.

However:

1. It is not that safe to print all the properties (e.g. mvn.project.property.password, mvn.project.property.gpg.passphrase, etc). maven logs can be copy&pasted and it might lead to unexpected sharing of the passwords.

2. It would be nice to have a configuration property to suppress that output (as it would no longer be required after JCP comments are in place)

I am using your preprocessor as a maven plugin. I have this code:
xxxx
and it does not print when I have not defined the flag, and does when I do. So I know the plug-in preprocessing is taking place.
But when I tried enabling the print statements via mvn compile command:
/opt/apache-maven-3.2.3/bin/mvn clean install -DskipTests=true -DPRINT_WAYNE_FLAG=true
It did not work. Do you know what syntax I should use in the mvn command line to send a flag through mvn to affect the value of preprocessor flags in java code?

Typical Maven plugins skip missing source folders (compiler, resources, surefire, etc). This allows configuring them once in a parent POM or lifecyle. JCP fails the build if the source folder is missing.

Use case: we are using JCP in a big project with over 500 modules. Currently we define 2 executions: one for main and one for test sources. We want to configure JCP in the common parent POM to enable it in all modules by default, but it does not always work, because some modules do not have test sources.

Please make JCP Maven plugin ignore missing sources folders, or add a configuration parameter to ignore missing source folders.

I can implement the change and make a pull request if that will speed up things.

In fedora, we don't have the meta-* jars:
https://bugzilla.redhat.com/show_bug.cgi?id=1584114

Is there a possibility to make that meta-* stuff optional for jcp?

Could you please add an option to Maven plugin that allows removing comments but only those that contain JCP macros? So that javadocs and code-explaining comments remain untouched?

Hi,

This tool/plugin is great! The only minor inconvenience is that the directives must be //#directive and at least based on my tests they wont work if there is whitespace between the // and #, i.e. // #directive. I'm not sure how common it is but at least in eclipse standard java formatter convetions it is to add a space between the // and rest of the comment. I would assume it is used quite a lot (either configured as on-save-action or executed separately).

This means I need to disable that part of the formatter (which in practise means I need to create a custom one as the default cannot be edited). It also requires everyone else to be aware of this issue if they are using any auto formatting in a shared project and adding some "safety checks" to the build to check that the processing has happened.

It would be great if in the future there would be an option to allow that whitespace to exist (probably by default off to keep backward compatibility). Alternatively supporting e.g. // //#directive would work too.

Bjakke

Version 7.0.5, Gradle 7.4

Currently, the default target of the preprocess task is "build/java-comment-preprocessor/preprocess". This is inside the build folder, which gets deleted entirely when running the clean task. However, if I run preprocess again after a clean, I get > Task :core:preprocess UP-TO-DATE, after which, the preprocess folder won't be regenerated anymore.
Currently, my solution is to enable clearTarget and move the target outside of the build folder so it survives a clean and clears itself. This is not ideal, however.

[ERROR] /builddir/build/BUILD/java-comment-preprocessor-6.1.4/src/test/java/com/igormaznitsa/jcp/AbstractMockPreprocessorContextTest.java:[44,52] cannot find symbol
symbol: method getArgumentAt(int,java.lang.Class<java.lang.String>)
location: variable invocation of type org.mockito.invocation.InvocationOnMock
[ERROR] /builddir/build/BUILD/java-comment-preprocessor-6.1.4/src/test/java/com/igormaznitsa/jcp/AbstractMockPreprocessorContextTest.java:[44,124] cannot find symbol
symbol: method getArgumentAt(int,java.lang.Class<java.lang.Throwable>)
location: variable invocation of type org.mockito.invocation.InvocationOnMock

Seems to be related to mockito/mockito/issues/945

I've been upgrading some code in a project. It had been using jcp 5.3.2 and when I upgraded to 7.0.3, I discovered that comments were being stripped out even though the "r" option was not specified.

I tried a few versions up to 6.1.4 and confirmed that this behavior first appears in 7.0.0.

As pull request is accepted, it would be nice to automatically update snapshot versions, so users can test current version without manual compilation.

This seems to be a workable solution: https://gist.github.com/neothemachine/4060735