code_transformers 0.2.8

Code Transformers #

This package exposes various tools to help in the creation and testing of barback transformers, as well as an interface for logging messages with constant ids for documentation purposes.

Messages and logging #

This package exposes a BuildLogger class as well as Message, MessageTemplate, and MessageId classes. These work together to provide stable error messages with ids that can be referenced in documentation.

MessageId #

A MessageId is a constant definition of a message in a package. These are used to group messages with the same id or link to sections in a document.

const myId = const MessageId('myPackage', 0);

These ids should typically never change or disappear throughout the entire lifetime of a package.

Message #

A Message is a const object which has a MessageId and snippet.

const myMessage = const Message(myId, 'my message');

MessageTemplate #

TODO(jakemac): Docs on this, see https://github.com/dart-lang/code-transformers/blob/master/lib/messages/messages.dart

BuildLogger #

The BuildLogger class just wraps a normal TransformLogger to provide some additional functionality. You use it in the same way as a TransformLogger except that the log methods can accept a String or a Message. This should usually be created in the first step of your transformers apply function:

apply(Transform transform) {
  // If detailsUri is passed, then a link will be output with each log
  // message that follows this format
  // `$detailsUri#${msg.id.package}_${msg.id.id}`.
  var logger = new BuildLogger(transform, detailsUri: 'http://foo.com');
}

You can optionally dump out a file containing all the logs found in JSON format by calling the writeOutput method on the logger when you are done. The output file will have the same file path as the primary input of the transformer, with an extension matching this pattern ._buildLogs.$i. The i increments starting at 0 each time that logs are output (if multiple transformers run on the same file for instance). These can all be combined into a single file later on by calling the static combineLogFiles(Transform transform) function.

Testing Transformers #

TODO(jakemac): Docs on this, see testPhases in https://github.com/dart-lang/code-transformers/blob/master/lib/tests.dart

Using the Analyzer in Transformers #

This package exposes a Resolver class which helps out when using the analyzer in a transform.

TODO(jakemac): Docs on this, see https://github.com/dart-lang/code-transformers/blob/master/lib/src/resolver.dart

Barback AssetIds and Uris #

This package also provides some helpers to convert AssetIds to and from Uris relative to a source asset.

TODO(jakemac): Docs on this, see uriToAssetId & assetIdToUri in https://github.com/dart-lang/code-transformers/blob/master/lib/assets.dart

0.2.8 #

  • Add benchmarks.dart file which exposes a TransformerBenchmark. This can be used to implement simple benchmarks of transformer code.

0.2.7+2 #

  • Fix assetIdToUri on windows, 41

0.2.7+1 #

  • Fixes for missing overrides after upgrade to analzyer 0.24.0

0.2.7 #

  • Added default set of mockSdkSources and upgraded to analyzer 0.24.0

0.2.6 #

  • Added assetIdToUri to assets.dart.

0.2.5 #

  • Improvements to dartSdkDirectory so it has a better chance of success.
  • BuildLogger now accepts AggregateTransform or Transform. If passing in an AggregateTransform you must also pass in an AssetId to use as the primary input.

0.2.4 #

  • Added some basic string formatting options to testPhases to make it a bit less strict if desired.

0.2.3+2 #

  • Added logic to discover the location of the dart SDK when the dart binary is a symlink.

0.2.3 #

  • Added support for logging stable error messages from transformers.

0.2.2 #

  • Added two transformers, 'delete_file' and 'remove_sourcemap_comment'.

0.2.0+3 #

  • Raise the lower bound on the source_maps constraint to exclude incompatible versions.

0.2.0+2 #

  • Widen the constraint on source_maps.

0.2.0+1 #

  • Widen the constraint on barback.

0.2.0 #

  • Switch from source_maps' Span class to source_span's SourceSpan class.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  code_transformers: ^0.2.8

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:code_transformers/assets.dart';
import 'package:code_transformers/benchmarks.dart';
import 'package:code_transformers/messages/build_logger.dart';
import 'package:code_transformers/messages/messages.dart';
import 'package:code_transformers/resolver.dart';
import 'package:code_transformers/tests.dart';
  
Awaiting analysis to complete.

Admin