Merge branch 'pr-2675'

[core] Deprecate parser options #2675

docs/pages/release_notes.md

@@ -44,9 +44,16 @@ This is a {{ site.pmd.release_type }} release.
 
 #### Deprecated API
 
-##### For removal
-
 *   {% jdoc !!pmd-java::lang.java.ast.ASTThrowStatement#getFirstClassOrInterfaceTypeImage() %}
+*   {% jdoc !!core::Rule#getParserOptions() %}
+*   {% jdoc !!core::lang.Parser#getParserOptions() %}
+*   {% jdoc !!core::lang.AbstractParser %}
+*   {% jdoc apex::lang.apex.ApexParserOptions %}
+*   {% jdoc xml::lang.xml.XmlParserOptions %}
+*   {% jdoc xml::lang.xml.rule.XmlXpathRule %}
+*   Properties of {% jdoc xml::lang.xml.rule.AbstractXmlRule %}
+*   {% jdoc javascript::lang.ecmascript.EcmascriptParserOptions %}
+*   {% jdoc javascript::lang.ecmascript.rule.EcmascriptXPathRule %}
 
 ### External Contributions
 

pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/ApexParserOptions.java

@@ -6,6 +6,10 @@ package net.sourceforge.pmd.lang.apex;
 
 import net.sourceforge.pmd.lang.ParserOptions;
 
+/**
+ * @deprecated Not useful
+ */
+@Deprecated
 public class ApexParserOptions extends ParserOptions {
 
     // empty class for now, since we don't have extra options for Apex

pmd-core/src/main/java/net/sourceforge/pmd/Rule.java

@@ -255,7 +255,12 @@ public interface Rule extends PropertySource {
      * should return a new instance on each call.
      *
      * @return the parser options
+     *
+     * @deprecated This was never implemented and will never be. PMD
+     *     cannot parse files once per rule. Let this method assume
+     *     its default by not overriding it.
      */
+    @Deprecated
     ParserOptions getParserOptions();
 
     /**

pmd-core/src/main/java/net/sourceforge/pmd/lang/AbstractParser.java

@@ -10,7 +10,10 @@ import java.io.Reader;
  * This is a generic implementation of the Parser interface.
  *
  * @see Parser
+ *
+ * @deprecated This will become useless in PMD 7. Implement or use {@link Parser} directly
  */
+@Deprecated
 public abstract class AbstractParser implements Parser {
     protected final ParserOptions parserOptions;
 

pmd-core/src/main/java/net/sourceforge/pmd/lang/Parser.java

@@ -16,9 +16,13 @@ import net.sourceforge.pmd.lang.ast.ParseException;
  * @author Pieter_Van_Raemdonck - Application Engineers NV/SA - www.ae.be
  */
 public interface Parser {
+
     /**
      * Get the ParserOptions used by this Parser.
+     *
+     * @deprecated Parser options should be a parameter to {@link #parse(String, Reader)}
      */
+    @Deprecated
     ParserOptions getParserOptions();
 
     /**

pmd-core/src/main/java/net/sourceforge/pmd/lang/rule/AbstractRule.java

@@ -229,6 +229,7 @@ public abstract class AbstractRule extends AbstractPropertySource implements Rul
      * @see Rule#setPriority(RulePriority)
      */
     @Override
+    @Deprecated
     public ParserOptions getParserOptions() {
         return new ParserOptions();
     }

pmd-javascript/src/main/java/net/sourceforge/pmd/lang/ecmascript/EcmascriptParserOptions.java

@@ -13,7 +13,10 @@ import net.sourceforge.pmd.lang.ParserOptions;
 import net.sourceforge.pmd.properties.BooleanProperty;
 import net.sourceforge.pmd.properties.EnumeratedProperty;
 
-
+/**
+ * @deprecated Will be removed in 7.0 TODO refactor this into language versions?
+ */
+@Deprecated
 public class EcmascriptParserOptions extends ParserOptions {
 
     public enum Version {

pmd-javascript/src/main/java/net/sourceforge/pmd/lang/ecmascript/rule/EcmascriptXPathRule.java

@@ -12,7 +12,10 @@ import net.sourceforge.pmd.lang.ecmascript.EcmascriptParserOptions.Version;
 import net.sourceforge.pmd.lang.rule.XPathRule;
 import net.sourceforge.pmd.properties.PropertyDescriptor;
 
-
+/**
+ * @deprecated Parser options are deprecated, use {@link XPathRule} directly
+ */
+@Deprecated
 public class EcmascriptXPathRule extends XPathRule {
 
     private static final PropertyDescriptor<Boolean> RECORDING_COMMENTS_DESCRIPTOR = EcmascriptParserOptions.RECORDING_COMMENTS_DESCRIPTOR;

pmd-xml/src/main/java/net/sourceforge/pmd/lang/xml/XmlParserOptions.java

@@ -16,31 +16,36 @@ import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.lang.ParserOptions;
 import net.sourceforge.pmd.properties.BooleanProperty;
 
+/**
+ * @deprecated Parser options will be removed with 7.0, these options
+ *             will assume their default values then.
+ */
+@Deprecated
 public class XmlParserOptions extends ParserOptions {
 
     // Note: The UI order values are chosen to be larger than those built into
     // XPathRule.
     public static final BooleanProperty COALESCING_DESCRIPTOR = new BooleanProperty("coalescing",
-            "Specifies that the XML parser convert CDATA nodes to Text nodes and append it to the adjacent (if any) text node.",
+            "deprecated!Specifies that the XML parser convert CDATA nodes to Text nodes and append it to the adjacent (if any) text node.",
             Boolean.FALSE, 3.0f);
     public static final BooleanProperty EXPAND_ENTITY_REFERENCES_DESCRIPTOR = new BooleanProperty(
-            "expandEntityReferences", "Specifies that the XML parser expand entity reference nodes.", Boolean.TRUE,
+            "expandEntityReferences", "deprecated!Specifies that the XML parser expand entity reference nodes.", Boolean.TRUE,
             4.0f);
     public static final BooleanProperty IGNORING_COMMENTS_DESCRIPTOR = new BooleanProperty("ignoringComments",
-            "Specifies that the XML parser ignore comments.", Boolean.FALSE, 5.0f);
+            "deprecated!Specifies that the XML parser ignore comments.", Boolean.FALSE, 5.0f);
     public static final BooleanProperty IGNORING_ELEMENT_CONTENT_WHITESPACE_DESCRIPTOR = new BooleanProperty(
             "ignoringElementContentWhitespace",
-            "Specifies that the XML parser eliminate whitespace in element content.  Setting this to 'true' will force validating.",
+            "deprecated!Specifies that the XML parser eliminate whitespace in element content.  Setting this to 'true' will force validating.",
             Boolean.FALSE, 6.0f);
     public static final BooleanProperty NAMESPACE_AWARE_DESCRIPTOR = new BooleanProperty("namespaceAware",
-            "Specifies that the XML parser will provide support for XML namespaces.", Boolean.TRUE, 7.0f);
+            "deprecated!Specifies that the XML parser will provide support for XML namespaces.", Boolean.TRUE, 7.0f);
     public static final BooleanProperty VALIDATING_DESCRIPTOR = new BooleanProperty("validating",
-            "Specifies that the XML parser will validate documents as they are parsed.  This only works for DTDs.",
+            "deprecated!Specifies that the XML parser will validate documents as they are parsed.  This only works for DTDs.",
             Boolean.FALSE, 8.0f);
     public static final BooleanProperty XINCLUDE_AWARE_DESCRIPTOR = new BooleanProperty("xincludeAware",
-            "Specifies that the XML parser will process XInclude markup.", Boolean.FALSE, 9.0f);
+            "deprecated!Specifies that the XML parser will process XInclude markup.", Boolean.FALSE, 9.0f);
     public static final BooleanProperty LOOKUP_DESCRIPTOR_DTD = new BooleanProperty("xincludeAware",
-            "Specifies whether XML parser will attempt to lookup the DTD.", Boolean.FALSE, 10.0f);
+            "deprecated!Specifies whether XML parser will attempt to lookup the DTD.", Boolean.FALSE, 10.0f);
 
     public static final EntityResolver SILENT_ENTITY_RESOLVER = new EntityResolver() {
         @Override

pmd-xml/src/main/java/net/sourceforge/pmd/lang/xml/rule/AbstractXmlRule.java

@@ -25,12 +25,19 @@ import net.sourceforge.pmd.properties.BooleanProperty;
  */
 public class AbstractXmlRule extends AbstractRule implements ImmutableLanguage {
 
+    @Deprecated
     public static final BooleanProperty COALESCING_DESCRIPTOR = XmlParserOptions.COALESCING_DESCRIPTOR;
+    @Deprecated
     public static final BooleanProperty EXPAND_ENTITY_REFERENCES_DESCRIPTOR = XmlParserOptions.EXPAND_ENTITY_REFERENCES_DESCRIPTOR;
+    @Deprecated
     public static final BooleanProperty IGNORING_COMMENTS_DESCRIPTOR = XmlParserOptions.IGNORING_COMMENTS_DESCRIPTOR;
+    @Deprecated
     public static final BooleanProperty IGNORING_ELEMENT_CONTENT_WHITESPACE_DESCRIPTOR = XmlParserOptions.IGNORING_ELEMENT_CONTENT_WHITESPACE_DESCRIPTOR;
+    @Deprecated
     public static final BooleanProperty NAMESPACE_AWARE_DESCRIPTOR = XmlParserOptions.NAMESPACE_AWARE_DESCRIPTOR;
+    @Deprecated
     public static final BooleanProperty VALIDATING_DESCRIPTOR = XmlParserOptions.VALIDATING_DESCRIPTOR;
+    @Deprecated
     public static final BooleanProperty XINCLUDE_AWARE_DESCRIPTOR = XmlParserOptions.XINCLUDE_AWARE_DESCRIPTOR;
 
     public AbstractXmlRule() {

pmd-xml/src/main/java/net/sourceforge/pmd/lang/xml/rule/XmlXPathRule.java

@@ -11,14 +11,25 @@ import net.sourceforge.pmd.lang.xml.XmlLanguageModule;
 import net.sourceforge.pmd.lang.xml.XmlParserOptions;
 import net.sourceforge.pmd.properties.BooleanProperty;
 
+/**
+ * @deprecated Parser options are deprecated, use {@link XPathRule} directly
+ */
+@Deprecated
 public class XmlXPathRule extends XPathRule {
 
+    @Deprecated
     public static final BooleanProperty COALESCING_DESCRIPTOR = XmlParserOptions.COALESCING_DESCRIPTOR;
+    @Deprecated
     public static final BooleanProperty EXPAND_ENTITY_REFERENCES_DESCRIPTOR = XmlParserOptions.EXPAND_ENTITY_REFERENCES_DESCRIPTOR;
+    @Deprecated
     public static final BooleanProperty IGNORING_COMMENTS_DESCRIPTOR = XmlParserOptions.IGNORING_COMMENTS_DESCRIPTOR;
+    @Deprecated
     public static final BooleanProperty IGNORING_ELEMENT_CONTENT_WHITESPACE_DESCRIPTOR = XmlParserOptions.IGNORING_ELEMENT_CONTENT_WHITESPACE_DESCRIPTOR;
+    @Deprecated
     public static final BooleanProperty NAMESPACE_AWARE_DESCRIPTOR = XmlParserOptions.NAMESPACE_AWARE_DESCRIPTOR;
+    @Deprecated
     public static final BooleanProperty VALIDATING_DESCRIPTOR = XmlParserOptions.VALIDATING_DESCRIPTOR;
+    @Deprecated
     public static final BooleanProperty XINCLUDE_AWARE_DESCRIPTOR = XmlParserOptions.XINCLUDE_AWARE_DESCRIPTOR;
 
     public XmlXPathRule() {