Package org.codehaus.mojo.javacc
Class JJDocMojo
java.lang.Object
org.apache.maven.plugin.AbstractMojo
org.apache.maven.reporting.AbstractMavenReport
org.codehaus.mojo.javacc.JJDocMojo
- All Implemented Interfaces:
org.apache.maven.plugin.ContextEnabled
,org.apache.maven.plugin.Mojo
,org.apache.maven.reporting.MavenMultiPageReport
,org.apache.maven.reporting.MavenReport
@Mojo(name="jjdoc")
@Execute(phase=GENERATE_SOURCES)
public class JJDocMojo
extends org.apache.maven.reporting.AbstractMavenReport
JJDoc takes a JavaCC parser specification and produces
documentation for the BNF grammar. This mojo will search the source directory for all
*.jj
files and
run JJDoc once for each file it finds. Each of these output files, along with an index.html
file will
be placed in the site directory (target/site/jjdoc
), and a link will be created in the "Project
Reports" menu of the generated site.- Since:
- 2.3
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static class
Compares grammar infos using their relative grammar file paths as the sort key. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Boolean
A flag whether to generate a plain text document with the unformatted BNF.private String
The hypertext reference to an optional CSS file for the generated HTML documents.private File
The default source directory for hand-crafted grammar files.private File
The default source directory for grammar files generated by JJTree.private File
The default source directory for grammar files generated by JTB.private String
The file encoding to use for reading the grammar files.private String
The relative path of the JJDoc reports in the output directory.private boolean
This option controls the structure of the generated HTML output.private File
The destination directory where JJDoc saves the generated documentation files.private File[]
The directories where the JavaCC grammar files (*.jj
) are located.private Boolean
A flag to specify the output format for the generated documentation.Fields inherited from class org.apache.maven.reporting.AbstractMavenReport
locale, mojoExecution, outputFormat, outputTimestamp, project, reactorProjects, remoteProjectRepositories, repoSession, siteDirectory, siteRenderer, siteTool
Fields inherited from interface org.apache.maven.reporting.MavenReport
CATEGORY_PROJECT_INFORMATION, CATEGORY_PROJECT_REPORTS, ROLE
Fields inherited from interface org.apache.maven.plugin.Mojo
ROLE
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
private void
createReportFooter
(org.apache.maven.doxia.sink.Sink sink) Create the HTML footer for the report page.private void
createReportHeader
(ResourceBundle bundle, org.apache.maven.doxia.sink.Sink sink) Create the header and title for the HTML report page.private void
createReportLink
(org.apache.maven.doxia.sink.Sink sink, File sourceDirectory, File grammarFile, String linkPath) Create a table row containing a link to the JJDoc report for a grammar file.void
executeReport
(Locale locale) Run the actual report.void
private ResourceBundle
Get the resource bundle for the report text.getDescription
(Locale locale) private File
Get the output directory of the JJDoc files, i.e.protected String
Get the output directory of the report if run directly from the command line.private String
private File[]
Get the source directories that should be scanned for grammar files.private JJDoc
newJJDoc()
Creates a new facade to invoke JJDoc.private GrammarInfo[]
scanForGrammars
(File sourceDirectory) Searches the specified source directory to find grammar files that can be documented.Methods inherited from class org.apache.maven.reporting.AbstractMavenReport
closeReport, constructXrefLocation, execute, generate, getCategoryName, getInputEncoding, getLocale, getOutputEncoding, getProject, getReportOutputDirectory, getSink, getSinkFactory, getSiteRenderer, getXrefLocation, isExternalReport, setReportOutputDirectory
Methods inherited from class org.apache.maven.plugin.AbstractMojo
getLog, getPluginContext, setLog, setPluginContext
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.apache.maven.reporting.MavenReport
getOutputPath
-
Field Details
-
sourceDirectories
The directories where the JavaCC grammar files (*.jj
) are located. By default, the directories${basedir}/src/main/javacc
,${project.build.directory}/generated-sources/jjtree
and${project.build.directory}/generated-sources/jtb
are scanned for grammar files to document. -
defaultGrammarDirectoryJavaCC
The default source directory for hand-crafted grammar files. -
defaultGrammarDirectoryJJTree
@Parameter(defaultValue="${project.build.directory}/generated-sources/jjtree") private File defaultGrammarDirectoryJJTreeThe default source directory for grammar files generated by JJTree. -
defaultGrammarDirectoryJTB
@Parameter(defaultValue="${project.build.directory}/generated-sources/jtb") private File defaultGrammarDirectoryJTBThe default source directory for grammar files generated by JTB. -
jjdocDirectory
The relative path of the JJDoc reports in the output directory. This path will be appended to the output directory. -
outputDirectory
@Parameter(defaultValue="${project.reporting.outputDirectory}", property="javacc.outputDirectory") private File outputDirectoryThe destination directory where JJDoc saves the generated documentation files. Note that this parameter is only relevant if the goal is run from the command line or from the default build lifecycle. If the goal is run indirectly as part of a site generation, the output directory configured in the Maven Site Plugin is used instead. -
grammarEncoding
@Parameter(defaultValue="${project.build.sourceEncoding}", property="javacc.grammarEncoding") private String grammarEncodingThe file encoding to use for reading the grammar files.- Since:
- 2.6
-
cssHref
The hypertext reference to an optional CSS file for the generated HTML documents. If specified, this CSS file will be included via a<link>
element in the HTML documents. Otherwise, the default style will be used.- Since:
- 2.5
-
text
A flag to specify the output format for the generated documentation. If set totrue
, JJDoc will generate a plain text description of the BNF. Some formatting is done via tab characters, but the intention is to leave it as plain as possible. Specifyingfalse
causes JJDoc to generate a hyperlinked HTML document unless the parameterbnf
has been set totrue
. Default value isfalse
. -
bnf
A flag whether to generate a plain text document with the unformatted BNF. Note that setting this option totrue
is only effective if the parametertext
isfalse
. Default value isfalse
.- Since:
- 2.6
-
oneTable
@Parameter(property="javacc.oneTable", defaultValue="true") private boolean oneTableThis option controls the structure of the generated HTML output. If set totrue
, a single HTML table for the entire BNF is generated. Setting it tofalse
will produce one table for every production in the grammar.
-
-
Constructor Details
-
JJDocMojo
public JJDocMojo()
-
-
Method Details
-
getOutputDirectory
Get the output directory of the report if run directly from the command line.- Overrides:
getOutputDirectory
in classorg.apache.maven.reporting.AbstractMavenReport
- Returns:
- The report output directory.
- See Also:
-
getJJDocOutputDirectory
Get the output directory of the JJDoc files, i.e. the sub directory in the report output directory as specified by thejjdocDirectory
parameter.- Returns:
- The report output directory of the JJDoc files.
-
getSourceDirectories
Get the source directories that should be scanned for grammar files.- Returns:
- The source directories that should be scanned for grammar files, never
null
.
-
getName
- Parameters:
locale
- The locale to use for this report.- Returns:
- The name of this report.
- See Also:
-
getDescription
- Parameters:
locale
- The locale to use for this report.- Returns:
- The description of this report.
- See Also:
-
getOutputName
- Returns:
- The name of the main report file.
- See Also:
-
canGenerateReport
public boolean canGenerateReport()- Specified by:
canGenerateReport
in interfaceorg.apache.maven.reporting.MavenReport
- Overrides:
canGenerateReport
in classorg.apache.maven.reporting.AbstractMavenReport
- Returns:
true
if the configured source directories are not empty,false
otherwise.- See Also:
-
executeReport
Run the actual report.- Specified by:
executeReport
in classorg.apache.maven.reporting.AbstractMavenReport
- Parameters:
locale
- The locale to use for this report.- Throws:
org.apache.maven.reporting.MavenReportException
- If the report generation failed.
-
getOutputFileExtension
The JJDoc output file will have a.html
or.txt
extension depending on the value of the parameterstext
andbnf
.- Returns:
- The file extension (including the leading period) to be used for the JJDoc output files.
-
createReportHeader
Create the header and title for the HTML report page.- Parameters:
bundle
- The resource bundle with the text.sink
- The sink for writing to the main report file.
-
createReportLink
private void createReportLink(org.apache.maven.doxia.sink.Sink sink, File sourceDirectory, File grammarFile, String linkPath) Create a table row containing a link to the JJDoc report for a grammar file.- Parameters:
sink
- The sink to write the reportsourceDirectory
- The source directory of the grammar file.grammarFile
- The JavaCC grammar file.linkPath
- The path to the JJDoc output.
-
newJJDoc
Creates a new facade to invoke JJDoc. Most options for the invocation are derived from the current values of the corresponding mojo parameters. The caller is responsible to set the input file and output file on the returned facade.- Returns:
- The facade for the tool invocation, never
null
.
-
scanForGrammars
private GrammarInfo[] scanForGrammars(File sourceDirectory) throws org.apache.maven.reporting.MavenReportException Searches the specified source directory to find grammar files that can be documented.- Parameters:
sourceDirectory
- The source directory to scan for grammar files.- Returns:
- An array of grammar infos describing the found grammar files or
null
if the source directory does not exist. - Throws:
org.apache.maven.reporting.MavenReportException
- If there is a problem while scanning for .jj files.
-
getBundle
Get the resource bundle for the report text.- Parameters:
locale
- The locale to use for this report.- Returns:
- The resource bundle.
-
generate
public void generate(org.apache.maven.doxia.sink.Sink sink, Locale locale) throws org.apache.maven.reporting.MavenReportException - Specified by:
generate
in interfaceorg.apache.maven.reporting.MavenReport
- Overrides:
generate
in classorg.apache.maven.reporting.AbstractMavenReport
- Throws:
org.apache.maven.reporting.MavenReportException
-