/*
* Copyright (c) 2014, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package jdk.jshell;
import java.util.Collection;
import java.util.List;
/**
* Provides analysis utilities for source code input.
* Optional functionality that provides for a richer interactive experience.
* Includes completion analysis:
* Is the input a complete snippet of code?
* Do I need to prompt for more input?
* Would adding a semicolon make it complete?
* Is there more than one snippet?
* etc.
* Also includes completion suggestions, as might be used in tab-completion.
*
*/
public abstract class SourceCodeAnalysis {
/**
* Given an input string, find the first snippet of code (one statement,
* definition, import, or expression) and evaluate if it is complete.
* @param input the input source string
* @return a CompletionInfo instance with location and completeness info
*/
public abstract CompletionInfo analyzeCompletion(String input);
/**
* Compute possible follow-ups for the given input.
* Uses information from the current {@code JShell} state, including
* type information, to filter the suggestions.
* @param input the user input, so far
* @param cursor the current position of the cursors in the given {@code input} text
* @param anchor outgoing parameter - when an option will be completed, the text between
* the anchor and cursor will be deleted and replaced with the given option
* @return list of candidate continuations of the given input.
*/
public abstract List<Suggestion> completionSuggestions(String input, int cursor, int[] anchor);
/**
* Compute documentation for the given user's input. Multiple {@code Documentation} objects may
* be returned when multiple elements match the user's input (like for overloaded methods).
* @param input the snippet the user wrote so far
* @param cursor the current position of the cursors in the given {@code input} text
* @param computeJavadoc true if the javadoc for the given input should be computed in
* addition to the signature
* @return the documentations for the given user's input, if multiple elements match the input,
* multiple {@code Documentation} objects are returned.
*/
public abstract List<Documentation> documentation(String input, int cursor, boolean computeJavadoc);
/**
* Infer the type of the given expression. The expression spans from the beginning of {@code code}
* to the given {@code cursor} position. Returns null if the type of the expression cannot
* be inferred.
*
* @param code the expression for which the type should be inferred
* @param cursor current cursor position in the given code
* @return the inferred type, or null if it cannot be inferred
*/
public abstract String analyzeType(String code, int cursor);
/**
* List qualified names known for the simple name in the given code immediately
* to the left of the given cursor position. The qualified names are gathered by inspecting the
* classpath used by eval (see {@link JShell#addToClasspath(java.lang.String)}).
*
* @param code the expression for which the candidate qualified names should be computed
* @param cursor current cursor position in the given code
* @return the known qualified names
*/
public abstract QualifiedNames listQualifiedNames(String code, int cursor);
/**
* Returns the wrapper information for the {@code Snippet}. The wrapper changes as
* the environment changes, so calls to this method at different times may
* yield different results.
*
* @param snippet the {@code Snippet} from which to retrieve the wrapper
* @return information on the wrapper
*/
public abstract SnippetWrapper wrapper(Snippet snippet);
/**
* Returns the wrapper information for the snippet within the
* input source string.
* <p>
* Wrapper information for malformed and incomplete
* snippets also generate wrappers. The list is in snippet encounter
* order. The wrapper changes as the environment changes, so calls to this
* method at different times may yield different results.
* <p>
* The input should be
* exactly one complete snippet of source code, that is, one expression,
* statement, variable declaration, method declaration, class declaration,
* or import.
* To break arbitrary input into individual complete snippets, use
* {@link SourceCodeAnalysis#analyzeCompletion(String)}.
* <p>
* The wrapper may not match that returned by
* {@link SourceCodeAnalysis#wrapper(Snippet) wrapper(Snippet)},
* were the source converted to a {@code Snippet}.
*
* @param input the source input from which to generate wrappers
* @return a list of wrapper information
*/
public abstract List<SnippetWrapper> wrappers(String input);
/**
* Returns a collection of {@code Snippet}s which might need updating if the
* given {@code Snippet} is updated. The returned collection is designed to
* be inclusive and may include many false positives.
*
* @param snippet the {@code Snippet} whose dependents are requested
* @return the collection of dependents
*/
public abstract Collection<Snippet> dependents(Snippet snippet);
/**
* Internal only constructor
*/
SourceCodeAnalysis() {}
/**
* The result of {@code analyzeCompletion(String input)}.
* Describes the completeness of the first snippet in the given input.
*/
public interface CompletionInfo {
/**
* The analyzed completeness of the input.
*
* @return an enum describing the completeness of the input string.
*/
Completeness completeness();
/**
* Input remaining after the complete part of the source.
*
* @return the portion of the input string that remains after the
* complete Snippet
*/
String remaining();
/**
* Source code for the first Snippet of code input. For example, first
* statement, or first method declaration. Trailing semicolons will be
* added, as needed.
*
* @return the source of the first encountered Snippet
*/
String source();
}
/**
* Describes the completeness of the given input.
*/
public enum Completeness {
/**
* The input is a complete source snippet (declaration or statement) as is.
*/
COMPLETE(true),
/**
* With this addition of a semicolon the input is a complete source snippet.
* This will only be returned when the end of input is encountered.
*/
COMPLETE_WITH_SEMI(true),
/**
* There must be further source beyond the given input in order for it
* to be complete. A semicolon would not complete it.
* This will only be returned when the end of input is encountered.
*/
DEFINITELY_INCOMPLETE(false),
/**
* A statement with a trailing (non-terminated) empty statement.
* Though technically it would be a complete statement
* with the addition of a semicolon, it is rare
* that that assumption is the desired behavior.
* The input is considered incomplete. Comments and white-space are
* still considered empty.
*/
CONSIDERED_INCOMPLETE(false),
/**
* An empty input.
* The input is considered incomplete. Comments and white-space are
* still considered empty.
*/
EMPTY(false),
/**
* The completeness of the input could not be determined because it
* contains errors. Error detection is not a goal of completeness
* analysis, however errors interfered with determining its completeness.
* The input is considered complete because evaluating is the best
* mechanism to get error information.
*/
UNKNOWN(true);
private final boolean isComplete;
Completeness(boolean isComplete) {
this.isComplete = isComplete;
}
/**
* Indicates whether the first snippet of source is complete.
* For example, "{@code x=}" is not
* complete, but "{@code x=2}" is complete, even though a subsequent line could
* make it "{@code x=2+2}". Already erroneous code is marked complete.
*
* @return {@code true} if the input is or begins a complete Snippet;
* otherwise {@code false}
*/
public boolean isComplete() {
return isComplete;
}
}
/**
* A candidate for continuation of the given user's input.
*/
public interface Suggestion {
/**
* The candidate continuation of the given user's input.
*
* @return the continuation string
*/
String continuation();
/**
* Indicates whether input continuation matches the target type and is thus
* more likely to be the desired continuation. A matching continuation is
* preferred.
*
* @return {@code true} if this suggested continuation matches the
* target type; otherwise {@code false}
*/
boolean matchesType();
}
/**
* A documentation for a candidate for continuation of the given user's input.
*/
public interface Documentation {
/**
* The signature of the given element.
*
* @return the signature
*/
String signature();
/**
* The javadoc of the given element.
*
* @return the javadoc, or null if not found or not requested
*/
String javadoc();
}
/**
* List of possible qualified names.
*/
public static final class QualifiedNames {
private final List<String> names;
private final int simpleNameLength;
private final boolean upToDate;
private final boolean resolvable;
QualifiedNames(List<String> names, int simpleNameLength, boolean upToDate, boolean resolvable) {
this.names = names;
this.simpleNameLength = simpleNameLength;
this.upToDate = upToDate;
this.resolvable = resolvable;
}
/**
* Known qualified names for the given simple name in the original code.
*
* @return known qualified names
*/
public List<String> getNames() {
return names;
}
/**
* The length of the simple name in the original code for which the
* qualified names where gathered.
*
* @return the length of the simple name; -1 if there is no name immediately left to the cursor for
* which the candidates could be computed
*/
public int getSimpleNameLength() {
return simpleNameLength;
}
/**
* Indicates whether the result is based on up-to-date data. The
* {@link SourceCodeAnalysis#listQualifiedNames(java.lang.String, int) listQualifiedNames}
* method may return before the classpath is fully inspected, in which case this method will
* return {@code false}. If the result is based on a fully inspected classpath, this method
* will return {@code true}.
*
* @return {@code true} if the result is based on up-to-date data;
* otherwise {@code false}
*/
public boolean isUpToDate() {
return upToDate;
}
/**
* Indicates whether the given simple name in the original code refers
* to a resolvable element.
*
* @return {@code true} if the given simple name in the original code
* refers to a resolvable element; otherwise {@code false}
*/
public boolean isResolvable() {
return resolvable;
}
}
/**
* The wrapping of a snippet of Java source into valid top-level Java
* source. The wrapping will always either be an import or include a
* synthetic class at the top-level. If a synthetic class is generated, it
* will be proceeded by the package and import declarations, and may contain
* synthetic class members.
* <p>
* This interface, in addition to the mapped form, provides the context and
* position mapping information.
*/
public interface SnippetWrapper {
/**
* Returns the input that is wrapped. For
* {@link SourceCodeAnalysis#wrappers(java.lang.String) wrappers(String)},
* this is the source of the snippet within the input. A variable
* declaration of {@code N} variables will map to {@code N} wrappers
* with the source separated.
* <p>
* For {@link SourceCodeAnalysis#wrapper(Snippet) wrapper(Snippet)},
* this is {@link Snippet#source() }.
*
* @return the input source corresponding to the wrapper.
*/
String source();
/**
* Returns a Java class definition that wraps the
* {@link SnippetWrapper#source()} or, if an import, the import source.
* <p>
* If the input is not a valid Snippet, this will not be a valid
* class/import definition.
* <p>
* The source may be divided and mapped to different locations within
* the wrapped source.
*
* @return the source wrapped into top-level Java code
*/
String wrapped();
/**
* Returns the fully qualified class name of the
* {@link SnippetWrapper#wrapped() } class.
* For erroneous input, a best guess is returned.
*
* @return the name of the synthetic wrapped class; if an import, the
* name is not defined
*/
String fullClassName();
/**
* Returns the {@link Snippet.Kind} of the
* {@link SnippetWrapper#source()}.
*
* @return an enum representing the general kind of snippet.
*/
Snippet.Kind kind();
/**
* Maps character position within the source to character position
* within the wrapped.
*
* @param pos the position in {@link SnippetWrapper#source()}
* @return the corresponding position in
* {@link SnippetWrapper#wrapped() }
*/
int sourceToWrappedPosition(int pos);
/**
* Maps character position within the wrapped to character position
* within the source.
*
* @param pos the position in {@link SnippetWrapper#wrapped()}
* @return the corresponding position in
* {@link SnippetWrapper#source() }
*/
int wrappedToSourcePosition(int pos);
}
}