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 }