From 0d5ecebd4eb8498c95a084e59c472912ae5ef566 Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Fri, 14 Apr 2023 09:41:52 +0200 Subject: [PATCH] [core] Antlr - make more methods protected The abstract methods createPmdTerminal and createPmdError in AntlrGeneratedParserBase don't need to be public. They are just implementation. The language specific inner nodes (KotlinInnerNode, SwiftInnerNode) can be package private. Only the concrete subclasses are considered public API. --- .../adding_a_new_antlr_based_language.md | 18 +++++++++++------- docs/pages/release_notes.md | 4 +++- docs/pages/release_notes_pmd7.md | 5 +++-- .../impl/antlr4/AntlrGeneratedParserBase.java | 7 ++++--- .../sourceforge/pmd/lang/kotlin/ast/Kotlin.g4 | 4 ++-- .../sourceforge/pmd/lang/kotlin/ast/README.md | 4 ++-- .../pmd/lang/kotlin/ast/KotlinInnerNode.java | 3 +-- .../sourceforge/pmd/lang/swift/ast/Swift.g4 | 4 ++-- .../pmd/lang/swift/ast/SwiftInnerNode.java | 3 ++- 9 files changed, 30 insertions(+), 22 deletions(-) diff --git a/docs/pages/pmd/devdocs/major_contributions/adding_a_new_antlr_based_language.md b/docs/pages/pmd/devdocs/major_contributions/adding_a_new_antlr_based_language.md index bfb6197eff..7d2be2372a 100644 --- a/docs/pages/pmd/devdocs/major_contributions/adding_a_new_antlr_based_language.md +++ b/docs/pages/pmd/devdocs/major_contributions/adding_a_new_antlr_based_language.md @@ -75,20 +75,24 @@ definitely don't come for free. It is much effort and requires perseverance to i * a language specific inner node - these nodes represent the production rules from the grammar. In Antlr, they are called "ParserRuleContext". We call them "InnerNode". Use the base class from pmd-core - [`BaseAntlrInnerNode`](https://github.com/pmd/pmd/blob/pmd/7.0.x/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/impl/antlr4/BaseAntlrInnerNode.java) - . And example is [`SwiftInnerNode`](https://github.com/pmd/pmd/blob/pmd/7.0.x/pmd-swift/src/main/java/net/sourceforge/pmd/lang/swift/ast/SwiftInnerNode.java). + [`BaseAntlrInnerNode`](https://github.com/pmd/pmd/blob/master/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/impl/antlr4/BaseAntlrInnerNode.java) + . And example is [`SwiftInnerNode`](https://github.com/pmd/pmd/blob/master/pmd-swift/src/main/java/net/sourceforge/pmd/lang/swift/ast/SwiftInnerNode.java). + Note that this language specific inner node is package-private, as it is only the base class for the concrete + nodes generated by ANLTR. * a language specific root node - this provides the root of the AST and our parser will return subtypes of this node. The root node itself is a "InnerNode". - See [`SwiftRootNode`](https://github.com/pmd/pmd/blob/pmd/7.0.x/pmd-swift/src/main/java/net/sourceforge/pmd/lang/swift/ast/SwiftRootNode.java). + See [`SwiftRootNode`](https://github.com/pmd/pmd/blob/master/pmd-swift/src/main/java/net/sourceforge/pmd/lang/swift/ast/SwiftRootNode.java). + Note that this language specific root node is package-private, as it is only the base class for the concrete + node generated by ANLTR. * a language specific terminal node. - See [`SwiftTerminalNode`](https://github.com/pmd/pmd/blob/pmd/7.0.x/pmd-swift/src/main/java/net/sourceforge/pmd/lang/swift/ast/SwiftTerminalNode.java). + See [`SwiftTerminalNode`](https://github.com/pmd/pmd/blob/master/pmd-swift/src/main/java/net/sourceforge/pmd/lang/swift/ast/SwiftTerminalNode.java). * a language specific error node. - See [`SwiftErrorNode`](https://github.com/pmd/pmd/blob/pmd/7.0.x/pmd-swift/src/main/java/net/sourceforge/pmd/lang/swift/ast/SwiftErrorNode.java). + See [`SwiftErrorNode`](https://github.com/pmd/pmd/blob/master/pmd-swift/src/main/java/net/sourceforge/pmd/lang/swift/ast/SwiftErrorNode.java). * In order for the generated code to match and use our custom classes, we have a common ant script, that fiddles with - the generated code. The ant script is [`antlr4-wrapper.xml`](https://github.com/pmd/pmd/blob/pmd/7.0.x/antlr4-wrapper.xml) and + the generated code. The ant script is [`antlr4-wrapper.xml`](https://github.com/pmd/pmd/blob/master/antlr4-wrapper.xml) and does not need to be adjusted - it has plenty of parameters to set. The ant script is added in the language module's `pom.xml` where the parameters are set (e.g. name of root name class). Have a look at - Swift's example: [`pmd-swift/pom.xml`](https://github.com/pmd/pmd/blob/pmd/7.0.x/pmd-swift/pom.xml). + Swift's example: [`pmd-swift/pom.xml`](https://github.com/pmd/pmd/blob/master/pmd-swift/pom.xml). * You can add additional methods in your "InnerNode" (e.g. `SwiftInnerNode`) that are available on all nodes. But on most cases you won't need to do anything. diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md index cd313c8362..3376a48d59 100644 --- a/docs/pages/release_notes.md +++ b/docs/pages/release_notes.md @@ -43,7 +43,9 @@ The remaining section describe the complete release notes for 7.0.0. * Moved the two classes {% jdoc core::cpd.impl.AntlrTokenizer %} and {% jdoc core::cpd.impl.JavaCCTokenizer %} from `internal` package into package {% jdoc_package core::cpd.impl %}. These two classes are part of the API and are base classes for CPD language implementations. -* `AntlrBaseRule` is gone in favor of {% jdoc core::pmd.lang.rule.AbstractVisitorRule %}. +* `AntlrBaseRule` is gone in favor of {% jdoc core::lang.rule.AbstractVisitorRule %}. +* The classes {% jdoc kotlin::lang.kotlin.ast.KotlinInnerNode %} and {% jdoc swift::lang.swift.ast.SwiftInnerNode %} + are package-private now. #### Fixed Issues: * java-codestyle diff --git a/docs/pages/release_notes_pmd7.md b/docs/pages/release_notes_pmd7.md index 2fe6c79009..d83c4cfff8 100644 --- a/docs/pages/release_notes_pmd7.md +++ b/docs/pages/release_notes_pmd7.md @@ -753,8 +753,9 @@ until the next major release, but it is recommended to stop using them. * Moved the two classes {% jdoc core::cpd.impl.AntlrTokenizer %} and {% jdoc core::cpd.impl.JavaCCTokenizer %} from `internal` package into package {% jdoc_package core::cpd.impl %}. These two classes are part of the API and are base classes for CPD language implementations. Since 7.0.0-rc2. -* `AntlrBaseRule` is gone in favor of {% jdoc core::pmd.lang.rule.AbstractVisitorRule %}. Since 7.0.0-rc2. - +* `AntlrBaseRule` is gone in favor of {% jdoc core::lang.rule.AbstractVisitorRule %}. Since 7.0.0-rc2. +* The classes {% jdoc kotlin::lang.kotlin.ast.KotlinInnerNode %} and {% jdoc swift::lang.swift.ast.SwiftInnerNode %} + are package-private now. Since 7.0.0-rc2. ### XPath 3.1 support diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/impl/antlr4/AntlrGeneratedParserBase.java b/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/impl/antlr4/AntlrGeneratedParserBase.java index edf18dbedb..6f2750966a 100644 --- a/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/impl/antlr4/AntlrGeneratedParserBase.java +++ b/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/impl/antlr4/AntlrGeneratedParserBase.java @@ -31,7 +31,8 @@ import net.sourceforge.pmd.lang.ast.Node; * which stores the XPath names of the generated nodes (and terminals). * *

Additional members can be added to a parser with {@code @parser::members { ... }} - * in the g4 file. + * in the g4 file. That's how the implementations for {@link #createPmdTerminal(ParserRuleContext, Token)} + * and {@link #createPmdError(ParserRuleContext, Token)} can be added. */ public abstract class AntlrGeneratedParserBase> extends Parser { @@ -52,9 +53,9 @@ public abstract class AntlrGeneratedParserBase> extends P // Those two need to return a node that implements eg SwiftNode - public abstract BaseAntlrTerminalNode createPmdTerminal(ParserRuleContext parent, Token t); + protected abstract BaseAntlrTerminalNode createPmdTerminal(ParserRuleContext parent, Token t); - public abstract BaseAntlrErrorNode createPmdError(ParserRuleContext parent, Token t); + protected abstract BaseAntlrErrorNode createPmdError(ParserRuleContext parent, Token t); protected Node asPmdNode(RuleContext ctx) { diff --git a/pmd-kotlin/src/main/antlr4/net/sourceforge/pmd/lang/kotlin/ast/Kotlin.g4 b/pmd-kotlin/src/main/antlr4/net/sourceforge/pmd/lang/kotlin/ast/Kotlin.g4 index 282b737351..16e602e2cc 100644 --- a/pmd-kotlin/src/main/antlr4/net/sourceforge/pmd/lang/kotlin/ast/Kotlin.g4 +++ b/pmd-kotlin/src/main/antlr4/net/sourceforge/pmd/lang/kotlin/ast/Kotlin.g4 @@ -15,12 +15,12 @@ import net.sourceforge.pmd.lang.ast.AstVisitor; static final AntlrNameDictionary DICO = new KotlinNameDictionary(VOCABULARY, ruleNames); @Override - public KotlinTerminalNode createPmdTerminal(ParserRuleContext parent, Token t) { + protected KotlinTerminalNode createPmdTerminal(ParserRuleContext parent, Token t) { return new KotlinTerminalNode(t); } @Override - public KotlinErrorNode createPmdError(ParserRuleContext parent, Token t) { + protected KotlinErrorNode createPmdError(ParserRuleContext parent, Token t) { return new KotlinErrorNode(t); } } diff --git a/pmd-kotlin/src/main/antlr4/net/sourceforge/pmd/lang/kotlin/ast/README.md b/pmd-kotlin/src/main/antlr4/net/sourceforge/pmd/lang/kotlin/ast/README.md index 20361f9a64..0bce081a13 100644 --- a/pmd-kotlin/src/main/antlr4/net/sourceforge/pmd/lang/kotlin/ast/README.md +++ b/pmd-kotlin/src/main/antlr4/net/sourceforge/pmd/lang/kotlin/ast/README.md @@ -50,12 +50,12 @@ import net.sourceforge.pmd.lang.ast.AstVisitor; static final AntlrNameDictionary DICO = new KotlinNameDictionary(VOCABULARY, ruleNames); @Override - public KotlinTerminalNode createPmdTerminal(ParserRuleContext parent, Token t) { + protected KotlinTerminalNode createPmdTerminal(ParserRuleContext parent, Token t) { return new KotlinTerminalNode(t); } @Override - public KotlinErrorNode createPmdError(ParserRuleContext parent, Token t) { + protected KotlinErrorNode createPmdError(ParserRuleContext parent, Token t) { return new KotlinErrorNode(t); } } diff --git a/pmd-kotlin/src/main/java/net/sourceforge/pmd/lang/kotlin/ast/KotlinInnerNode.java b/pmd-kotlin/src/main/java/net/sourceforge/pmd/lang/kotlin/ast/KotlinInnerNode.java index a6d58699ae..683f78b4de 100644 --- a/pmd-kotlin/src/main/java/net/sourceforge/pmd/lang/kotlin/ast/KotlinInnerNode.java +++ b/pmd-kotlin/src/main/java/net/sourceforge/pmd/lang/kotlin/ast/KotlinInnerNode.java @@ -9,8 +9,7 @@ import org.antlr.v4.runtime.ParserRuleContext; import net.sourceforge.pmd.lang.ast.AstVisitor; import net.sourceforge.pmd.lang.ast.impl.antlr4.BaseAntlrInnerNode; -public abstract class KotlinInnerNode - extends BaseAntlrInnerNode implements KotlinNode { +abstract class KotlinInnerNode extends BaseAntlrInnerNode implements KotlinNode { KotlinInnerNode(ParserRuleContext parent, int invokingStateNumber) { super(parent, invokingStateNumber); diff --git a/pmd-swift/src/main/antlr4/net/sourceforge/pmd/lang/swift/ast/Swift.g4 b/pmd-swift/src/main/antlr4/net/sourceforge/pmd/lang/swift/ast/Swift.g4 index 7d9bd13ff6..17c2e3f934 100644 --- a/pmd-swift/src/main/antlr4/net/sourceforge/pmd/lang/swift/ast/Swift.g4 +++ b/pmd-swift/src/main/antlr4/net/sourceforge/pmd/lang/swift/ast/Swift.g4 @@ -44,12 +44,12 @@ import net.sourceforge.pmd.lang.ast.AstVisitor; static final AntlrNameDictionary DICO = new SwiftNameDictionary(VOCABULARY, ruleNames); @Override - public SwiftTerminalNode createPmdTerminal(ParserRuleContext parent, Token t) { + protected SwiftTerminalNode createPmdTerminal(ParserRuleContext parent, Token t) { return new SwiftTerminalNode(t); } @Override - public SwiftErrorNode createPmdError(ParserRuleContext parent, Token t) { + protected SwiftErrorNode createPmdError(ParserRuleContext parent, Token t) { return new SwiftErrorNode(t); } } diff --git a/pmd-swift/src/main/java/net/sourceforge/pmd/lang/swift/ast/SwiftInnerNode.java b/pmd-swift/src/main/java/net/sourceforge/pmd/lang/swift/ast/SwiftInnerNode.java index ea082bfbdc..48c5de1aeb 100644 --- a/pmd-swift/src/main/java/net/sourceforge/pmd/lang/swift/ast/SwiftInnerNode.java +++ b/pmd-swift/src/main/java/net/sourceforge/pmd/lang/swift/ast/SwiftInnerNode.java @@ -9,7 +9,8 @@ import org.antlr.v4.runtime.ParserRuleContext; import net.sourceforge.pmd.lang.ast.AstVisitor; import net.sourceforge.pmd.lang.ast.impl.antlr4.BaseAntlrInnerNode; -public abstract class SwiftInnerNode +// package private base class +abstract class SwiftInnerNode extends BaseAntlrInnerNode implements SwiftNode { SwiftInnerNode() {