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 anindex.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:
- JJDoc Documentation
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
JJDocMojo.GrammarInfoComparator
Compares grammar infos using their relative grammar file paths as the sort key.
-
Field Summary
Fields Modifier and Type Field Description private java.lang.Boolean
bnf
A flag whether to generate a plain text document with the unformatted BNF.private java.lang.String
cssHref
The hypertext reference to an optional CSS file for the generated HTML documents.private java.io.File
defaultGrammarDirectoryJavaCC
The default source directory for hand-crafted grammar files.private java.io.File
defaultGrammarDirectoryJJTree
The default source directory for grammar files generated by JJTree.private java.io.File
defaultGrammarDirectoryJTB
The default source directory for grammar files generated by JTB.private java.lang.String
grammarEncoding
The file encoding to use for reading the grammar files.private java.lang.String
jjdocDirectory
The relative path of the JJDoc reports in the output directory.private boolean
oneTable
This option controls the structure of the generated HTML output.private java.io.File
outputDirectory
The destination directory where JJDoc saves the generated documentation files.private java.io.File[]
sourceDirectories
The directories where the JavaCC grammar files (*.jj
) are located.private java.lang.Boolean
text
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
-
-
Constructor Summary
Constructors Constructor Description JJDocMojo()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
canGenerateReport()
private void
createReportFooter(org.apache.maven.doxia.sink.Sink sink)
Create the HTML footer for the report page.private void
createReportHeader(java.util.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, java.io.File sourceDirectory, java.io.File grammarFile, java.lang.String linkPath)
Create a table row containing a link to the JJDoc report for a grammar file.void
executeReport(java.util.Locale locale)
Run the actual report.void
generate(org.apache.maven.doxia.sink.Sink sink, java.util.Locale locale)
private java.util.ResourceBundle
getBundle(java.util.Locale locale)
Get the resource bundle for the report text.java.lang.String
getDescription(java.util.Locale locale)
private java.io.File
getJJDocOutputDirectory()
Get the output directory of the JJDoc files, i.e.java.lang.String
getName(java.util.Locale locale)
protected java.lang.String
getOutputDirectory()
Get the output directory of the report if run directly from the command line.private java.lang.String
getOutputFileExtension()
java.lang.String
getOutputName()
private java.io.File[]
getSourceDirectories()
Get the source directories that should be scanned for grammar files.private JJDoc
newJJDoc()
Creates a new facade to invoke JJDoc.private GrammarInfo[]
scanForGrammars(java.io.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
-
-
-
-
Field Detail
-
sourceDirectories
@Parameter private java.io.File[] 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
@Parameter(defaultValue="${basedir}/src/main/javacc") private java.io.File defaultGrammarDirectoryJavaCC
The default source directory for hand-crafted grammar files.
-
defaultGrammarDirectoryJJTree
@Parameter(defaultValue="${project.build.directory}/generated-sources/jjtree") private java.io.File defaultGrammarDirectoryJJTree
The default source directory for grammar files generated by JJTree.
-
defaultGrammarDirectoryJTB
@Parameter(defaultValue="${project.build.directory}/generated-sources/jtb") private java.io.File defaultGrammarDirectoryJTB
The default source directory for grammar files generated by JTB.
-
jjdocDirectory
@Parameter(defaultValue="jjdoc") private java.lang.String 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 java.io.File outputDirectory
The 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 java.lang.String grammarEncoding
The file encoding to use for reading the grammar files.- Since:
- 2.6
-
cssHref
@Parameter(property="javacc.cssHref") private java.lang.String 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
@Parameter(property="javacc.text") private java.lang.Boolean 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
@Parameter(property="javacc.bnf") private java.lang.Boolean 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 oneTable
This 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.
-
-
Method Detail
-
getOutputDirectory
protected java.lang.String 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:
AbstractMavenReport.getOutputDirectory()
-
getJJDocOutputDirectory
private java.io.File 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
private java.io.File[] 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
public java.lang.String getName(java.util.Locale locale)
- Parameters:
locale
- The locale to use for this report.- Returns:
- The name of this report.
- See Also:
MavenReport.getName(java.util.Locale)
-
getDescription
public java.lang.String getDescription(java.util.Locale locale)
- Parameters:
locale
- The locale to use for this report.- Returns:
- The description of this report.
- See Also:
MavenReport.getDescription(java.util.Locale)
-
getOutputName
public java.lang.String getOutputName()
- Returns:
- The name of the main report file.
- See Also:
MavenReport.getOutputName()
-
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:
MavenReport.canGenerateReport()
-
executeReport
public void executeReport(java.util.Locale locale) throws org.apache.maven.reporting.MavenReportException
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
private java.lang.String 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
private void createReportHeader(java.util.ResourceBundle bundle, org.apache.maven.doxia.sink.Sink sink)
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, java.io.File sourceDirectory, java.io.File grammarFile, java.lang.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.
-
createReportFooter
private void createReportFooter(org.apache.maven.doxia.sink.Sink sink)
Create the HTML footer for the report page.- Parameters:
sink
- The sink to write the HTML report page.
-
newJJDoc
private JJDoc 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(java.io.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
private java.util.ResourceBundle getBundle(java.util.Locale locale)
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, java.util.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
-
-