Move scanner into pkg/front_end/lib/src/scanner.

pkg/front_end/lib/src/scanner/errors.dart

+// Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library front_end.src.scanner.errors;

[Brian Wilkerson, 2016/11/08 20:53:23]

Is there any value to having library directives (in the absence of parts)?

Also, consider adding doc comments to all libraries in the process.

[Paul Berry, 2016/11/08 21:47:06]

IMHO, not really.  I've removed them.
Acknowledged.

+
+import 'package:analyzer/error/error.dart'

[kevmoo, 2016/11/08 22:26:03]

We try to avoid circular dependencies between packages (at least in the lib
directory, tests are fine)

Is this short-term?

[Paul Berry, 2016/11/08 22:28:14]

Yes.  This will be removed when the "@deprecated" members below are removed,
which we should be able to do next time we publish a breaking change to
analyzer.

+    show errorCodeValues, errorCodeByUniqueName;
+
+/**
+ * An error code associated with an [AnalysisError].
+ *
+ * Generally, we want to provide messages that consist of three sentences. From
+ * the user's perspective these sentences should explain:
+ *
+ * 1. what is wrong,
+ * 2. why is it wrong, and
+ * 3. how do I fix it.
+ *
+ * However, we combine the first two in the [message] and the last in the
+ * [correction].
+ *
+ * When composing messages (including correction messages) keep the following
+ * guidelines in mind.
+ *
+ * 1. The message should be a complete sentence starting with an uppercase
+ * letter, and ending with a period.
+ *
+ * 2. Reserved words and embedded identifiers should be in single quotes, so
+ * prefer double quotes for the complete message. For example,
+ * ```
+ * "The class '{0}' can't use 'super'."
+ * ```
+ * Notice that the word 'class' in the preceding message is not quoted as it
+ * refers to the concept 'class', not the reserved word. On the other hand,
+ * 'super' refers to the reserved word. Do not quote 'null' and numeric literals.
+ *
+ * 3. Do not try to compose messages, as it can make translating them hard.
+ *
+ * 4. Try to keep the error messages short, but informative.
+ *
+ * 5. Use simple words and terminology, assume the reader of the message doesn't
+ * have an advanced degree in math, and that English is not the reader's native
+ * language. Do not assume any formal computer science training. For example, do
+ * not use Latin abbreviations (prefer "that is" over "i.e.", and "for example"
+ * over "e.g."). Also avoid phrases such as "if and only if" and "iff"; that
+ * level of precision is unnecessary.
+ *
+ * 6. Prefer contractions when they are in common use, for example, prefer
+ * "can't" over "cannot". Using "cannot", "must not", "shall not", etc. is
+ * off-putting to people new to programming.
+ *
+ * 7. Use common terminology, preferably from the Dart Language Specification.
+ * This increases the user's chance of finding a good explanation on the web.
+ *
+ * 8. Do not try to be cute or funny. It is extremely frustrating to work on a
+ * product that crashes with a "tongue-in-cheek" message, especially if you did
+ * not want to use this product to begin with.
+ *
+ * 9. Do not lie, that is, do not write error messages containing phrases like
+ * "can't happen".  If the user ever saw this message, it would be a lie. Prefer
+ * messages like: "Internal error: This function should not be called when 'x'
+ * is null.".
+ *
+ * 10. Prefer to not use the imperative tone. That is, the message should not
+ * sound accusing or like it is ordering the user around. The computer should
+ * describe the problem, not criticize the user for violating the specification.
+ */
+abstract class ErrorCode {

[Brian Wilkerson, 2016/11/08 20:53:23]

I would recommend putting the abstract classes in a non-scanner-specific
library.

[Paul Berry, 2016/11/08 21:47:06]

Acknowledged.  I will address this in later CLs.

+  /**
+   * Engine error code values.
+   */
+  @deprecated
+  static const List<ErrorCode> values = errorCodeValues;
+
+  /**
+   * An empty list of error codes.
+   */
+  @deprecated
+  static const List<ErrorCode> EMPTY_LIST = const <ErrorCode>[];
+
+  /**
+   * The name of the error code.
+   */
+  final String name;
+
+  /**
+   * The template used to create the message to be displayed for this error. The
+   * message should indicate what is wrong and why it is wrong.
+   */
+  final String message;
+
+  /**
+   * The template used to create the correction to be displayed for this error,
+   * or `null` if there is no correction information for this error. The
+   * correction should indicate how the user can fix the error.
+   */
+  final String correction;
+
+  /**
+   * Initialize a newly created error code to have the given [name]. The message
+   * associated with the error will be created from the given [message]
+   * template. The correction associated with the error will be created from the
+   * given [correction] template.
+   */
+  const ErrorCode(this.name, this.message, [this.correction]);
+
+  /**
+   * The severity of the error.
+   */
+  ErrorSeverity get errorSeverity;
+
+  /**
+   * The type of the error.
+   */
+  ErrorType get type;
+
+  /**
+   * The unique name of this error code.
+   */
+  String get uniqueName => "$runtimeType.$name";
+
+  @override
+  String toString() => uniqueName;
+
+  /**
+   * Return the [ErrorCode] with the given [uniqueName], or `null` if not
+   * found.
+   */
+  @deprecated
+  static ErrorCode byUniqueName(String uniqueName) =>
+      errorCodeByUniqueName(uniqueName);
+}
+
+/**
+ * The severity of an [ErrorCode].
+ */
+class ErrorSeverity implements Comparable<ErrorSeverity> {
+  /**
+   * The severity representing a non-error. This is never used for any error
+   * code, but is useful for clients.
+   */
+  static const ErrorSeverity NONE = const ErrorSeverity('NONE', 0, " ", "none");
+
+  /**
+   * The severity representing an informational level analysis issue.
+   */
+  static const ErrorSeverity INFO = const ErrorSeverity('INFO', 1, "I", "info");
+
+  /**
+   * The severity representing a warning. Warnings can become errors if the `-Werror` command
+   * line flag is specified.
+   */
+  static const ErrorSeverity WARNING =
+      const ErrorSeverity('WARNING', 2, "W", "warning");
+
+  /**
+   * The severity representing an error.
+   */
+  static const ErrorSeverity ERROR =
+      const ErrorSeverity('ERROR', 3, "E", "error");
+
+  static const List<ErrorSeverity> values = const [NONE, INFO, WARNING, ERROR];
+
+  /**
+   * The name of this error code.
+   */
+  final String name;
+
+  /**
+   * The ordinal value of the error code.
+   */
+  final int ordinal;
+
+  /**
+   * The name of the severity used when producing machine output.
+   */
+  final String machineCode;
+
+  /**
+   * The name of the severity used when producing readable output.
+   */
+  final String displayName;
+
+  /**
+   * Initialize a newly created severity with the given names.
+   */
+  const ErrorSeverity(
+      this.name, this.ordinal, this.machineCode, this.displayName);
+
+  @override
+  int get hashCode => ordinal;
+
+  @override
+  int compareTo(ErrorSeverity other) => ordinal - other.ordinal;
+
+  /**
+   * Return the severity constant that represents the greatest severity.
+   */
+  ErrorSeverity max(ErrorSeverity severity) =>
+      this.ordinal >= severity.ordinal ? this : severity;
+
+  @override
+  String toString() => name;
+}
+
+/**
+ * The type of an [ErrorCode].
+ */
+class ErrorType implements Comparable<ErrorType> {
+  /**
+   * Task (todo) comments in user code.
+   */
+  static const ErrorType TODO = const ErrorType('TODO', 0, ErrorSeverity.INFO);
+
+  /**
+   * Extra analysis run over the code to follow best practices, which are not in
+   * the Dart Language Specification.
+   */
+  static const ErrorType HINT = const ErrorType('HINT', 1, ErrorSeverity.INFO);
+
+  /**
+   * Compile-time errors are errors that preclude execution. A compile time
+   * error must be reported by a Dart compiler before the erroneous code is
+   * executed.
+   */
+  static const ErrorType COMPILE_TIME_ERROR =
+      const ErrorType('COMPILE_TIME_ERROR', 2, ErrorSeverity.ERROR);
+
+  /**
+   * Checked mode compile-time errors are errors that preclude execution in
+   * checked mode.
+   */
+  static const ErrorType CHECKED_MODE_COMPILE_TIME_ERROR = const ErrorType(
+      'CHECKED_MODE_COMPILE_TIME_ERROR', 3, ErrorSeverity.ERROR);
+
+  /**
+   * Static warnings are those warnings reported by the static checker. They
+   * have no effect on execution. Static warnings must be provided by Dart
+   * compilers used during development.
+   */
+  static const ErrorType STATIC_WARNING =
+      const ErrorType('STATIC_WARNING', 4, ErrorSeverity.WARNING);
+
+  /**
+   * Many, but not all, static warnings relate to types, in which case they are
+   * known as static type warnings.
+   */
+  static const ErrorType STATIC_TYPE_WARNING =
+      const ErrorType('STATIC_TYPE_WARNING', 5, ErrorSeverity.WARNING);
+
+  /**
+   * Syntactic errors are errors produced as a result of input that does not
+   * conform to the grammar.
+   */
+  static const ErrorType SYNTACTIC_ERROR =
+      const ErrorType('SYNTACTIC_ERROR', 6, ErrorSeverity.ERROR);
+
+  /**
+   * Lint warnings describe style and best practice recommendations that can be
+   * used to formalize a project's style guidelines.
+   */
+  static const ErrorType LINT = const ErrorType('LINT', 7, ErrorSeverity.INFO);
+
+  static const List<ErrorType> values = const [
+    TODO,
+    HINT,
+    COMPILE_TIME_ERROR,
+    CHECKED_MODE_COMPILE_TIME_ERROR,
+    STATIC_WARNING,
+    STATIC_TYPE_WARNING,
+    SYNTACTIC_ERROR,
+    LINT
+  ];
+
+  /**
+   * The name of this error type.
+   */
+  final String name;
+
+  /**
+   * The ordinal value of the error type.
+   */
+  final int ordinal;
+
+  /**
+   * The severity of this type of error.
+   */
+  final ErrorSeverity severity;
+
+  /**
+   * Initialize a newly created error type to have the given [name] and
+   * [severity].
+   */
+  const ErrorType(this.name, this.ordinal, this.severity);
+
+  String get displayName => name.toLowerCase().replaceAll('_', ' ');
+
+  @override
+  int get hashCode => ordinal;
+
+  @override
+  int compareTo(ErrorType other) => ordinal - other.ordinal;
+
+  @override
+  String toString() => name;
+}
+
+/**
+ * The error codes used for errors detected by the scanner.
+ */
+class ScannerErrorCode extends ErrorCode {
+  /**
+   * Parameters:
+   * 0: the illegal character
+   */
+  static const ScannerErrorCode ILLEGAL_CHARACTER =
+      const ScannerErrorCode('ILLEGAL_CHARACTER', "Illegal character '{0}'.");
+
+  static const ScannerErrorCode MISSING_DIGIT =
+      const ScannerErrorCode('MISSING_DIGIT', "Decimal digit expected.");
+
+  static const ScannerErrorCode MISSING_HEX_DIGIT = const ScannerErrorCode(
+      'MISSING_HEX_DIGIT', "Hexidecimal digit expected.");
+
+  static const ScannerErrorCode MISSING_QUOTE =
+      const ScannerErrorCode('MISSING_QUOTE', "Expected quote (' or \").");
+
+  /**
+   * Parameters:
+   * 0: the path of the file that cannot be read
+   */
+  static const ScannerErrorCode UNABLE_GET_CONTENT = const ScannerErrorCode(
+      'UNABLE_GET_CONTENT', "Unable to get content of '{0}'.");
+
+  static const ScannerErrorCode UNTERMINATED_MULTI_LINE_COMMENT =
+      const ScannerErrorCode(
+          'UNTERMINATED_MULTI_LINE_COMMENT',
+          "Unterminated multi-line comment.",
+          "Try terminating the comment with '*/', or "
+          "removing any unbalanced occurances of '/*' (because comments nest in Dart).");
+
+  static const ScannerErrorCode UNTERMINATED_STRING_LITERAL =
+      const ScannerErrorCode(
+          'UNTERMINATED_STRING_LITERAL', "Unterminated string literal.");
+
+  /**
+   * Initialize a newly created error code to have the given [name]. The message
+   * associated with the error will be created from the given [message]
+   * template. The correction associated with the error will be created from the
+   * given [correction] template.
+   */
+  const ScannerErrorCode(String name, String message, [String correction])
+      : super(name, message, correction);
+
+  @override
+  ErrorSeverity get errorSeverity => ErrorSeverity.ERROR;
+
+  @override
+  ErrorType get type => ErrorType.SYNTACTIC_ERROR;
+}