From 1ec4cf8353a79ec3948e6363d701d5fbfac7e2b7 Mon Sep 17 00:00:00 2001 From: Michael Ernst Date: Sun, 12 Jan 2025 20:01:48 -0800 Subject: [PATCH] Deprecate fields in `Signatures`: `FqBinaryNameRegex`, `FqBinaryNamePattern` --- CHANGELOG.md | 2 ++ .../plumelib/reflection/SignatureRegexes.java | 33 +++++++++++-------- .../org/plumelib/reflection/Signatures.java | 8 ++++- 3 files changed, 29 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dceb40ba..3795fc7f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,8 @@ - New method 'Signatures.internalFormToDotSeparatedIdentifiers' - Removed method `Signatures.isBinaryNameWithoutPackage`; use `Signatures.isIdentifier` +- Deprecated fields `Signatures.FqBinaryNameRegex` and `Signatures.FqBinaryNamePattern`; + use `Signatures.FullyQualifiedNameRegex` and `Signatures.FullyQualifiedNamePattern` instead. ## 1.1.4 (2024-10-09) diff --git a/src/main/java/org/plumelib/reflection/SignatureRegexes.java b/src/main/java/org/plumelib/reflection/SignatureRegexes.java index dad562c7..c6939e60 100644 --- a/src/main/java/org/plumelib/reflection/SignatureRegexes.java +++ b/src/main/java/org/plumelib/reflection/SignatureRegexes.java @@ -147,7 +147,12 @@ private SignatureRegexes() { private static final @Regex String KEYWORD_OR_LITERAL = ALTERNATE(KEYWORD, "true", "false", "null"); - /** A regex that matches Java identifier tokens, as defined by the Java grammar. */ + /** + * A regex that matches Java identifier tokens, as defined by the Java grammar. + * + *

This includes identifiers containing "$". The "$" character is permitted but strongly + * discouraged in source code. However, "$" often occurs in identifiers in class files. + */ private static final @Regex String IDENTIFIER_TOKEN = "[A-Za-z_$][A-Za-z_$0-9]*"; /** A grouped regex that matches identifiers. */ @@ -162,10 +167,6 @@ private SignatureRegexes() { private static final @Regex String DOT_SEPARATED_IDENTIFIERS = IDENTIFIER + ANY("\\." + IDENTIFIER); - /** An unanchored regex that matches slash-separated identifiers. */ - private static final @Regex String SLASH_SEPARATED_IDENTIFIERS = - IDENTIFIER + ANY("/" + IDENTIFIER); - /** A regex that matches the nested-class part of a class name, for one nested class. */ private static final @Regex String NESTED_ONE = "\\$[A-Za-z_0-9]+"; @@ -174,14 +175,14 @@ private SignatureRegexes() { */ private static final @Regex String NESTED = ANY(NESTED_ONE); - /** An unanchored regex that matches BinaryName strings. */ - private static final @Regex String BINARY_NAME = DOT_SEPARATED_IDENTIFIERS + NESTED; + /** A regex that matches BinaryName strings, which are dot-separated identifiers. */ + private static final @Regex String BINARY_NAME = DOT_SEPARATED_IDENTIFIERS; /** A regex that matches the array part of a type, which might be the empty string. */ private static final @Regex String ARRAY = "(\\[\\])*"; - /** A regex that matches InternalForm strings. */ - public static final @Regex String INTERNAL_FORM = SLASH_SEPARATED_IDENTIFIERS + NESTED; + /** A regex that matches InternalForm strings. These are slash-separated identifiers. */ + public static final @Regex String INTERNAL_FORM = IDENTIFIER + ANY("/" + IDENTIFIER); /** A regex that matches ClassGetName, for non-primitive, non-array types. */ private static final @Regex String CLASS_GET_NAME_NONPRIMITIVE_NONARRAY = @@ -278,18 +279,24 @@ private SignatureRegexes() { public static final Pattern FieldDescriptorForPrimitivePattern = Pattern.compile(FieldDescriptorForPrimitiveRegex); - /** An anchored regex that matches FqBinaryName strings. */ + /** Deprecated. Use {@link FullyQualifiedNameRegex} instead. */ public static final @Regex String FqBinaryNameRegex = ANCHORED("(" + PRIMITIVE_TYPE + "|" + BINARY_NAME + ")" + ARRAY); - /** An anchored pattern that matches FqBinaryName strings. */ + /** Deprecated. Use {@link FullyQualifiedNamePattern} instead. */ public static final Pattern FqBinaryNamePattern = Pattern.compile(FqBinaryNameRegex); - /** An anchored regex that matches FullyQualifiedName strings. */ + /** + * An anchored regex that matches FullyQualifiedName and FqBinaryName strings (which are + * syntactically identical but are interpreted differently). + */ public static final @Regex String FullyQualifiedNameRegex = ANCHORED("(" + PRIMITIVE_TYPE + "|" + DOT_SEPARATED_IDENTIFIERS + ")" + ARRAY); - /** An anchored pattern that matches FullyQualifiedName strings. */ + /** + * An anchored pattern that matches FullyQualifiedName and FqBinaryName strings (which are + * syntactically identical but are interpreted differently). + */ public static final Pattern FullyQualifiedNamePattern = Pattern.compile(FullyQualifiedNameRegex); /** An anchored regex that matches Identifier strings. */ diff --git a/src/main/java/org/plumelib/reflection/Signatures.java b/src/main/java/org/plumelib/reflection/Signatures.java index d330e575..84b3e2c3 100644 --- a/src/main/java/org/plumelib/reflection/Signatures.java +++ b/src/main/java/org/plumelib/reflection/Signatures.java @@ -281,19 +281,25 @@ public static boolean isFieldDescriptorForPrimitive(String s) { * Returns true if the argument has the format of a FqBinaryName. The type it refers to might or * might not exist. * + *

This method has the same semantics as {@link isFullyQualifiedName}, because the syntactic + * formats are the same (though the interpretations of the strings differ). + * * @param s a string * @return true if the string is a @FqBinaryName */ @SuppressWarnings("signature") @EnsuresQualifierIf(result = true, expression = "#1", qualifier = FqBinaryName.class) public static boolean isFqBinaryName(String s) { - return SignatureRegexes.FqBinaryNamePattern.matcher(s).matches(); + return SignatureRegexes.FullyQualifiedNamePattern.matcher(s).matches(); } /** * Returns true if the argument has the format of a FullyQualifiedName. The type it refers to * might or might not exist. * + *

This method has the same semantics as {@link isFqBinaryName}, because the syntactic formats + * are the same (though the interpretations of the strings differ). + * * @param s a string * @return true if the string is a @FullyQualifiedName */