Parser.java revision 1786:80120e9b3273
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 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 9 40 */ 41public 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 * <dt>"--language=es6"</dt><dd>enable ECMAScript 6 parsing mode</dd> 134 * <dt>"--es6-module"</dt><dd>enable ECMAScript 6 module parsing mode. This option implies --language=es6</dd> 135 * </dl> 136 * 137 * @throws NullPointerException if options array or any of its element is null 138 * @throws IllegalArgumentException on unsupported option value. 139 * @return a new Parser instance. 140 */ 141 public static Parser create(final String... options) throws IllegalArgumentException { 142 options.getClass(); 143 for (final String opt : options) { 144 switch (opt) { 145 case "--const-as-var": 146 case "-dump-on-error": 147 case "-doe": 148 case "--empty-statements": 149 case "--no-syntax-extensions": 150 case "-nse": 151 case "-scripting": 152 case "-strict": 153 case "--language=es6": 154 case "--es6-module": 155 break; 156 default: 157 throw new IllegalArgumentException(opt); 158 } 159 } 160 161 return new ParserImpl(options); 162 } 163} 164