1 /* 2 * Copyright (c) 2015, 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 * @since 9 40 */ 41 public interface Parser { 42 /** 43 * Parses the source file and returns compilation unit tree 44 * 45 * @param file source file to parse 46 * @param listener to receive diagnostic messages from the parser. This can be null. 47 * if null is passed, a NashornException is thrown on the first parse error. 48 * @return compilation unit tree 49 * @throws NullPointerException if file is null 50 * @throws IOException if parse source read fails 51 * @throws NashornException is thrown if no listener is supplied and parser encounters error 52 */ 53 public CompilationUnitTree parse(final File file, final DiagnosticListener listener) throws IOException, NashornException; 54 55 /** 56 * Parses the source Path and returns compilation unit tree 57 * 58 * @param path source Path to parse 59 * @param listener to receive diagnostic messages from the parser. This can be null. 60 * if null is passed, a NashornException is thrown on the first parse error. 61 * @return compilation unit tree 62 * @throws NullPointerException if path is null 63 * @throws IOException if parse source read fails 64 * @throws NashornException is thrown if no listener is supplied and parser encounters error 65 */ 66 public CompilationUnitTree parse(final Path path, final DiagnosticListener listener) throws IOException, NashornException; 67 68 /** 69 * Parses the source url and returns compilation unit tree 70 * 71 * @param url source file to parse 72 * @param listener to receive diagnostic messages from the parser. This can be null. 73 * if null is passed, a NashornException is thrown on the first parse error. 74 * @return compilation unit tree 75 * @throws NullPointerException if url is null 76 * @throws IOException if parse source read fails 77 * @throws NashornException is thrown if no listener is supplied and parser encounters error 78 */ 79 public CompilationUnitTree parse(final URL url, final DiagnosticListener listener) throws IOException, NashornException; 80 81 /** 82 * Parses the reader and returns compilation unit tree 83 * 84 * @param name name of the source file to parse 85 * @param reader from which source is read 86 * @param listener to receive diagnostic messages from the parser. This can be null. 87 * if null is passed, a NashornException is thrown on the first parse error. 88 * @return compilation unit tree 89 * @throws NullPointerException if name or reader is null 90 * @throws IOException if parse source read fails 91 * @throws NashornException is thrown if no listener is supplied and parser encounters error 92 */ 93 public CompilationUnitTree parse(final String name, Reader reader, final DiagnosticListener listener) throws IOException, NashornException; 94 95 /** 96 * Parses the string source and returns compilation unit tree 97 * 98 * @param name of the source 99 * @param code string source 100 * @param listener to receive diagnostic messages from the parser. This can be null. 101 * if null is passed, a NashornException is thrown on the first parse error. 102 * @return compilation unit tree 103 * @throws NullPointerException if name or code is null 104 * @throws NashornException is thrown if no listener is supplied and parser encounters error 105 */ 106 public CompilationUnitTree parse(final String name, String code, final DiagnosticListener listener) throws NashornException; 107 108 /** 109 * Parses the source from script object and returns compilation unit tree 110 * 111 * @param scriptObj script object whose script and name properties are used for script source 112 * @param listener to receive diagnostic messages from the parser. This can be null. 113 * if null is passed, a NashornException is thrown on the first parse error. 114 * @return compilation unit tree 115 * @throws NullPointerException if scriptObj is null 116 * @throws NashornException is thrown if no listener is supplied and parser encounters error 117 */ 118 public CompilationUnitTree parse(final ScriptObjectMirror scriptObj, final DiagnosticListener listener) throws NashornException; 119 120 /** 121 * Factory method to create a new instance of Parser. 122 * 123 * @param options configuration options to initialize the Parser. 124 * Currently the following options are supported: 125 * 126 * <dl> 127 * <dt>"--const-as-var"</dt><dd>treat "const" declaration as "var"</dd> 128 * <dt>"-dump-on-error" or "-doe"</dt><dd>dump stack trace on error</dd> 129 * <dt>"--empty-statements"</dt><dd>include empty statement nodes</dd> 130 * <dt>"--no-syntax-extensions" or "-nse"</dt><dd>disable ECMAScript syntax extensions</dd> 131 * <dt>"-scripting"</dt><dd>enable scripting mode extensions</dd> 132 * <dt>"-strict"</dt><dd>enable ECMAScript strict mode</dd> 133 * </dl> 134 * 135 * @throws NullPointerException if options array or any of its element is null 136 * @throws IllegalArgumentException on unsupported option value. 137 * @return a new Parser instance. 138 */ 139 public static Parser create(final String... options) throws IllegalArgumentException { 140 options.getClass(); 141 for (String opt : options) { 142 switch (opt) { 143 case "--const-as-var": 144 case "-dump-on-error": 145 case "-doe": 146 case "--empty-statements": 147 case "--no-syntax-extensions": 148 case "-nse": 149 case "-scripting": 150 case "-strict": 151 break; 152 default: 153 throw new IllegalArgumentException(opt); 154 } 155 } 156 157 return new ParserImpl(options); 158 } 159 }