From 2aaaeb7253147715e16e36f8b5ea209e2147a6a5 Mon Sep 17 00:00:00 2001 From: Sam Pottinger Date: Mon, 4 Nov 2019 17:34:33 -0800 Subject: [PATCH] Cleaned up documentation for sttaic import handeling. --- .../mode/java/pdex/CompletionGenerator.java | 2 +- .../mode/java/pdex/ImportStatement.java | 91 ++++++++++++++++--- .../java/preproc/PdeParseTreeListener.java | 20 ++++ 3 files changed, 100 insertions(+), 13 deletions(-) diff --git a/java/src/processing/mode/java/pdex/CompletionGenerator.java b/java/src/processing/mode/java/pdex/CompletionGenerator.java index 1a9bf0009..17077ecd0 100644 --- a/java/src/processing/mode/java/pdex/CompletionGenerator.java +++ b/java/src/processing/mode/java/pdex/CompletionGenerator.java @@ -738,7 +738,7 @@ public class CompletionGenerator { return importListStream .map(list -> list.stream() .map(is -> { - if (is.getClassName().equals(finalClassName)) { + if (is.getMemberName().equals(finalClassName)) { return is.getFullClassName(); } else if (is.isStarredImport()) { return is.getPackageName() + "." + finalClassName; diff --git a/java/src/processing/mode/java/pdex/ImportStatement.java b/java/src/processing/mode/java/pdex/ImportStatement.java index 62f9cd81f..6d30c6d89 100644 --- a/java/src/processing/mode/java/pdex/ImportStatement.java +++ b/java/src/processing/mode/java/pdex/ImportStatement.java @@ -42,7 +42,7 @@ public class ImportStatement { * Full class name of the import with all packages * Ends with star for starred imports */ - private String className; + private String memberName; /** * Name of the package e.g. everything before last dot @@ -51,25 +51,43 @@ public class ImportStatement { private ImportStatement() { } + /** + * Create an import statement for a full package. + * + * @param cls The fully qualified name of the package. + * @return ImportStatement which imports all package members in a non-static context using a wildcard. + */ public static ImportStatement wholePackage(String pckg) { ImportStatement is = new ImportStatement(); is.packageName = pckg; - is.className = "*"; + is.memberName = "*"; is.isStarred = true; return is; } + /** + * Create an import statement for a single class. + * + * @param cls The fully qualified name of the class. + * @return ImportStatement which imports the class in a non-static context. + */ public static ImportStatement singleClass(String cls) { ImportStatement is = new ImportStatement(); int lastDot = cls.lastIndexOf('.'); - is.className = lastDot >= 0 ? cls.substring(lastDot+1) : cls; + is.memberName = lastDot >= 0 ? cls.substring(lastDot+1) : cls; is.packageName = lastDot >= 0 ? cls.substring(0, lastDot) : ""; // is.isClass = true; return is; } - - + /** + * Prase an import statement from a fully qualified name. + * + * @param importString The fully qualified name from which an import statement should be built. This supports static + * prepended so both "java.util.List" and "static org.processing.package.Factory.build" are supported. Note that + * the static prepending is required if the import is static. + * @return + */ public static ImportStatement parse(String importString) { Matcher matcher = SourceUtils.IMPORT_REGEX_NO_KEYWORD.matcher(importString); if (!matcher.find()) return null; @@ -77,6 +95,13 @@ public class ImportStatement { return parse(matcher.toMatchResult()); } + /** + * Parse an import statement from a regex match found via SourceUtils.*REGEX*. + * + * @param match The regex match from which an import statement should be built. Can be from IMPORT_REGEX_NO_KEYWORD or + * IMPORT_REGEX or equivalent. + * @return Newly parsed import statement information. + */ public static ImportStatement parse(MatchResult match) { ImportStatement is = new ImportStatement(); @@ -94,42 +119,84 @@ public class ImportStatement { int periodOfContainingTypeName = withContainingTypeNameAtEnd.lastIndexOf("."); String containingTypeName = withContainingTypeNameAtEnd.substring(periodOfContainingTypeName + 1); is.packageName = withContainingTypeNameAtEnd.substring(0, periodOfContainingTypeName); - is.className = containingTypeName + "." + memberName; + is.memberName = containingTypeName + "." + memberName; } else { is.packageName = endsWithPeriod ? pckg.substring(0, pckg.length() - 1) : pckg; - is.className = memberName; + is.memberName = memberName; } return is; } + /** + * Get the source line needed to execute this import. + * + * @return The java code required for executing this import. + */ public String getFullSourceLine() { - return importKw + " " + (isStatic ? (staticKw + " ") : "") + packageName + "." + className + ";"; + return importKw + " " + (isStatic ? (staticKw + " ") : "") + packageName + "." + memberName + ";"; } + /** + * Get the fully qualified member name which includes the package path. + * + * @return The fully qualified member name including the parent class. This is "java.util.List" in the case of + * "import java.util.List". Note that, in the case of static imports, it will include the member imported so + * "org.processing.package.Factory.build" would be returned for + * "import static org.processing.package.Factory.build". + */ public String getFullClassName(){ - return packageName + "." + className; + return packageName + "." + memberName; } - public String getClassName(){ - return className; + /** + * Get the end of the import statement with the type to be imported. + * + * @return This is the class name (List) in the case of "import java.util.List" or "*" in the case of a wildcard. For + * static imports this will be the member within the containing class (Factory.build in the case of + * "import static org.processing.package.Factory.build"). + */ + public String getMemberName(){ + return memberName; } + /** + * Get the package from which the import is being made. + * + * @return The package "java.util" from "import java.util.List". Note that, in the case of wildcards, the wildcard + * will be in the member name and not the class name. + */ public String getPackageName(){ return packageName; } + /** + * Determine if this import is a wildcard import. + * + * @return True if the FQN (fully qualified name) ends in a wildcard and false otherwise. + */ public boolean isStarredImport() { return isStarred; } + /** + * Determine if this import statement is a static import. + * + * @return True if of the form "import static {FQN}" where FQN refers to the fully qualified name and false otherwise. + */ public boolean isStaticImport() { return isStatic; } + /** + * Check if the import statements refer to the same import target. + * + * @param is The other import statement. + * @return True of the two ImportStatements refer to the same import target and false otherwise. + */ public boolean isSameAs(ImportStatement is) { return packageName.equals(is.packageName) && - className.equals(is.className) && + memberName.equals(is.memberName) && isStatic == is.isStatic; } } \ No newline at end of file diff --git a/java/src/processing/mode/java/preproc/PdeParseTreeListener.java b/java/src/processing/mode/java/preproc/PdeParseTreeListener.java index 9c12c6f3f..294fbf6c0 100644 --- a/java/src/processing/mode/java/preproc/PdeParseTreeListener.java +++ b/java/src/processing/mode/java/preproc/PdeParseTreeListener.java @@ -1289,10 +1289,30 @@ public class PdeParseTreeListener extends ProcessingBaseListener { return TextTransform.Edit.delete(start.getStartIndex(), start.getText().length()); } + /* + * ================================================ + * === Utility functions for import statements. === + * ================================================ + */ + + /** + * Create a set of non-static imports given the fully qualified names (FQNs) for the types to be imported. + * + * @param fullyQualifiedNames The fully qualified names of the types to be imported. This should be like + * "java.util.List". Supports wildcards. + * @return Import statements for the listed types. + */ private List createPlainImportStatementInfos(List fullyQualifiedNames) { return fullyQualifiedNames.stream().map(this::createPlainImportStatementInfo).collect(Collectors.toList()); } + /** + * Create a single non-static import given the fully qualified name (FQN) + * + * @param fullyQualifiedName The fully qualified name of the types to be imported. This should be like + * "java.util.List". Supports wildcards. + * @return Newly created ImportStatement. + */ private ImportStatement createPlainImportStatementInfo(String fullyQualifiedName) { return ImportStatement.parse(fullyQualifiedName); }