       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 }