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 1.9
40 */
41 @jdk.Exported
42 public 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 reader and 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 array or any of its 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 }