pkg/front_end/lib/src/base/errors.dart - sdk.git - Git at Google

 // Copyright (c) 2016, 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.

 /**
  * 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 {
   /**
    * 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;
 }

 /**
  * 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;
 }
	// Copyright (c) 2016, 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.

	/**
	* 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 {
	/**
	* 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;
	}

	/**
	* 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;
	}