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