| // 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. |
| |
| /// Collects services that can be used to access objects dynamically, inspect |
| /// type information, and convert between symbols and strings. |
| library smoke; |
| |
| import 'src/implementation.dart' as implementation; |
| |
| export 'src/common.dart' show minArgs, maxArgs, SUPPORTED_ARGS; |
| import 'src/common.dart' show compareLists; |
| |
| /// Configures this library to use [objectAccessor] for all read/write/invoke |
| /// APIs, [typeInspector] for all type query APIs, and [symbolConverter] for all |
| /// symbol convertion operations. |
| /// |
| /// This function doesn't need to be called during development, but frameworks |
| /// should autogenerate a call to this function when running in deployment. |
| void configure(ObjectAccessorService objectAccessor, |
| TypeInspectorService typeInspector, |
| SymbolConverterService symbolConverter) { |
| implementation.objectAccessor = objectAccessor; |
| implementation.typeInspector = typeInspector; |
| implementation.symbolConverter = symbolConverter; |
| } |
| |
| /// Return the value of [field] in [object]. |
| read(Object object, Symbol field) => |
| implementation.objectAccessor.read(object, field); |
| |
| /// Update the [value] of [field] in [object]. |
| void write(Object object, Symbol field, value) => |
| implementation.objectAccessor.write(object, field, value); |
| |
| /// Invoke [method] in [receiver] with [args]. The [receiver] can be either an |
| /// object (to invoke instance methods) or a type (to invoke static methods). |
| /// This function optionally [adjust]s the list of arguments to match the number |
| /// of formal parameters by either adding nulls for missing arguments, or by |
| /// truncating the list. |
| invoke(receiver, Symbol method, List args, |
| {Map namedArgs, bool adjust: false}) => |
| implementation.objectAccessor.invoke( |
| receiver, method, args, namedArgs: namedArgs, adjust: adjust); |
| |
| /// Tells whether [type] is transitively a subclass of [supertype]. |
| bool isSubclassOf(Type type, Type supertype) => |
| implementation.typeInspector.isSubclassOf(type, supertype); |
| |
| // TODO(sigmund): consider adding also: |
| // * isImplementationOf(type, subtype) to tells whether [type] declares that it |
| // implements the [supertype] interface. |
| // * isSubtypeOf(type, subtype): Tells whether [type]'s interface is a sybtype |
| // of [supertype]. That is, whether it is a subclass or if [type] implements |
| // [supertype]. |
| |
| /// Tells whether [type] has a field or getter for [field]. |
| bool hasGetter(Type type, Symbol field) => |
| implementation.typeInspector.hasGetter(type, field); |
| |
| /// Tells whether [type] has a field or setter for [field]. |
| bool hasSetter(Type type, Symbol field) => |
| implementation.typeInspector.hasSetter(type, field); |
| |
| /// Tells whether [type] or a superclass (other than [Object]) defines |
| /// `noSuchMethod`. |
| bool hasNoSuchMethod(Type type) => hasInstanceMethod(type, #noSuchMethod); |
| |
| /// Tells whether [type] has or a superclass contains a specific instance |
| /// [method] (excluding methods in [Object]). |
| bool hasInstanceMethod(Type type, Symbol method) => |
| implementation.typeInspector.hasInstanceMethod(type, method); |
| |
| /// Tells whether [type] has a specific static [method]. |
| bool hasStaticMethod(Type type, Symbol method) => |
| implementation.typeInspector.hasStaticMethod(type, method); |
| |
| /// Get the declaration associated with field [name] found in [type] or a |
| /// superclass of [type]. |
| Declaration getDeclaration(Type type, Symbol name) => |
| implementation.typeInspector.getDeclaration(type, name); |
| |
| /// Retrieve all symbols of [type] that match [options]. |
| List<Declaration> query(Type type, QueryOptions options) => |
| implementation.typeInspector.query(type, options); |
| |
| /// Returns the name associated with a [symbol]. |
| String symbolToName(Symbol symbol) => |
| implementation.symbolConverter.symbolToName(symbol); |
| |
| /// Returns the symbol associated with a [name]. |
| Symbol nameToSymbol(String name) => |
| implementation.symbolConverter.nameToSymbol(name); |
| |
| /// Establishes the parameters for [query] to search for symbols in a type |
| /// hierarchy. For now only public instance symbols can be queried (no private, |
| /// no static). |
| class QueryOptions { |
| /// Whether to include fields (default is true). |
| final bool includeFields; |
| |
| /// Whether to include getters and setters (default is true). Note that to |
| /// include fields you also need to enable [includeFields]. |
| final bool includeProperties; |
| |
| /// Whether to include symbols from the given type and its superclasses |
| /// (except [Object]). |
| final bool includeInherited; |
| |
| /// If [includeInherited], walk up the type hierarchy up to this type |
| /// (defaults to [Object]). |
| final Type includeUpTo; |
| |
| /// Whether to include final fields and getter-only properties. |
| final bool excludeFinal; |
| |
| /// Whether to include methods (default is false). |
| final bool includeMethods; |
| |
| /// If [withAnnotation] is not null, then it should be a list of types, so |
| /// only symbols that are annotated with instances of those types are |
| /// included. |
| final List withAnnotations; |
| |
| /// If [matches] is not null, then include only those fields, properties, or |
| /// methods that match the predicate. |
| final NameMatcher matches; |
| |
| const QueryOptions({ |
| this.includeFields: true, |
| this.includeProperties: true, |
| this.includeInherited: true, |
| this.includeUpTo: Object, |
| this.excludeFinal: false, |
| this.includeMethods: false, |
| this.withAnnotations: null, |
| this.matches: null}); |
| |
| String toString() => (new StringBuffer() |
| ..write('(options:') |
| ..write(includeFields ? 'fields ' : '') |
| ..write(includeProperties ? 'properties ' : '') |
| ..write(includeMethods ? 'methods ' : '') |
| ..write(includeInherited ? 'inherited ' : '_') |
| ..write(excludeFinal ? 'no finals ' : '') |
| ..write('annotations: $withAnnotations') |
| ..write(matches != null ? 'with matcher' : '') |
| ..write(')')).toString(); |
| } |
| |
| /// Used to filter query results based on a predicate on [name]. Returns true if |
| /// [name] should be included in the query results. |
| typedef bool NameMatcher(Symbol name); |
| |
| /// Information associated with a symbol declaration (like a property or |
| /// method). |
| class Declaration { |
| /// Name of the property or method |
| final Symbol name; |
| |
| /// Kind of declaration (field, property, or method). |
| final DeclarationKind kind; |
| |
| /// Whether the symbol is a field (and not a getter/setter property). |
| bool get isField => kind == FIELD; |
| |
| /// Whether the symbol is a getter/setter and not a field. |
| bool get isProperty => kind == PROPERTY; |
| |
| /// Whether the symbol is a method. |
| bool get isMethod => kind == METHOD; |
| |
| /// For fields, whether they are final, for properties, whether they are |
| /// read-only (they have no setter). |
| final bool isFinal; |
| |
| /// If this is a field or property, it's declared type (including dynamic if |
| /// it's not declared). For methods, the returned type. |
| final Type type; |
| |
| /// Whether this symbol is static. |
| final bool isStatic; |
| |
| /// List of annotations in this declaration. |
| final List annotations; |
| |
| const Declaration(this.name, this.type, {this.kind: FIELD, |
| this.isFinal: false, this.isStatic: false, this.annotations: const []}); |
| |
| int get hashCode => name.hashCode; |
| operator ==(other) => other is Declaration && name == other.name && |
| kind == other.kind && isFinal == other.isFinal && |
| type == other.type && isStatic == other.isStatic && |
| compareLists(annotations, other.annotations); |
| |
| String toString() { |
| return (new StringBuffer() |
| ..write('(declaration ') |
| ..write(name) |
| ..write(isProperty ? ' (property) ' : ' (method) ') |
| ..write(isFinal ? 'final ' : '') |
| ..write(isStatic ? 'static ' : '') |
| ..write(annotations) |
| ..write(')')).toString(); |
| } |
| } |
| |
| /// Enumeration for declaration kinds (field, property, or method) |
| class DeclarationKind { |
| final int kind; |
| const DeclarationKind(this.kind); |
| } |
| |
| /// Declaration kind used to denote a raw field. |
| const FIELD = const DeclarationKind(0); |
| |
| /// Declaration kind used to denote a getter/setter. |
| const PROPERTY = const DeclarationKind(1); |
| |
| /// Declaration kind used to denote a method. |
| const METHOD = const DeclarationKind(2); |
| |
| |
| /// A service that provides a way to implement simple operations on objects like |
| /// read, write, and invoke. |
| abstract class ObjectAccessorService { |
| /// Return the value of [field] in [object]. |
| read(Object object, Symbol field); |
| |
| /// Update the [value] of [field] in [object]. |
| void write(Object object, Symbol field, value); |
| |
| /// Invoke [method] in [object] with [args]. It optionally [adjust]s the list |
| /// of arguments to match the number of formal parameters by either adding |
| /// nulls for missing arguments, or by truncating the list. |
| invoke(Object object, Symbol method, List args, |
| {Map namedArgs, bool adjust: false}); |
| } |
| |
| |
| /// A service that provides partial inspection into Dart types. |
| abstract class TypeInspectorService { |
| /// Tells whether [type] is transitively a subclass of [supertype]. |
| bool isSubclassOf(Type type, Type supertype); |
| |
| /// Tells whether [type] has a field or getter for [name]. |
| bool hasGetter(Type type, Symbol name); |
| |
| /// Tells whether [type] has a field or setter for [name]. |
| bool hasSetter(Type type, Symbol name); |
| |
| /// Tells whether [type] has a specific instance [method]. |
| bool hasInstanceMethod(Type type, Symbol method); |
| |
| /// Tells whether [type] has a specific static [method]. |
| bool hasStaticMethod(Type type, Symbol method); |
| |
| /// Get the declaration associated with field [name] in [type]. |
| Declaration getDeclaration(Type type, Symbol name); |
| |
| /// Retrieve all symbols of [type] that match [options]. |
| List<Declaration> query(Type type, QueryOptions options); |
| } |
| |
| |
| /// A service that converts between [Symbol]s and [String]s. |
| abstract class SymbolConverterService { |
| /// Returns the name associated with a [symbol]. |
| String symbolToName(Symbol symbol); |
| |
| /// Returns the symbol associated with a [name]. |
| Symbol nameToSymbol(String name); |
| } |