From 6549c585a0be267c604657d0fcf392762e256837 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Fournier?= Date: Thu, 24 Mar 2022 22:07:28 +0100 Subject: [PATCH 1/4] Update release notes --- docs/pages/release_notes.md | 45 +++++++++++++++++++ .../pmd/lang/xml/rule/DomXPathRule.java | 2 + 2 files changed, 47 insertions(+) diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md index ae817d64cb..282bf63c6a 100644 --- a/docs/pages/release_notes.md +++ b/docs/pages/release_notes.md @@ -14,6 +14,51 @@ This is a {{ site.pmd.release_type }} release. ### New and noteworthy +#### Better XML XPath support + +The new rule class {% jdoc xml::lang.xml.rule.DomXPathRule %} is intended to replace +usage of the `XPathRule` for XML rules. This rule executes the XPath query in a different +way, which sticks to the XPath specification. This means the expression is interpreted +the same way in PMD as in all other XPath development tools that stick to the standard. +You can for instance test the expression in an online XPath editor. + +Prefer using this class to define XPath rules: replace the value of the `class` +attribute with `net.sourceforge.pmd.lang.xml.rule.DomXPathRule` like so: +```xml + + + + + + + + + +``` + +The rule is more powerful than `XPathRule`, as it can now handle XML namespaces, +comments and processing instructions. Please refer to the Javadoc of {% jdoc xml::lang.xml.rule.DomXPathRule %} +for information about the differences with `XPathRule` and examples. + +`XPathRule` is still perfectly supported for all other languages, including Apex and Java. + +#### New XPath functions + +The new XPath functions `pmd:startLine`, `pmd:endLine`, `pmd:startColumn`, +and `pmd:endColumn` are now available in XPath rules for all languages. They +replace the node attributes `@BeginLine`, `@EndLine` and such. These attributes +will be deprecated in a future release. + +Please refer to [the documentation](https://pmd.github.io/latest/pmd_userdocs_extending_writing_xpath_rules.html#pmd-extension-functions) of these functions for more information, including usage samples. + +Note that the function `pmd:endColumn` returns an exclusive index, while the +attribute `@EndColumn` is inclusive. This is for forward compatibility with PMD 7, +which uses exclusive end indices. #### New programmatic API diff --git a/pmd-xml/src/main/java/net/sourceforge/pmd/lang/xml/rule/DomXPathRule.java b/pmd-xml/src/main/java/net/sourceforge/pmd/lang/xml/rule/DomXPathRule.java index f3440dd83f..57ba692d0a 100644 --- a/pmd-xml/src/main/java/net/sourceforge/pmd/lang/xml/rule/DomXPathRule.java +++ b/pmd-xml/src/main/java/net/sourceforge/pmd/lang/xml/rule/DomXPathRule.java @@ -127,6 +127,8 @@ public class DomXPathRule extends AbstractRule { public DomXPathRule() { definePropertyDescriptor(XPATH_EXPR); definePropertyDescriptor(DEFAULT_NS_URI); + // for compatibility, but is ignored. + definePropertyDescriptor(XPathRule.VERSION_DESCRIPTOR); } From 6e1e8a6adc741650549ef8542485085350a5841d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Fournier?= Date: Thu, 24 Mar 2022 22:24:26 +0100 Subject: [PATCH 2/4] Deprecate xpath attrs for lines/cols --- docs/pages/release_notes.md | 8 +++++++- .../src/main/java/net/sourceforge/pmd/lang/ast/Node.java | 4 ++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md index 282bf63c6a..192d0023e2 100644 --- a/docs/pages/release_notes.md +++ b/docs/pages/release_notes.md @@ -52,7 +52,8 @@ for information about the differences with `XPathRule` and examples. The new XPath functions `pmd:startLine`, `pmd:endLine`, `pmd:startColumn`, and `pmd:endColumn` are now available in XPath rules for all languages. They replace the node attributes `@BeginLine`, `@EndLine` and such. These attributes -will be deprecated in a future release. +are now deprecated for removal (from the XPath API, not the Java getter). + Please refer to [the documentation](https://pmd.github.io/latest/pmd_userdocs_extending_writing_xpath_rules.html#pmd-extension-functions) of these functions for more information, including usage samples. @@ -124,6 +125,11 @@ The CLI itself remains compatible, if you run PMD via command-line, no action is The whole class however was deprecated long ago already with 6.30.0. It is internal API and should not be used. +* The XPath attributes `@BeginLine`, `@EndLine`, `@BeginColumn` and `@EndColumn`, +available on all nodes, are deprecated. They should be replaced with calls to the +new functions `pmd:startLine`, `pmd:endLine`, `pmd:startColumn`, and `pmd:endColumn`. +See [New XPath functions](#new-xpath-functions). + #### Experimental APIs * Together with the [new programmatic API](#new-programmatic-api) the interface diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java b/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java index 5beb352e6d..c54c7e5b46 100644 --- a/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java +++ b/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java @@ -178,13 +178,17 @@ public interface Node { */ boolean hasImageEqualTo(String image); + @DeprecatedAttribute(replaceWith = "pmd:startLine(.)") int getBeginLine(); + @DeprecatedAttribute(replaceWith = "pmd:startColumn(.)") int getBeginColumn(); + @DeprecatedAttribute(replaceWith = "pmd:endLine(.)") int getEndLine(); // FIXME should not be inclusive + @DeprecatedAttribute(replaceWith = "pmd:endColumn(.)") int getEndColumn(); From 586a9011468f4a0a16b3babe29c9ad8efe368bf8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Fournier?= Date: Thu, 24 Mar 2022 22:24:31 +0100 Subject: [PATCH 3/4] REVERTME Revert "Deprecate xpath attrs for lines/cols" This reverts commit 6e1e8a6adc741650549ef8542485085350a5841d. Note for future: I tried to deprecate the XPath attributes for `@BeginLine`, `@EndLine` etc, but there's a rule I can't port easily without XPath 3: OneDeclarationPerLine. It has this thing: ``` distinct-values(FieldDeclaration/VariableExpression/@BeginLine) ``` In XPath 3 you can write this ``` distinct-values(FieldDeclaration/VariableExpression ! pmd:startLine) ``` But I'm not sure how to do this in XPath 2, so I've reverted the commit, we can do that later. --- docs/pages/release_notes.md | 8 +------- .../src/main/java/net/sourceforge/pmd/lang/ast/Node.java | 4 ---- 2 files changed, 1 insertion(+), 11 deletions(-) diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md index 192d0023e2..282bf63c6a 100644 --- a/docs/pages/release_notes.md +++ b/docs/pages/release_notes.md @@ -52,8 +52,7 @@ for information about the differences with `XPathRule` and examples. The new XPath functions `pmd:startLine`, `pmd:endLine`, `pmd:startColumn`, and `pmd:endColumn` are now available in XPath rules for all languages. They replace the node attributes `@BeginLine`, `@EndLine` and such. These attributes -are now deprecated for removal (from the XPath API, not the Java getter). - +will be deprecated in a future release. Please refer to [the documentation](https://pmd.github.io/latest/pmd_userdocs_extending_writing_xpath_rules.html#pmd-extension-functions) of these functions for more information, including usage samples. @@ -125,11 +124,6 @@ The CLI itself remains compatible, if you run PMD via command-line, no action is The whole class however was deprecated long ago already with 6.30.0. It is internal API and should not be used. -* The XPath attributes `@BeginLine`, `@EndLine`, `@BeginColumn` and `@EndColumn`, -available on all nodes, are deprecated. They should be replaced with calls to the -new functions `pmd:startLine`, `pmd:endLine`, `pmd:startColumn`, and `pmd:endColumn`. -See [New XPath functions](#new-xpath-functions). - #### Experimental APIs * Together with the [new programmatic API](#new-programmatic-api) the interface diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java b/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java index c54c7e5b46..5beb352e6d 100644 --- a/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java +++ b/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java @@ -178,17 +178,13 @@ public interface Node { */ boolean hasImageEqualTo(String image); - @DeprecatedAttribute(replaceWith = "pmd:startLine(.)") int getBeginLine(); - @DeprecatedAttribute(replaceWith = "pmd:startColumn(.)") int getBeginColumn(); - @DeprecatedAttribute(replaceWith = "pmd:endLine(.)") int getEndLine(); // FIXME should not be inclusive - @DeprecatedAttribute(replaceWith = "pmd:endColumn(.)") int getEndColumn(); From cdf19cf24bf37d6d10735dcec7808a4d2389754f Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Fri, 25 Mar 2022 08:10:47 +0100 Subject: [PATCH 4/4] [doc] Update release notes (#2766, #3863, #3864) --- docs/pages/release_notes.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md index 282bf63c6a..ed24fe01e8 100644 --- a/docs/pages/release_notes.md +++ b/docs/pages/release_notes.md @@ -102,6 +102,9 @@ The CLI itself remains compatible, if you run PMD via command-line, no action is * [#3299](https://github.com/pmd/pmd/issues/3299): \[core] Deprecate system properties of PMDCommandLineInterface * doc * [#3812](https://github.com/pmd/pmd/issues/3812): \[doc] Documentation website table of contents broken on pages with many subheadings +* xml + * [#2766](https://github.com/pmd/pmd/issues/2766): \[xml] XMLNS prefix is not pre-declared in xpath query + * [#3863](https://github.com/pmd/pmd/issues/3863): \[xml] Make XPath rules work exactly as in the XPath spec ### API Changes