/*

 * Copyright (c) 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.Collections;

import java.util.List;

/**

 * A Snippet represents a snippet of Java source code as passed to

 * {@link jdk.jshell.JShell#eval}.  It is associated only with the

 * {@link jdk.jshell.JShell JShell} instance that created it.

 * An instance of Snippet (including its subclasses) is immutable: an access to

 * any of its methods will always return the same result.

 * For information about the current state of the snippet within the JShell

 * <p>

 * @author Robert Field

 * @see jdk.jshell.JShell#status

 */

public abstract class Snippet {

    /**

     * Describes the general kind of snippet.

     * It is accessed with {@link jdk.jshell.Snippet#kind()}.

     * subclass of Snippet it is. For example,

     * {@link jdk.jshell.JShell#eval eval("int three() { return 3; }")} will

     * cast as such.

     */

    public enum Kind {

        /**

         * The snippet is an instance of {@link jdk.jshell.ImportSnippet}.

         * An import can be a single type import

         * ({@link jdk.jshell.Snippet.SubKind#SINGLE_TYPE_IMPORT_SUBKIND}),

         * a static single import

         * ({@link jdk.jshell.Snippet.SubKind#SINGLE_STATIC_IMPORT_SUBKIND}),

         * an on-demand type import

         * ({@link jdk.jshell.Snippet.SubKind#TYPE_IMPORT_ON_DEMAND_SUBKIND}),

         * or a static on-demand type import

         * ({@link jdk.jshell.Snippet.SubKind#SINGLE_STATIC_IMPORT_SUBKIND}) --

         * use {@link jdk.jshell.Snippet#subKind()} to distinguish.

         * @jls 8.3: importDeclaration.

         */

        IMPORT(true),

        /**

         * A type declaration.

         * Which includes: NormalClassDeclaration, EnumDeclaration,

         * NormalInterfaceDeclaration, and AnnotationTypeDeclaration.

         * The snippet is an instance of {@link jdk.jshell.TypeDeclSnippet}.

         * A type declaration may be an interface

         * {@link jdk.jshell.Snippet.SubKind#INTERFACE_SUBKIND},

         * classes {@link jdk.jshell.Snippet.SubKind#CLASS_SUBKIND}, enums, and

         * annotation interfaces -- see {@link jdk.jshell.Snippet.SubKind} to

         * differentiate.

         * @jls 7.6: TypeDeclaration.

         */

        TYPE_DECL(true),

        /**

         * A method declaration.

         * The snippet is an instance of {@link jdk.jshell.MethodSnippet}.

         * @jls 8.4: MethodDeclaration.

         */

        METHOD(true),

        /**

         * One variable declaration.

         * Corresponding to one <i>VariableDeclarator</i>.

         * The snippet is an instance of {@link jdk.jshell.VarSnippet}.

         * The variable may be with or without initializer, or be a temporary

         * variable representing an expression -- see

         * {@link jdk.jshell.Snippet.SubKind}to differentiate.

         * @jls 8.3: FieldDeclaration.

         */

        VAR(true),

        /**

         * An expression, with or without side-effects.

         * The snippet is an instance of {@link jdk.jshell.ExpressionSnippet}.

         * The expression is currently either a simple named reference to a

         * variable ({@link jdk.jshell.Snippet.SubKind#VAR_VALUE_SUBKIND}) or an

         * assignment (both of which have natural referencing

         * names) -- see {@link jdk.jshell.Snippet.SubKind} to differentiate.

         * @jls 15: Expression.

         */

        EXPRESSION(false),

        /**

         * A statement.

         * The snippet is an instance of {@link jdk.jshell.StatementSnippet}.

         * @jls 14.5: Statement.

         */

        STATEMENT(false),

        /**

         * A syntactically incorrect input for which the specific

         * kind could not be determined.

         * The snippet is an instance of {@link jdk.jshell.ErroneousSnippet}.

         */

        ERRONEOUS(false);

        Kind(boolean isPersistent) {

            this.isPersistent = isPersistent;

        }

    }

    /**

     * The detailed variety of a snippet.  This is a sub-classification of the

     * Kind.  The Kind of a SubKind is accessible with

     * {@link jdk.jshell.Snippet.SubKind#kind}.

     */

    public enum SubKind {

        /**

         * Single-Type-Import Declaration.

         * An import declaration of a single type.

         * @jls 7.5.1 SingleTypeImportDeclaration.

         */

        SINGLE_TYPE_IMPORT_SUBKIND(Kind.IMPORT),

        /**

         * Type-Import-on-Demand Declaration.

         * A non-static "star" import.

         * @jls 7.5.2. TypeImportOnDemandDeclaration.

         */

        TYPE_IMPORT_ON_DEMAND_SUBKIND(Kind.IMPORT),

        /**

         * Single-Static-Import Declaration.

         * An import of a static member.

         * @jls 7.5.3 Single-Static-Import.

         */

        SINGLE_STATIC_IMPORT_SUBKIND(Kind.IMPORT),

        /**

         * Static-Import-on-Demand Declaration.

         * A static "star" import of all static members of a named type.

         * @jls 7.5.4. Static-Import-on-Demand Static "star" import.

         */

        STATIC_IMPORT_ON_DEMAND_SUBKIND(Kind.IMPORT),

        /**

         * A class declaration.

         * @jls 8.1. NormalClassDeclaration.

         */

        CLASS_SUBKIND(Kind.TYPE_DECL),

        /**

         * An interface declaration.

         * @jls 9.1. NormalInterfaceDeclaration.

         */

        INTERFACE_SUBKIND(Kind.TYPE_DECL),

        /**

         * An enum declaration.

         * @jls 8.9. EnumDeclaration.

         */

        ENUM_SUBKIND(Kind.TYPE_DECL),

        /**

         * {@link Kind#TYPE_DECL}.

         * @jls 9.6. AnnotationTypeDeclaration.

         */

        ANNOTATION_TYPE_SUBKIND(Kind.TYPE_DECL),

        /**

         * @jls 8.4. MethodDeclaration.

         */

        METHOD_SUBKIND(Kind.METHOD),

        /**

         * A variable declaration without initializer.

         * @jls 8.3. VariableDeclarator without VariableInitializer in

         * FieldDeclaration.

         */

        VAR_DECLARATION_SUBKIND(Kind.VAR),

        /**

         * A variable declaration with an initializer expression. A

         * @jls 8.3. VariableDeclarator with VariableInitializer in

         * FieldDeclaration.

         */

        VAR_DECLARATION_WITH_INITIALIZER_SUBKIND(Kind.VAR, true, true),

        /**

         * An expression whose value has been stored in a temporary variable. A

         * @jls 15. Primary.

         */

        TEMP_VAR_EXPRESSION_SUBKIND(Kind.VAR, true, true),

        /**

         * {@link Kind#EXPRESSION}.

         * @jls 15.11. Field Access as 3.8. Identifier.

         */

        VAR_VALUE_SUBKIND(Kind.EXPRESSION, true, true),

        /**

         * {@link Kind#EXPRESSION}.

         * @jls 15.26. Assignment.

         */

        ASSIGNMENT_SUBKIND(Kind.EXPRESSION, true, true),

        /**

         * An expression which has not been wrapped in a temporary variable

         */

        OTHER_EXPRESSION_SUBKIND(Kind.EXPRESSION, true, true),

        /**

         * @jls 14.5. Statement.

         */

        STATEMENT_SUBKIND(Kind.STATEMENT, true, false),

        /**

         * {@link Kind#ERRONEOUS}.

         */

        UNKNOWN_SUBKIND(Kind.ERRONEOUS, false, false);

        private final boolean isExecutable;

        private final boolean hasValue;

        private final Kind kind;

        SubKind(Kind kind) {

            this.kind = kind;

            this.isExecutable = false;

            this.hasValue = false;

        }

        SubKind(Kind kind, boolean isExecutable, boolean hasValue) {

            this.kind = kind;

            this.isExecutable = isExecutable;

            this.hasValue = hasValue;

        }

        /**

         *

         */

        public boolean isExecutable() {

            return isExecutable;

        }

        /**

         *

         */

        public boolean hasValue() {

            return hasValue;

        }

        /**

         *

         */

        public Kind kind() {

            return kind;

        }

    }

    /**

     * Describes the current state of a Snippet.

     * This is a dynamic property of a Snippet within the JShell state --

     * thus is retrieved with a {@linkplain

     * <p>

     * For example, creation of another snippet with

     * {@link jdk.jshell.JShell#eval(java.lang.String) eval}

     * may resolve dependencies of this Snippet (or invalidate those dependencies), or

     * {@linkplain jdk.jshell.Snippet.Status#OVERWRITTEN overwrite}

     * this Snippet changing its

     * <p>

     * existing and new snippets; and

     * JShell state changes, the snippet will update, possibly

     * An executable Snippet can only be executed if it is in the the

     * @see JShell#status(jdk.jshell.Snippet)

     */

    public enum Status {

        /**

         * The snippet is a valid snippet

         * <p>

         * The snippet will update as dependents change

         */

        VALID(true, true),

        /**

         * The snippet is a declaration snippet with potentially recoverable

         * unresolved references or other issues in its body

         * Only a {@link jdk.jshell.DeclarationSnippet} can have this

         * The snippet has a valid signature and it is visible to other

         * and thus can be referenced in existing or new snippets

         * but the snippet cannot be executed.

         * An {@link UnresolvedReferenceException} will be thrown on an attempt

         * to execute it.

         * <p>

         * The snippet will update as dependents change

         * <p>

         * indicate potentially recoverable errors, they differ in that, for

         */

        RECOVERABLE_DEFINED(true, true),

        /**

         * The snippet is a declaration snippet with potentially recoverable

         * unresolved references or other issues

         * Only a {@link jdk.jshell.DeclarationSnippet} can have this

         * The snippet has an invalid signature or the implementation is

         * otherwise unable to define it.

         * The snippet it is not visible to other snippets

         * and thus cannot be referenced or executed.

         * <p>

         * The snippet will update as dependents change

         * <p>

         * indicate potentially recoverable errors, they differ in that, for

         */

        RECOVERABLE_NOT_DEFINED(true, false),

        /**

         * The snippet is inactive because of an explicit call to

         * Only a {@link jdk.jshell.PersistentSnippet} can have this

         * The snippet is not visible to other snippets

         * and thus cannot be referenced or executed.

         * <p>

         * The snippet will not update as dependents change

         */

        DROPPED(false, false),

        /**

         * The snippet is inactive because it has been replaced by a new

         * snippet.  This occurs when the new snippet added with

         * {@link jdk.jshell.JShell#eval} matches a previous snippet.

         * match.

         * Only a {@link jdk.jshell.PersistentSnippet} can have this

         * The snippet is not visible to other snippets

         * and thus cannot be referenced or executed.

         * <p>

         * The snippet will not update as dependents change

         */

        OVERWRITTEN(false, false),

        /**

         * The snippet is inactive because it failed compilation on initial

         * evaluation and it is not capable of becoming valid with further

         * changes to the JShell state.

         * The snippet is not visible to other snippets

         * and thus cannot be referenced or executed.

         * <p>

         * The snippet will not update as dependents change

         */

        REJECTED(false, false),

        /**

         * The snippet is inactive because it does not yet exist.

         * Used only in {@link SnippetEvent#previousStatus} for new

         * snippets.