src/jdk.scripting.nashorn/share/classes/jdk/nashorn/api/tree/Parser.java
author sundar
Thu, 28 Jun 2018 18:04:19 +0530
changeset 50878 fb7800b66c92
parent 47216 71c04702a3d5
permissions -rw-r--r--
8204492: Add deprecation annotation to Nashorn APIs and warning to nashorn, jjs Reviewed-by: jlaskey, hannesw
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
29407
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
     1
/*
39662
e2b36a3779b9 8149929: Nashorn Parser API needs to be updated for ES6
sundar
parents: 35325
diff changeset
     2
 * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
29407
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
     4
 *
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    10
 *
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    15
 * accompanied this code).
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    16
 *
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    20
 *
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    23
 * questions.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    24
 */
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    25
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    26
package jdk.nashorn.api.tree;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    27
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    28
import java.io.File;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    29
import java.io.IOException;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    30
import java.io.Reader;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    31
import java.net.URL;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    32
import java.nio.file.Path;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    33
import jdk.nashorn.api.scripting.NashornException;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    34
import jdk.nashorn.api.scripting.ScriptObjectMirror;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    35
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    36
/**
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    37
 * Represents nashorn ECMAScript parser instance.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    38
 *
50878
fb7800b66c92 8204492: Add deprecation annotation to Nashorn APIs and warning to nashorn, jjs
sundar
parents: 47216
diff changeset
    39
 * @deprecated Nashorn JavaScript script engine and APIs, and the jjs tool
fb7800b66c92 8204492: Add deprecation annotation to Nashorn APIs and warning to nashorn, jjs
sundar
parents: 47216
diff changeset
    40
 * are deprecated with the intent to remove them in a future release.
fb7800b66c92 8204492: Add deprecation annotation to Nashorn APIs and warning to nashorn, jjs
sundar
parents: 47216
diff changeset
    41
 *
35325
7624a7d7e661 8136494: Update "@since 1.9" to "@since 9" to match java.version.specification
iris
parents: 34903
diff changeset
    42
 * @since 9
29407
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    43
 */
50878
fb7800b66c92 8204492: Add deprecation annotation to Nashorn APIs and warning to nashorn, jjs
sundar
parents: 47216
diff changeset
    44
@Deprecated(since="11", forRemoval=true)
29407
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    45
public interface Parser {
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    46
    /**
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    47
     * Parses the source file and returns compilation unit tree
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    48
     *
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    49
     * @param file source file to parse
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    50
     * @param listener to receive diagnostic messages from the parser. This can be null.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    51
     * if null is passed, a NashornException is thrown on the first parse error.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    52
     * @return compilation unit tree
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    53
     * @throws NullPointerException if file is null
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    54
     * @throws IOException if parse source read fails
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    55
     * @throws NashornException is thrown if no listener is supplied and parser encounters error
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    56
     */
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    57
    public CompilationUnitTree parse(final File file, final DiagnosticListener listener) throws IOException, NashornException;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    58
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    59
    /**
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    60
     * Parses the source Path and returns compilation unit tree
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    61
     *
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    62
     * @param path source Path to parse
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    63
     * @param listener to receive diagnostic messages from the parser. This can be null.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    64
     * if null is passed, a NashornException is thrown on the first parse error.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    65
     * @return compilation unit tree
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    66
     * @throws NullPointerException if path is null
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    67
     * @throws IOException if parse source read fails
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    68
     * @throws NashornException is thrown if no listener is supplied and parser encounters error
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    69
     */
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    70
    public CompilationUnitTree parse(final Path path, final DiagnosticListener listener) throws IOException, NashornException;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    71
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    72
    /**
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    73
     * Parses the source url and returns compilation unit tree
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    74
     *
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    75
     * @param url source file to parse
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    76
     * @param listener to receive diagnostic messages from the parser. This can be null.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    77
     * if null is passed, a NashornException is thrown on the first parse error.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    78
     * @return compilation unit tree
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    79
     * @throws NullPointerException if url is null
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    80
     * @throws IOException if parse source read fails
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    81
     * @throws NashornException is thrown if no listener is supplied and parser encounters error
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    82
     */
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    83
    public CompilationUnitTree parse(final URL url, final DiagnosticListener listener) throws IOException, NashornException;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    84
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    85
    /**
32534
b3ec7f3b3c2a 8136349: Typos patch for nashorn sources submitted on Sep 10, 2015
sundar
parents: 29407
diff changeset
    86
     * Parses the reader and returns compilation unit tree
29407
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    87
     *
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    88
     * @param name name of the source file to parse
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    89
     * @param reader from which source is read
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    90
     * @param listener to receive diagnostic messages from the parser. This can be null.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    91
     * if null is passed, a NashornException is thrown on the first parse error.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    92
     * @return compilation unit tree
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    93
     * @throws NullPointerException if name or reader is null
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    94
     * @throws IOException if parse source read fails
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    95
     * @throws NashornException is thrown if no listener is supplied and parser encounters error
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    96
     */
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    97
    public CompilationUnitTree parse(final String name, Reader reader, final DiagnosticListener listener) throws IOException, NashornException;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    98
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
    99
    /**
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   100
     * Parses the string source and returns compilation unit tree
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   101
     *
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   102
     * @param name of the source
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   103
     * @param code string source
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   104
     * @param listener to receive diagnostic messages from the parser. This can be null.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   105
     * if null is passed, a NashornException is thrown on the first parse error.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   106
     * @return compilation unit tree
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   107
     * @throws NullPointerException if name or code is null
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   108
     * @throws NashornException is thrown if no listener is supplied and parser encounters error
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   109
     */
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   110
    public CompilationUnitTree parse(final String name, String code, final DiagnosticListener listener) throws NashornException;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   111
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   112
    /**
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   113
     * Parses the source from script object and returns compilation unit tree
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   114
     *
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   115
     * @param scriptObj script object whose script and name properties are used for script source
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   116
     * @param listener to receive diagnostic messages from the parser. This can be null.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   117
     * if null is passed, a NashornException is thrown on the first parse error.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   118
     * @return compilation unit tree
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   119
     * @throws NullPointerException if scriptObj is null
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   120
     * @throws NashornException is thrown if no listener is supplied and parser encounters error
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   121
     */
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   122
    public CompilationUnitTree parse(final ScriptObjectMirror scriptObj, final DiagnosticListener listener) throws NashornException;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   123
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   124
    /**
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   125
     * Factory method to create a new instance of Parser.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   126
     *
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   127
     * @param options configuration options to initialize the Parser.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   128
     *         Currently the following options are supported:
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   129
     *
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   130
     * <dl>
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   131
     * <dt>"--const-as-var"</dt><dd>treat "const" declaration as "var"</dd>
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   132
     * <dt>"-dump-on-error" or "-doe"</dt><dd>dump stack trace on error</dd>
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   133
     * <dt>"--empty-statements"</dt><dd>include empty statement nodes</dd>
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   134
     * <dt>"--no-syntax-extensions" or "-nse"</dt><dd>disable ECMAScript syntax extensions</dd>
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   135
     * <dt>"-scripting"</dt><dd>enable scripting mode extensions</dd>
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   136
     * <dt>"-strict"</dt><dd>enable ECMAScript strict mode</dd>
39662
e2b36a3779b9 8149929: Nashorn Parser API needs to be updated for ES6
sundar
parents: 35325
diff changeset
   137
     * <dt>"--language=es6"</dt><dd>enable ECMAScript 6 parsing mode</dd>
e2b36a3779b9 8149929: Nashorn Parser API needs to be updated for ES6
sundar
parents: 35325
diff changeset
   138
     * <dt>"--es6-module"</dt><dd>enable ECMAScript 6 module parsing mode. This option implies --language=es6</dd>
29407
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   139
     * </dl>
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   140
     *
32534
b3ec7f3b3c2a 8136349: Typos patch for nashorn sources submitted on Sep 10, 2015
sundar
parents: 29407
diff changeset
   141
     * @throws NullPointerException if options array or any of its element is null
29407
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   142
     * @throws IllegalArgumentException on unsupported option value.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   143
     * @return a new Parser instance.
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   144
     */
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   145
    public static Parser create(final String... options) throws IllegalArgumentException {
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   146
        options.getClass();
41422
97eda72f53b6 8167117: insert missing final keywords
attila
parents: 39662
diff changeset
   147
        for (final String opt : options) {
29407
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   148
            switch (opt) {
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   149
                case "--const-as-var":
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   150
                case "-dump-on-error":
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   151
                case "-doe":
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   152
                case "--empty-statements":
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   153
                case "--no-syntax-extensions":
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   154
                case "-nse":
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   155
                case "-scripting":
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   156
                case "-strict":
39662
e2b36a3779b9 8149929: Nashorn Parser API needs to be updated for ES6
sundar
parents: 35325
diff changeset
   157
                case "--language=es6":
e2b36a3779b9 8149929: Nashorn Parser API needs to be updated for ES6
sundar
parents: 35325
diff changeset
   158
                case "--es6-module":
29407
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   159
                    break;
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   160
                default:
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   161
                    throw new IllegalArgumentException(opt);
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   162
            }
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   163
        }
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   164
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   165
        return new ParserImpl(options);
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   166
    }
3fd4ede1581e 8074671: Nashorn Parser API
sundar
parents:
diff changeset
   167
}