       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 /**
      29  * Interface for diagnostics from tools.  A diagnostic usually reports
      30  * a problem at a specific position in a source file.  However, not
      31  * all diagnostics are associated with a position or a file.
      32  *
      33  * <p>A position is a zero-based character offset from the beginning of
      34  * a file.  Negative values (except {@link #NOPOS}) are not valid
      35  * positions.
      36  *
      37  * <p>Line and column numbers begin at 1.  Negative values (except
      38  * {@link #NOPOS}) and 0 are not valid line or column numbers.
      39  *
      40  * <p>Line terminator is as defined in ECMAScript specification which is one
      41  * of { \u000A, \u000B, \u2028, \u2029 }.
      42  *

      43  * @since 9
      44  */

      45 public interface Diagnostic {
      46
      47     /**
      48      * Kinds of diagnostics, for example, error or warning.
      49      *
      50      * The kind of a diagnostic can be used to determine how the
      51      * diagnostic should be presented to the user. For example,
      52      * errors might be colored red or prefixed with the word "Error",
      53      * while warnings might be colored yellow or prefixed with the
      54      * word "Warning". There is no requirement that the Kind
      55      * should imply any inherent semantic meaning to the message
      56      * of the diagnostic: for example, a tool might provide an
      57      * option to report all warnings as errors.
      58      */

      59     enum Kind {
      60         /**
      61          * Problem which prevents the tool's normal completion.
      62          */
      63         ERROR,
      64         /**
      65          * Problem which does not usually prevent the tool from
      66          * completing normally.
      67          */
      68         WARNING,
      69         /**
      70          * Problem similar to a warning, but is mandated by the tool's
      71          * specification.  For example, the Java&trade; Language
      72          * Specification mandates warnings on certain
      73          * unchecked operations and the use of deprecated methods.
      74          */
      75         MANDATORY_WARNING,
      76         /**
      77          * Informative message from the tool.
      78          */
      79         NOTE,
      80         /**
      81          * Diagnostic which does not fit within the other kinds.
      82          */
      83         OTHER,
      84     }
      85
      86     /**
      87      * Used to signal that no position is available.
      88      */
      89     public final static long NOPOS = -1;
      90
      91     /**
      92      * Gets the kind of this diagnostic, for example, error or
      93      * warning.
      94      * @return the kind of this diagnostic
      95      */
      96     Kind getKind();
      97
      98     /**
      99      * Gets a character offset from the beginning of the source object
     100      * associated with this diagnostic that indicates the location of
     101      * the problem.  In addition, the following must be true:
     102      *
     103      * <p>{@code getStartPostion() <= getPosition()}
     104      * <p>{@code getPosition() <= getEndPosition()}
     105      *
     106      * @return character offset from beginning of source; {@link
     107      * #NOPOS} if no location is suitable
     108      */
     109     long getPosition();
     110
     111     /**
     112      * Gets the source file name.
     113      *
     114      * @return the file name or null if not available
     115      */
     116     String getFileName();
     117
     118     /**
     119      * Gets the line number of the character offset returned by
     120      * {@linkplain #getPosition()}.
     121      *
     122      * @return a line number or {@link #NOPOS} if and only if {@link
     123      * #getPosition()} returns {@link #NOPOS}
     124      */
     125     long getLineNumber();
     126
     127     /**
     128      * Gets the column number of the character offset returned by
     129      * {@linkplain #getPosition()}.
     130      *
     131      * @return a column number or {@link #NOPOS} if and only if {@link
     132      * #getPosition()} returns {@link #NOPOS}
     133      */
     134     long getColumnNumber();
     135
     136     /**
     137      * Gets a diagnostic code indicating the type of diagnostic.  The
     138      * code is implementation-dependent and might be {@code null}.
     139      *
     140      * @return a diagnostic code
     141      */
     142     String getCode();
     143
     144     /**
     145      * Gets a message for this diagnostic.
     146      *
     147      * @return a message
     148      */
     149     String getMessage();
     150 }
    --- EOF ---