| // 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. | |
| /// Defines messages templates and an adapter for TransformLogger to be able | |
| /// report error messages from transformers and refer to them in a consistent | |
| /// manner long term. | |
| library code_transformers.messages; | |
| // Note: this library purposely doesn't depend on dart:io, dart:html, or barback | |
| // so it can easily be used both in the transformers and in client-side apps | |
| // (for example in the log_injector). | |
| import 'dart:collection' show LinkedHashMap; | |
| import 'package:source_span/source_span.dart'; | |
| /// A globally unique identifier for an error message. This identifier should be | |
| /// stable, that is, it should never change after it is asigned to a particular | |
| /// message. That allows us to document our error messages and make them | |
| /// searchable for prosperity. | |
| class MessageId implements Comparable { | |
| /// Name of the package that declares this message. | |
| final String package; | |
| /// Message identifier number, unique within the package. | |
| final int id; | |
| const MessageId(this.package, this.id); | |
| static const MessageId NOT_SPECIFIED = const MessageId('unknown', 0); | |
| /// Serialize this message. We use a string and not a map to encode ids so | |
| /// they can be used as keys in JSON maps. | |
| String toJson() => toString(); | |
| toString() => '${package}#$id'; | |
| int compareTo(MessageId other) { | |
| var res = package.compareTo(other.package); | |
| if (res != 0) return res; | |
| return id.compareTo(other.id); | |
| } | |
| /// Creates a new [MessageId] from an encoded value produced via [toJson]. | |
| factory MessageId.fromJson(data) { | |
| var index = data.lastIndexOf('#'); | |
| if (index == -1) throw 'Invalid message id: $data'; | |
| return new MessageId( | |
| data.substring(0, index), int.parse(data.substring(index + 1))); | |
| } | |
| operator ==(MessageId other) => package == other.package && id == other.id; | |
| int get hashCode => 31 * package.hashCode + id; | |
| } | |
| /// An instance of an error message. These are typically produced from a | |
| /// [MessageTemplate]. | |
| class Message { | |
| /// A globally unique identifier for this message. | |
| final MessageId id; | |
| /// A snippet message that is presented to the user. | |
| final String snippet; | |
| const Message(this.id, this.snippet); | |
| const Message.unknown(this.snippet) : id = MessageId.NOT_SPECIFIED; | |
| /// Serializes this message to JSON. | |
| Map toJson() => {'id': id.toJson(), 'snippet': snippet}; | |
| String toString() => 'id: $id, snippet: $snippet'; | |
| /// Creates a new [Message] from an encoded value produced via [toJson]. | |
| factory Message.fromJson(data) => | |
| new Message(new MessageId.fromJson(data['id']), data['snippet']); | |
| } | |
| /// Template for a message. Templates can include placeholders to indicate | |
| /// values that are different for each instance of the error. Calling [create] | |
| /// will generate the actual message, with the placeholders replaced with | |
| /// values. If there are no placeholders, an instance of [MessageTemplate] is a | |
| /// valid instance of [Message] as well. | |
| class MessageTemplate implements Message { | |
| /// Unique and stable id for the message. | |
| final MessageId id; | |
| /// Template message with placeholders of the form `%-name-%`. | |
| final String snippetTemplate; | |
| /// This returns the message snippet, only if it the template has no | |
| /// placeholders, otherwise this throws an exception. Most messages have no | |
| /// placeholder arguments, in those cases, the snippet can be computed | |
| /// without specifying any arguments (exactly like calling `create()` with no | |
| /// arguments). | |
| String get snippet => _createSnippet(); | |
| /// Short description of the error message, typically used as a title of the | |
| /// error message in autogenerated documentation. This should be a single | |
| /// phrase, and cannot use placeholders. | |
| final String description; | |
| /// Additional details about this error message. These are used to | |
| /// automatically generate documentation. | |
| final String details; | |
| const MessageTemplate( | |
| this.id, this.snippetTemplate, this.description, this.details); | |
| static final _placeholderPattern = new RegExp(r"%-(\w*)-%"); | |
| _createSnippet([Map args = const {}, bool fillUnknowns = false]) { | |
| var snippet = snippetTemplate.replaceAllMapped(_placeholderPattern, (m) { | |
| var arg = m.group(1); | |
| var value = args[arg]; | |
| if (value != null) return '$value'; | |
| if (fillUnknowns) return ''; | |
| throw "missing argument $arg, for error message: $snippetTemplate"; | |
| }); | |
| return snippet; | |
| } | |
| create([Map args = const {}, bool fillUnknowns = false]) => | |
| new Message(id, _createSnippet(args, fillUnknowns)); | |
| /// Serializes this message to JSON. | |
| Map toJson() => create().toJson(); | |
| String toString() => '${toJson()}'; | |
| } | |
| /// Represents an actual log entry for a build error message. Including the | |
| /// actual message, its severity level (warning, error, etc), and a source span | |
| /// for a code location that is revelant to the message. | |
| class BuildLogEntry { | |
| /// The actual message. | |
| final Message message; | |
| /// Severity level. | |
| final String level; | |
| /// Location associated with this message, if any. | |
| final SourceSpan span; | |
| BuildLogEntry(this.message, this.span, this.level); | |
| /// Creates a new [BuildLogEntry] from an encoded value produced via [toJson]. | |
| factory BuildLogEntry.fromJson(Map data) { | |
| var spanData = data['span']; | |
| var span = null; | |
| if (spanData != null) { | |
| var locData = spanData['start']; | |
| var start = new SourceLocation(locData['offset'], | |
| sourceUrl: Uri.parse(locData['url']), | |
| line: locData['line'], | |
| column: locData['column']); | |
| locData = spanData['end']; | |
| var end = new SourceLocation(locData['offset'], | |
| sourceUrl: Uri.parse(locData['url']), | |
| line: locData['line'], | |
| column: locData['column']); | |
| span = new SourceSpan(start, end, spanData['text']); | |
| } | |
| return new BuildLogEntry( | |
| new Message.fromJson(data['message']), span, data['level']); | |
| } | |
| /// Serializes this log entry to JSON. | |
| Map toJson() { | |
| var data = {'level': level, 'message': message.toJson(),}; | |
| if (span != null) { | |
| data['span'] = { | |
| 'start': { | |
| 'url': span.start.sourceUrl.toString(), | |
| 'offset': span.start.offset, | |
| 'line': span.start.line, | |
| 'column': span.start.column, | |
| }, | |
| 'end': { | |
| 'url': span.end.sourceUrl.toString(), | |
| 'offset': span.end.offset, | |
| 'line': span.end.line, | |
| 'column': span.end.column, | |
| }, | |
| 'text': span.text, | |
| }; | |
| } | |
| return data; | |
| } | |
| String toString() => '${toJson()}'; | |
| } | |
| /// A table of entries, that clusters error messages by id. | |
| class LogEntryTable { | |
| final Map<MessageId, List<BuildLogEntry>> entries; | |
| LogEntryTable() : entries = new LinkedHashMap(); | |
| /// Creates a new [LogEntryTable] from an encoded value produced via [toJson]. | |
| factory LogEntryTable.fromJson(Map json) { | |
| var res = new LogEntryTable(); | |
| for (String key in json.keys) { | |
| var id = new MessageId.fromJson(key); | |
| res.entries[id] = | |
| json[key].map((v) => new BuildLogEntry.fromJson(v)).toList(); | |
| } | |
| return res; | |
| } | |
| /// Serializes this entire table as JSON. | |
| Map toJson() { | |
| var res = {}; | |
| entries.forEach((key, value) { | |
| res['$key'] = value.map((e) => e.toJson()).toList(); | |
| }); | |
| return res; | |
| } | |
| String toString() => '${toJson()}'; | |
| void add(BuildLogEntry entry) { | |
| entries.putIfAbsent(entry.message.id, () => []).add(entry); | |
| } | |
| void addAll(LogEntryTable other) { | |
| for (var key in other.entries.keys) { | |
| var values = entries.putIfAbsent(key, () => []); | |
| values.addAll(other.entries[key]); | |
| } | |
| } | |
| } |