Built by Maven

javacc:jtb

Full name:

org.javacc.plugin:javacc-maven-plugin:3.8.0-SNAPSHOT:jtb

Description:

The jtb goal, for generating the tree files (but not the parser files) from a JTB grammar.
It searches the source directory for all grammar files and run JTB once for each file it finds, managing the output directory from the user setting or the default setting, and adding it to the project-wide compile source roots.
It uses an intermediate output directory to help discard any generated file when the user wants instead his customized version he has put in any compile source root.

Detailed information about the JTB options can be found on the JTB wiki.
The code repository can be found within JTB at GitHub.

Attributes:

  • Requires a Maven project to be executed.
  • The goal is thread-safe and supports parallel builds.
  • Since version: 3.8.0.
  • Binds by default to the lifecycle phase: generate-sources.

Optional Parameters

Name Type Since Description
<excludes> String[] - The set of Ant-like exclusion patterns used to prevent certain files from being processed.
By default, this set is empty such that no files are excluded.
<failOnGrammarError> String - The fail on grammar error parameter.
It governs how the plugin will handle the errors it encountered while trying to read a grammar file to retrieve the parser name (and the parser package for languages that use it) (in an execution the plugin may process zero, one or many grammars).
Possible values are first, last and ignore.
If set to first, the error message is displayed, the plugin will stop processing other grammars and will report an error for the build;
if set to last, the error message is displayed, the plugin will continue processing other grammars and at the end it will report an error for the build;
if set to ignore the error message(s) is(are) displayed but the plugin will not report an error for the current execution (i.e. it will continue with the next execution).
Default: first
User Property: javacc.failOnGrammarError
<failOnPluginError> Boolean - The fail on plugin error flag.
It governs how the plugin will handle the errors it encountered on general configuration (i.e. parameters not related to grammars).
Possible values are true and false.
On the first error: if set to false, the error message is displayed but the plugin will not report an error for the current execution (i.e. it will continue with the next execution);
if set to true the error message is displayed and the plugin will report an error for the build.
Default: true
User Property: javacc.failOnPluginError
<failOnProcessorError> String - The fail on processor error parameter.
It governs how the plugin will handle the errors returned by the processor invocations and the plugin post-processor copy operations (in an execution the plugin may process zero, one or many grammars and invoke one or more processors for each).
Possible values are first, last and ignore.
If set to first, the error message is displayed, the plugin will stop processing other grammars and will report an error for the build;
if set to last, the error message is displayed, the plugin will continue processing other grammars and at the end it will report an error for the build;
if set to ignore the error message(s) is(are) displayed but the plugin will not report an error for the current execution (i.e. it will continue with the next execution).
Default: first
User Property: javacc.failOnProcessorError
<includes> String[] - The set of Ant-like inclusion patterns used to select files from the source directory for processing.
By default, the patterns are:
**/*.jj for the javacc goal,
**/*.jjt for the jjtree and jjtree-javacc goals,
**/*.jtb for the jtb and jtb-javacc goals.
<jtbCmdLineArgs> List<String> - The list of single full command line arguments, which should be in the form accepted by JTB/JavaCC.

Arguments' values for -CODE_GENERATOR, -GRAMMAR_ENCODING, -d or -JTB_D and -OUTPUT_DIRECTORY are read and used by the plugin; their default values (i.e. if these options are not present) are "Java" (as for JTB/JavaCC), system property file.encoding (as for JTB/JavaCC) ${project.build.directory}/generated-sources/jtb and ${project.build.directory}/generated-sources/javacc (as usual maven convention, which is different from JavaCC and JTB default values which are ".").

The list will be passed as it is to JTB, no control nor modification is done by the plugin, except for -d or -JTB_D, whose value will be changed to an intermediate temporary directory ${project.build.directory}/jtb-nnnnnn. The given output directory value will be used at the end to copy the generated files from the intermediate directory to it.

The list has no default value (except for the 3 above options) (but JTB/JavaCC itself supplies default values).
Note that among those 3 default values, the grammar encoding one (platform file encoding) may be not adequate as most of the times the project is under an IDE and globally set to a platform independent encoding like 'UTF-8'.

Example:


<jtbCmdLineArgs>
  <arg>-ns="MyNode"</arg>
  <arg>-JTB_VIS=false</arg>
  <arg>-code_generator:"Java"</arg>
  <arg>-Grammar_Encoding="UTF-8"</arg>
  <arg>-d="${
project.build.directory
}/gen-src/jtb"</arg>
  <arg>-OUTPUT_DIRECTORY="${
project.build.directory
}/gen-src/jj"</arg>
</jtbCmdLineArgs>

Note that the jtbCmdLineArgs parameter is of type List<String>, which implies that the inner tags names can have any names and may be appear many times (like arg above).
Note also that if the project has a parent which also configures the plugin with parameters (to factorize them for the children for example), the child parameters will complement / replace the parent's ones for those that are absent / present in the parent; so
  • if one wants to get rid of (all) the parent's ones, he must use the combine.self="override" attribute at the list level in the child, and
  • if one wants to replace some of the parent's ones and add new ones in the child it is recommended to use distinct tag names in the parent, the same tag names in the child for those that must be replaced and another tag name or other tag names for the new ones.
See also Processor parameters.
User Property: javacc.jtbCmdLineArgs
<keepIntermediateDirectory> Boolean - The keep the intermediate directory(ies) flag.
If set to true, the intermediate directory(ies) will not be deleted, which may sometimes be handy for plugin or processor debug purposes.
Default: false
User Property: javacc.keepIntermediateDirectory
<skip> Boolean - The skip processing flag.
If true, no goal will not be executed.
Default: false
User Property: javacc.skip
<sourceDirectory> File - The directory where the grammar files are located.
It must exist and be a directory, otherwise a plugin error will be raised.
This directory will be recursively scanned for input files to pass to JavaCC.
If one wants a pom to process more than one source directory, he must configure multiple executions with different source directories.
Note: we could have implemented a list of source directories (as in AbstractPluginReport, but most of the time different source directories will need different configurations, so the user would still have to configure multiple executions.
The parameters includes and excludes can be used to select a subset of the files.
If not an absolute path, maven internals considers it is relative to ${basedir} and converts it accordingly to an absolute path (i.e. src/main/javacc will be considered as ${basedir}/src/main/javacc, but /src/main/javacc will be considered as an absolute path, usually leading to an error.
The default value, adequate for a user written grammar, but not for a generated (by a preprocessor) grammar, is:
${basedir}/src/main/javacc for JavaCC,
${basedir}/src/main/jjtree for JJTree,
${basedir}/src/main/jtb for JTB.
User Property: javacc.sourceDirectory
<timestampDeltaMs> Long - The delta in milliseconds of the last modification timestamps for testing whether a grammar file needs regeneration.
If set to a negative value, no comparison will be performed and grammars will always be passed to the processor.
Otherwise a grammar file will be passed to the processor if the sum of the main generated file timestamp plus this delta is lower than the grammar file timestamp or than the more recent of the dependent jars timestamps.
Default: 0
User Property: javacc.timestampDeltaMs

Parameter Details

<excludes>

The set of Ant-like exclusion patterns used to prevent certain files from being processed.
By default, this set is empty such that no files are excluded.
  • Type: java.lang.String[]
  • Required: No

<failOnGrammarError>

The fail on grammar error parameter.
It governs how the plugin will handle the errors it encountered while trying to read a grammar file to retrieve the parser name (and the parser package for languages that use it) (in an execution the plugin may process zero, one or many grammars).
Possible values are first, last and ignore.
If set to first, the error message is displayed, the plugin will stop processing other grammars and will report an error for the build;
if set to last, the error message is displayed, the plugin will continue processing other grammars and at the end it will report an error for the build;
if set to ignore the error message(s) is(are) displayed but the plugin will not report an error for the current execution (i.e. it will continue with the next execution).
  • Type: java.lang.String
  • Required: No
  • User Property: javacc.failOnGrammarError
  • Default: first

<failOnPluginError>

The fail on plugin error flag.
It governs how the plugin will handle the errors it encountered on general configuration (i.e. parameters not related to grammars).
Possible values are true and false.
On the first error: if set to false, the error message is displayed but the plugin will not report an error for the current execution (i.e. it will continue with the next execution);
if set to true the error message is displayed and the plugin will report an error for the build.
  • Type: java.lang.Boolean
  • Required: No
  • User Property: javacc.failOnPluginError
  • Default: true

<failOnProcessorError>

The fail on processor error parameter.
It governs how the plugin will handle the errors returned by the processor invocations and the plugin post-processor copy operations (in an execution the plugin may process zero, one or many grammars and invoke one or more processors for each).
Possible values are first, last and ignore.
If set to first, the error message is displayed, the plugin will stop processing other grammars and will report an error for the build;
if set to last, the error message is displayed, the plugin will continue processing other grammars and at the end it will report an error for the build;
if set to ignore the error message(s) is(are) displayed but the plugin will not report an error for the current execution (i.e. it will continue with the next execution).
  • Type: java.lang.String
  • Required: No
  • User Property: javacc.failOnProcessorError
  • Default: first

<includes>

The set of Ant-like inclusion patterns used to select files from the source directory for processing.
By default, the patterns are:
**/*.jj for the javacc goal,
**/*.jjt for the jjtree and jjtree-javacc goals,
**/*.jtb for the jtb and jtb-javacc goals.
  • Type: java.lang.String[]
  • Required: No

<jtbCmdLineArgs>

The list of single full command line arguments, which should be in the form accepted by JTB/JavaCC.

Arguments' values for -CODE_GENERATOR, -GRAMMAR_ENCODING, -d or -JTB_D and -OUTPUT_DIRECTORY are read and used by the plugin; their default values (i.e. if these options are not present) are "Java" (as for JTB/JavaCC), system property file.encoding (as for JTB/JavaCC) ${project.build.directory}/generated-sources/jtb and ${project.build.directory}/generated-sources/javacc (as usual maven convention, which is different from JavaCC and JTB default values which are ".").

The list will be passed as it is to JTB, no control nor modification is done by the plugin, except for -d or -JTB_D, whose value will be changed to an intermediate temporary directory ${project.build.directory}/jtb-nnnnnn. The given output directory value will be used at the end to copy the generated files from the intermediate directory to it.

The list has no default value (except for the 3 above options) (but JTB/JavaCC itself supplies default values).
Note that among those 3 default values, the grammar encoding one (platform file encoding) may be not adequate as most of the times the project is under an IDE and globally set to a platform independent encoding like 'UTF-8'.

Example:


<jtbCmdLineArgs>
  <arg>-ns="MyNode"</arg>
  <arg>-JTB_VIS=false</arg>
  <arg>-code_generator:"Java"</arg>
  <arg>-Grammar_Encoding="UTF-8"</arg>
  <arg>-d="${
project.build.directory
}/gen-src/jtb"</arg>
  <arg>-OUTPUT_DIRECTORY="${
project.build.directory
}/gen-src/jj"</arg>
</jtbCmdLineArgs>

Note that the jtbCmdLineArgs parameter is of type List<String>, which implies that the inner tags names can have any names and may be appear many times (like arg above).
Note also that if the project has a parent which also configures the plugin with parameters (to factorize them for the children for example), the child parameters will complement / replace the parent's ones for those that are absent / present in the parent; so
  • if one wants to get rid of (all) the parent's ones, he must use the combine.self="override" attribute at the list level in the child, and
  • if one wants to replace some of the parent's ones and add new ones in the child it is recommended to use distinct tag names in the parent, the same tag names in the child for those that must be replaced and another tag name or other tag names for the new ones.
See also Processor parameters.
  • Type: java.util.List<java.lang.String>
  • Required: No
  • User Property: javacc.jtbCmdLineArgs

<keepIntermediateDirectory>

The keep the intermediate directory(ies) flag.
If set to true, the intermediate directory(ies) will not be deleted, which may sometimes be handy for plugin or processor debug purposes.
  • Type: java.lang.Boolean
  • Required: No
  • User Property: javacc.keepIntermediateDirectory
  • Default: false

<skip>

The skip processing flag.
If true, no goal will not be executed.
  • Type: java.lang.Boolean
  • Required: No
  • User Property: javacc.skip
  • Default: false

<sourceDirectory>

The directory where the grammar files are located.
It must exist and be a directory, otherwise a plugin error will be raised.
This directory will be recursively scanned for input files to pass to JavaCC.
If one wants a pom to process more than one source directory, he must configure multiple executions with different source directories.
Note: we could have implemented a list of source directories (as in AbstractPluginReport, but most of the time different source directories will need different configurations, so the user would still have to configure multiple executions.
The parameters includes and excludes can be used to select a subset of the files.
If not an absolute path, maven internals considers it is relative to ${basedir} and converts it accordingly to an absolute path (i.e. src/main/javacc will be considered as ${basedir}/src/main/javacc, but /src/main/javacc will be considered as an absolute path, usually leading to an error.
The default value, adequate for a user written grammar, but not for a generated (by a preprocessor) grammar, is:
${basedir}/src/main/javacc for JavaCC,
${basedir}/src/main/jjtree for JJTree,
${basedir}/src/main/jtb for JTB.
  • Type: java.io.File
  • Required: No
  • User Property: javacc.sourceDirectory

<timestampDeltaMs>

The delta in milliseconds of the last modification timestamps for testing whether a grammar file needs regeneration.
If set to a negative value, no comparison will be performed and grammars will always be passed to the processor.
Otherwise a grammar file will be passed to the processor if the sum of the main generated file timestamp plus this delta is lower than the grammar file timestamp or than the more recent of the dependent jars timestamps.
  • Type: java.lang.Long
  • Required: No
  • User Property: javacc.timestampDeltaMs
  • Default: 0