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