Add a public API for the results of constant evaluation

pkg/analyzer/lib/src/generated/constant.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 engine.constant;
 
 import 'dart:collection';
 
 import 'package:analyzer/src/generated/engine.dart';
 import 'package:analyzer/src/generated/utilities_general.dart';
@@ skipping 293 matching lines @@
       HashMap<String, DartObjectImpl> namedArgumentValues) {
     if (arguments.length != 1) {
       return false;
     }
     if (arguments[0] is NamedExpression) {
       return false;
     }
     if (!identical(argumentValues[0].type, typeProvider.stringType)) {
       return false;
     }
-    String name = argumentValues[0].stringValue;
+    String name = argumentValues[0].toStringValue();
     return isValidPublicSymbol(name);
   }
 
   /**
    * Compute the constant value associated with the given [constant].
    */
   void computeConstantValue(ConstantEvaluationTarget constant) {
     validator.beforeComputeValue(constant);
     if (constant is ParameterElement) {
       if (constant.initializer != null) {
@@ skipping 294 matching lines @@
       // See if it's because we reached an external const factory constructor
       // that we can emulate.
       if (constructor.name == "fromEnvironment") {
         if (!checkFromEnvironmentArguments(
             arguments, argumentValues, namedArgumentValues, definingClass)) {
           errorReporter.reportErrorForNode(
               CompileTimeErrorCode.CONST_EVAL_THROWS_EXCEPTION, node);
           return null;
         }
         String variableName =
-            argumentCount < 1 ? null : argumentValues[0].stringValue;
+            argumentCount < 1 ? null : argumentValues[0].toStringValue();
         if (identical(definingClass, typeProvider.boolType)) {
           DartObject valueFromEnvironment;
           valueFromEnvironment =
               _declaredVariables.getBool(typeProvider, variableName);
           return computeValueFromEnvironment(
               valueFromEnvironment,
               new DartObjectImpl(typeProvider.boolType, BoolState.FALSE_STATE),
               namedArgumentValues);
         } else if (identical(definingClass, typeProvider.intType)) {
           DartObject valueFromEnvironment;
@@ skipping 14 matching lines @@
         }
       } else if (constructor.name == "" &&
           identical(definingClass, typeProvider.symbolType) &&
           argumentCount == 1) {
         if (!checkSymbolArguments(
             arguments, argumentValues, namedArgumentValues)) {
           errorReporter.reportErrorForNode(
               CompileTimeErrorCode.CONST_EVAL_THROWS_EXCEPTION, node);
           return null;
         }
-        String argumentValue = argumentValues[0].stringValue;
+        String argumentValue = argumentValues[0].toStringValue();
         return new DartObjectImpl(
             definingClass, new SymbolState(argumentValue));
       }
       // Either it's an external const factory constructor that we can't
       // emulate, or an error occurred (a cycle, or a const constructor trying
       // to delegate to a non-const constructor).
       // In the former case, the best we can do is consider it an unknown value.
       // In the latter case, the error has already been reported, so considering
       // it an unknown value will suppress further errors.
       return new DartObjectImpl.validWithUnknownValue(definingClass);
@@ skipping 916 matching lines @@
     } else if (thenResult == null) {
       return thenResult;
     } else if (elseResult == null) {
       return elseResult;
     }
     conditionResult =
         _dartObjectComputer.applyBooleanConversion(condition, conditionResult);
     if (conditionResult == null) {
       return conditionResult;
     }
-    if (conditionResult.isTrue) {
+    if (conditionResult.toBoolValue() == true) {
       return thenResult;
-    } else if (conditionResult.isFalse) {
+    } else if (conditionResult.toBoolValue() == false) {
       return elseResult;
     }
     ParameterizedType thenType = thenResult.type;
     ParameterizedType elseType = elseResult.type;
     return new DartObjectImpl.validWithUnknownValue(
         _typeSystem.getLeastUpperBound(_typeProvider, thenType, elseType)
         as InterfaceType);
   }
 
   @override
@@ skipping 315 matching lines @@
   DartObjectImpl _valueOf(Expression expression) {
     DartObjectImpl expressionValue = expression.accept(this);
     if (expressionValue != null) {
       return expressionValue;
     }
     return _typeProvider.nullObject;
   }
 }
 
 /**
- * The state of a Dart object.
+ * A representation of the value of a compile-time constant expression.
+ *
+ * Note that, unlike the mirrors system, the object being represented does *not*
+ * exist. This interface allows static analysis tools to determine something
+ * about the state of the object that would exist if the code that creates the
+ * object were executed, but none of the code being analyzed is actually
+ * executed.
  */
 abstract class DartObject {
   /**
    * Return the boolean value of this object, or `null` if either the value of
    * this object is not known or this object is not of type 'bool'.
-   */
+   *
+   * Deprecated. Use [toBoolValue].
+   */
+  @deprecated
   bool get boolValue;
 
   /**
    * Return the floating point value of this object, or `null` if either the
    * value of this object is not known or this object is not of type 'double'.
-   */
+   *
+   * Deprecated. Use [toDoubleValue].
+   */
+  @deprecated
   double get doubleValue;
 
   /**
    * Return `true` if this object's value can be represented exactly.
-   */
+   *
+   * Deprecated. The semantics of this method were not clear. One semantic is
+   * covered by [hasKnownValue].
+   */
+  @deprecated
   bool get hasExactValue;
 
   /**
+   * Return `true` if the value of the object being represented is known.
+   *
+   * This method will return `false` if
+   * * the value being represented is the value of a declared variable (a
+   *   variable whose value is provided at run-time using a `-D` command-line
+   *   option), or
+   * * the value is a function.
+   *
+   * The result of this method does not imply anything about the state of
+   * object representations returned by the method [getField], those that are
+   * elements of the list returned by [toListValue], or the keys or values in
+   * the map returned by [toMapValue]. For example, a representation of a list
+   * can return `true` even if one or more of the elements of that list would
+   * return `false`.
+   */
+  bool get hasKnownValue;
+
+  /**
    * Return the integer value of this object, or `null` if either the value of
    * this object is not known or this object is not of type 'int'.
-   */
+   *
+   * Deprecated. Use [toIntValue].
+   */
+  @deprecated
   int get intValue;
 
   /**
    * Return `true` if this object represents the value 'false'.
-   */
+   *
+   * Deprecated. Use `object.toBoolValue() == false`.
+   */
+  @deprecated
   bool get isFalse;
 
   /**
-   * Return `true` if this object represents the value 'null'.
+   * Return `true` if the object being represented represents the value 'null'.
    */
   bool get isNull;
 
   /**
    * Return `true` if this object represents the value 'true'.
-   */
+   *
+   * Deprecated. Use `object.toBoolValue() == true`.
+   */
+  @deprecated
   bool get isTrue;
 
   /**
    * Return the string value of this object, or `null` if either the value of
    * this object is not known or this object is not of type 'String'.
-   */
+   *
+   * Deprecated. Use [toStringValue].
+   */
+  @deprecated
   String get stringValue;
 
   /**
-   * Return the run-time type of this object.
+   * Return a representation of the type of the object being represented.
+   *
+   * For values resulting from the invocation of a 'const' constructor, this
+   * will be a representation of the run-time type of the object.
+   *
+   * For values resulting from a literal expression, this will be a
+   * representation of the static type of the value -- `int` for integer
+   * literals, `List` for list literals, etc. -- even when the static type is an
+   * abstract type (such as `List`) and hence will never be the run-time type of
+   * the represented object.
+   *
+   * For values resulting from any other kind of expression, this will be a
+   * representation of the result of evaluating the expression.
+   *
+   * Return `null` if the expression cannot be evaluated, either because it is
+   * not a valid constant expression or because one or more of the values used
+   * in the expression does not have a known value.
+   *
+   * This method can return a representation of the type, even if this object
+   * would return `false` from [hasKnownValue].
    */
   ParameterizedType get type;
 
   /**
    * Return this object's value if it can be represented exactly, or `null` if
    * either the value cannot be represented exactly or if the value is `null`.
-   * Clients should use [hasExactValue] to distinguish between these two cases.
-   */
+   * Clients should use `hasExactValue` to distinguish between these two cases.
+   *
+   * Deprecated. Use one of the `isXValue()` methods.
+   */
+  @deprecated
   Object get value;
+
+  /**
+   * Return a representation of the value of the field with the given [name].
+   *
+   * Return `null` if either the object being represented does not have a field
+   * with the given name or if the implementation of the class of the object is
+   * invalid, making it impossible to determine that value of the field.
+   *
+   * Note that, unlike the mirrors API, this method does *not* invoke a getter;
+   * it simply returns a representation of the known state of a field.
+   */
+  DartObject getField(String name);
+
+  /**
+   * Return a boolean corresponding to the value of the object being
+   * represented, or `null` if
+   * * this object is not of type 'bool',
+   * * the value of the object being represented is not known, or
+   * * the value of the object being represented is `null`.
+   */
+  bool toBoolValue();
+
+  /**
+   * Return a double corresponding to the value of the object being represented,
+   * or `null`
+   * if
+   * * this object is not of type 'double',
+   * * the value of the object being represented is not known, or
+   * * the value of the object being represented is `null`.
+   */
+  double toDoubleValue();
+
+  /**
+   * Return an integer corresponding to the value of the object being
+   * represented, or `null` if
+   * * this object is not of type 'int',
+   * * the value of the object being represented is not known, or
+   * * the value of the object being represented is `null`.
+   */
+  int toIntValue();
+
+  /**
+   * Return a list corresponding to the value of the object being represented,
+   * or `null` if
+   * * this object is not of type 'List', or
+   * * the value of the object being represented is `null`.
+   */
+  List<DartObject> toListValue();
+
+  /**
+   * Return a map corresponding to the value of the object being represented, or
+   * `null` if
+   * * this object is not of type 'Map', or
+   * * the value of the object being represented is `null`.
+   */
+  Map<DartObject, DartObject> toMapValue();
+
+  /**
+   * Return a string corresponding to the value of the object being represented,
+   * or `null` if
+   * * this object is not of type 'String',
+   * * the value of the object being represented is not known, or
+   * * the value of the object being represented is `null`.
+   */
+  String toStringValue();
+
+  /**
+   * Return a string corresponding to the value of the object being represented,
+   * or `null` if
+   * * this object is not of type 'Symbol', or
+   * * the value of the object being represented is `null`.
+   * (We return the string
+   */
+  String toSymbolValue();
+
+  /**
+   * Return the representation of the type corresponding to the value of the
+   * object being represented, or `null` if
+   * * this object is not of type 'Type', or
+   * * the value of the object being represented is `null`.
+   */
+  ParameterizedType toTypeValue();
 }
 
 /**
  * A utility class that contains methods for manipulating instances of a Dart
  * class and for collecting errors during evaluation.
  */
 class DartObjectComputer {
   /**
    * The error reporter that we are using to collect errors.
    */
@@ skipping 376 matching lines @@
         return new DartObjectImpl(type, DoubleState.UNKNOWN_VALUE);
       } else if (typeName == "int") {
         return new DartObjectImpl(type, IntState.UNKNOWN_VALUE);
       } else if (typeName == "String") {
         return new DartObjectImpl(type, StringState.UNKNOWN_VALUE);
       }
     }
     return new DartObjectImpl(type, GenericState.UNKNOWN_VALUE);
   }
 
+  @deprecated
   @override
-  bool get boolValue {
-    if (_state is BoolState) {
-      return (_state as BoolState).value;
-    }
-    return null;
-  }
+  bool get boolValue => toBoolValue();
 
+  @deprecated
   @override
-  double get doubleValue {
-    if (_state is DoubleState) {
-      return (_state as DoubleState).value;
-    }
-    return null;
-  }
+  double get doubleValue => toDoubleValue();
 
   HashMap<String, DartObjectImpl> get fields => _state.fields;
 
+  @deprecated
   @override
   bool get hasExactValue => _state.hasExactValue;
 
   @override
   int get hashCode => JenkinsSmiHash.hash2(type.hashCode, _state.hashCode);
 
   @override
-  int get intValue {
-    if (_state is IntState) {
-      return (_state as IntState).value;
-    }
-    return null;
-  }
+  bool get hasKnownValue => !_state.isUnknown;
+
+  @deprecated
+  @override
+  int get intValue => toIntValue();
 
   /**
    * Return `true` if this object represents an object whose type is 'bool'.
    */
   bool get isBool => _state.isBool;
 
   /**
    * Return `true` if this object represents an object whose type is either
    * 'bool', 'num', 'String', or 'Null'.
    */
   bool get isBoolNumStringOrNull => _state.isBoolNumStringOrNull;
 
+  @deprecated
   @override
-  bool get isFalse =>
-      _state is BoolState && identical((_state as BoolState).value, false);
+  bool get isFalse => toBoolValue() == false;
 
   @override
   bool get isNull => _state is NullState;
 
+  @deprecated
   @override
   bool get isTrue =>
       _state is BoolState && identical((_state as BoolState).value, true);
 
   /**
    * Return `true` if this object represents an unknown value.
    */
   bool get isUnknown => _state.isUnknown;
 
   /**
    * Return `true` if this object represents an instance of a user-defined
    * class.
    */
   bool get isUserDefinedObject => _state is GenericState;
 
+  @deprecated
   @override
-  String get stringValue {
-    if (_state is StringState) {
-      return (_state as StringState).value;
-    }
-    return null;
-  }
+  String get stringValue => toStringValue();
 
+  @deprecated
   @override
   Object get value => _state.value;
 
   @override
   bool operator ==(Object object) {
     if (object is! DartObjectImpl) {
       return false;
     }
     DartObjectImpl dartObject = object as DartObjectImpl;
     return type == dartObject.type && _state == dartObject._state;
@@ skipping 141 matching lines @@
           typeName == "Null" ||
           type.isDynamic)) {
         throw new EvaluationException(
             CompileTimeErrorCode.CONST_EVAL_TYPE_BOOL_NUM_STRING);
       }
     }
     return new DartObjectImpl(
         typeProvider.boolType, _state.equalEqual(rightOperand._state));
   }
 
+  @override
+  DartObject getField(String name) {
+    if (_state is GenericState) {
+      return (_state as GenericState).fields[name];
+    }
+    return null;
+  }
+
   /**
    * Return the result of invoking the '&gt;' operator on this object with the
    * [rightOperand]. The [typeProvider] is the type provider used to find known
    * types.
    *
    * Throws an [EvaluationException] if the operator is not appropriate for an
    * object of this kind.
    */
   DartObjectImpl greaterThan(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
@@ skipping 253 matching lines @@
     } else if (result is DoubleState) {
       return new DartObjectImpl(typeProvider.doubleType, result);
     } else if (result is NumState) {
       return new DartObjectImpl(typeProvider.numType, result);
     }
     // We should never get here.
     throw new IllegalStateException("times returned a ${result.runtimeType}");
   }
 
   @override
+  bool toBoolValue() {
+    if (_state is BoolState) {
+      return (_state as BoolState).value;
+    }
+    return null;
+  }
+
+  @override
+  double toDoubleValue() {
+    if (_state is DoubleState) {
+      return (_state as DoubleState).value;
+    }
+    return null;
+  }
+
+  @override
+  int toIntValue() {
+    if (_state is IntState) {
+      return (_state as IntState).value;
+    }
+    return null;
+  }
+
+  @override
+  List<DartObject> toListValue() {
+    if (_state is ListState) {
+      return (_state as ListState)._elements;
+    }
+    return null;
+  }
+
+  @override
+  Map<DartObject, DartObject> toMapValue() {
+    if (_state is MapState) {
+      return (_state as MapState)._entries;
+    }
+    return null;
+  }
+
+  @override
   String toString() => "${type.displayName} ($_state)";
+
+  @override
+  String toStringValue() {
+    if (_state is StringState) {
+      return (_state as StringState).value;
+    }
+    return null;
+  }
+
+  @override
+  String toSymbolValue() {
+    if (_state is SymbolState) {
+      return (_state as SymbolState).value;
+    }
+    return null;
+  }
+
+  @override
+  ParameterizedType toTypeValue() {
+    if (_state is TypeState) {
+      Element element = (_state as TypeState).value;
+      if (element is ClassElement) {
+        return element.type;
+      }
+      if (element is FunctionElement) {
+        return element.type;
+      }
+    }
+    return null;
+  }
 }
 
 /**
  * An object used to provide access to the values of variables that have been
  * defined on the command line using the `-D` option.
  */
 class DeclaredVariables {
   /**
    * A table mapping the names of declared variables to their values.
    */
@@ skipping 2412 matching lines @@
       return BoolState.from(_element == rightElement);
     } else if (rightOperand is DynamicState) {
       return BoolState.UNKNOWN_VALUE;
     }
     return BoolState.FALSE_STATE;
   }
 
   @override
   String toString() => _element == null ? "-unknown-" : _element.name;
 }