repository
field.2.18
.TypeChecker
.preamble
option to combining_builder
.analyzer: '>=4.6.0 <6.0.0'
sdk: '>=2.17.0 <3.0.0'
formatOutput
function to the PartBuilder
or LibraryBuilder
constructors.package:analyzer
.LibraryElement
in LibraryReader.allElements
, LibraryReader.annotatedWith
, and LibraryReader.annotatedWithExact
. Run GeneratorForAnnotation
generators on library elements when the library
statement has the annotation.build_extensions
configuration to the PartBuilder
and LibraryBuilder
. You must forward the BuilderOptions
object to the super constructor for this to work.part
statements on Windows.package:pedantic
.build_extensions
option to combining_builder
, allowing output files to be generated into a different directory.package:analyzer
.TypeChecker.fromRuntimeType
for types that come from non-package uris.package:analyzer
version 1.7.0
.ConstantReader.isAny
.ConstantReader.anyValue
.LibraryReader.classElements
.dart_style
range to include v2.x.package:build
version 2.0.0
.DartType.aliasElement
.package:analyzer
.package:analyzer
version 0.41.x
.allowSyntaxErrors
flag introduced in package:build
version 1.4.0
.2.10.0
.package:analyzer
version 0.40.x
.PartBuilder
.Set
in ConstantReader
.isLiteral
and literalValue
to handle Set
.isSet
and setValue
members.2.7.0
.LibraryReader.allElements
to include extensions.Add support for an ignore_for_file
option to combining_builder
.
Expand documentation for GeneratorForAnnotation
to make it clear that it only targets elements at the top level of a library.
Element
reported is in a summary file rather than a source file.package:analyzer
version 0.39.x
.analyzer
.pkg:analyzer
version 0.38.x
.pkg:analyzer
version 0.37.x
.pkg:analyzer
version 0.36.x
.pkg:analyzer
.ParsedLibraryResult
to find source spans for unresolvable annotations.LibraryReader.classElements
to LibraryReader.classes
to better reflect the behavior. Deprecate the old name.LibraryReader.enums
.LibraryReader
.pkg:analyzer
.spanForElement
.package:build
version 1.0.0.The result of ConstantReader.revive()
now returns a Revivable
that assumes access to a private class, constructor, or function instead of null
where possible. This allows generators that use part
files to still use this functionality and allows generators that use separate libraries to emit more actionable error messages (i.e. "cannot use private class _X"
).
Revivable.isPrivate
now returns true
when the underlying class was public but the constructor was private, or the Revivable
was pointing to a top-level or static private field or method. Previously it was only true
when referencing a private class.
LibraryReader.classElements
to return classes from parts, if they exist, as well as from the defining library file.SharedPartBuilder
for creating part files that can be merged with a new CombiningBuilder
. Note that CombiningBuilder
only outputs .g.dart
files.PartBuilder
now requires a generatedExtensions
argument. The value should not be .g.dart
. To produce .g.dart
files please use the SharedPartBuilder
.GeneratorForAnnotation
generateForAnnotatedElement
now allow multiple return values when implementations return an Iterable
or Stream
.generateForAnnotatedElement
have whitespace trimmed. null
and empty values are ignored.Simplification to the output of generator names in header sections.
Update handling of whitespace in generator outputs.
package:analyzer
0.32.0
.Cleanup logging output that duplicates headers provided by package:build_runner
.
InvalidGenerationSourceError
added an optional element
parameter to support more helpful error messages.
BREAKING removed the deprecated requireLibraryDirective
parameter in PartBuilder
.
Revivable
no longer throws a type error when attempting to revive a reference to a top-level function or static-class method. Now is returns a reference to that function or method, as expected.
TypeChecker
now throws an UnresolvedAnnotationException
with a more detailed exception body (and properties useful for further debugging) instead of Could not resolve @null
.LibraryBuilder
and PartBuilder
now have a more readable toString()
, which is useful when emitting a warning or error in a build system. For example you may see Generating .g.dart: MyBuilder
instead of Instance of LibraryBuilder
in your build logs.The PartBuilder
constructor parameter requireLibraryDirective
now defaults to false
. It will be removed in 0.8.0
.
Require at least Dart 2.0.0-dev.19.0
.
analyzer
package.BUG FIX: ConstantReader.revive()
now properly returns no URL fragment when the constant expression is resolved from a top-level or static-field. The documentation had said otherwise, and it was impossible to tell the difference between a constructor and a field. Now, fields are always in the form of accessor = {clazz}.{field}
or {topLevelField}
.
Fix file URIs on windows.
log.finest
with the output source of each generator. This allows a verbose option (-v
) for tools like bazel or build_runner to be much more readable and debuggable. Files are emitted to disk for inspection in any case.Added typeNameOf
, which is a safe way to get the name of a DartType
, even when the type is a FunctionType
, which has a null
name in newer versions of the Dart analyzer.
Added LibraryReader.pathToUrl(Uri|String)
, which computes the import
or export
path necessary to reach the provided URL from the current library. Also added pathToAsset
and pathToElement
as convenience functions.
Expanded package:build
support to allow version 0.12.0
.
GeneratorForAnnotation
.package:build
version 0.11.0header
argument to PartBuilder
and LibraryBuilder
.Generator{ForAnnotation}
generate{ForAnnotatedElement}
is now FutureOr<String>
.LibraryReader
annotatedElements
to return all elements annotated with something.classElements
getter for returning all class
-es in a library.TypeChecker
hasAnnotationOf
and hasAnnotationOfExact
.ConstantReader
isAny
(for consistency, but deprecated) and isLiteral
.literalValue
as an alias for the now deprecated anyValue
.literalValue
to return null
if the value is actually null
.Symbol
would return as a String
for anyValue
.List
and Map
were not considered literals.Breaking changes: See the wiki for help upgrading.
Generator.generate
now operates on a LibraryReader
rather than being called for every Element
within a library. Generators can iterate over elements using LibraryReader.allElements
. GeneratorForAnnotation
will continue to call generateForAnnotatedElement
repeatedly for each element.GeneratorForAnnotation
passes in a ConstantReader
for the annotation instance rather than re-creating it using mirrors.GeneratorBuilder
is replaced with PartBuilder
and LibraryBuilder
depending on whether the output is meant to be included in a part
file.JsonSerializable
and related classes. These are moved to package:json_serializable
.lib/builder.dart
. Import through source_gen.dart
instead.OutputFormatter
typedef.Add LibraryReader.allElements
- a utility to iterate across all Element
instances contained in Dart library.
Add LibraryReader.element
to get back to the LibraryElement
instance.
Add ConstantReader.objectValue
to get back to the DartObject
instance.
Add ConstantReader.peek
to read a value that returns null
if not found:
// Tries to read the field "token" first, then "_token". findTokenField(DartObject o) { final reader = new ConstantReader(o); final token = o.peek('token') ?? o.read('_token'); }
throwOnUnresolved
optional parameter to TypeChecker.annotationsOf
, TypeChecker.annotationsOfExact
, TypeChecker.firstAnnotationOf
, and TypeChecker.firstAnnotationOfExact
. Setting this to false
will enable you to check for matching annotations with incomplete type information (at your own risk).AssetId
instead of the library
, which is more useful for tracking down the actual files.source_span
.spanForElement
; returns a SourceSpan
for an analyzer Element
.GeneratorBuilder
outputs a part file for a given input, but that input does not define part 'name.g.dart';
.TypeChecker#annotationsOf|firstAnnotationOf
now returns annotations that are assignable to the TypeChecker
‘s type. As a result we’ve added #annotationsOfExact|firstAnnotationOfExact
which has the old behavior for precise checks.TypeChecker#annotations...
-methods now throw a StateError
if one or more annotations on an element are not resolvable. This is usually a sign of a misspelling, missing import, or missing dependency.TypeChecker.any
, which delegates to multiple other TypeChecker
implementations when making a type check.analyzer
package to 0.29.10
.Update the minimum Dart SDK to 1.22.1
.
Deprecated builder.dart
: import source_gen.dart
instead.
Added TypeChecker
, a high-level API for performing static type checks:
import 'package:analyzer/dart/element/type.dart'; import 'package:source_gen/source_gen.dart'; void checkType(DartType dartType) { // Checks compared to runtime type `SomeClass`. print(const TypeChecker.forRuntime(SomeClass).isExactlyType(dartType)); // Checks compared to a known Url/Symbol: const TypeChecker.forUrl('package:foo/foo.dart#SomeClass'); // Checks compared to another resolved `DartType`: const TypeChecker.forStatic(anotherDartType); }
Failing to add a library
directive to a library that is being used as a generator target that generates partial files (part of
) is now an explicit error that gives a hint on how to name and fix your library:
> Could not find library identifier so a "part of" cannot be built. > > Consider adding the following to your source file: > > "library foo.bar;"
In Dart SDK >=1.25.0
this can be relaxed as part of
can refer to a path. To opt-in, GeneratorBuilder
now has a new flag, requireLibraryDirective
. Set it to false
, and also set your sdk
constraint appropriately:
sdk: '>=1.25.0 <2.0.0'
Added LibraryReader
, a utility class for LibraryElement
that exposes high-level APIs, including findType
, which traverses export
directives for publicly exported types. For example, to find Generator
from package:source_gen/source_gen.dart
:
void example(LibraryElement pkgSourceGen) { var library = new LibraryReader(pkgSourceGen); // Instead of pkgSourceGen.getType('Generator'), which is null. library.findType('Generator'); }
Added ConstantReader
, a high-level API for reading from constant (static) values from Dart source code (usually represented by DartObject
from the analyzer
package):
abstract class ConstantReader { factory ConstantReader(DartObject object) => ... // Other methods and properties also exist. /// Reads[ field] from the constant as another constant value. ConstantReader read(String field); /// Reads [field] from the constant as a boolean. /// /// If the resulting value is `null`, uses [defaultTo] if defined. bool readBool(String field, {bool defaultTo()}); /// Reads [field] from the constant as an int. /// /// If the resulting value is `null`, uses [defaultTo] if defined. int readInt(String field, {int defaultTo()}); /// Reads [field] from the constant as a string. /// /// If the resulting value is `null`, uses [defaultTo] if defined. String readString(String field, {String defaultTo()}); }
formatOutput
optional parameter to the GeneratorBuilder
constructor. This is a lambda of the form String formatOutput(String originalCode)
which allows you do do custom formatting.pkg/dart_style
.log
field instead of the deprecated buildStep.logger
dartfmt
fails.build
, build_runner
, and build_test
releases.pkg/build
.README.md
.package:analyzer
0.29.0computeNode()
while instantiating annotation valuesbuild
package.Remove an outdated work-around.
Make strong-mode clean.
pkg/build
.Breaking: Switch to the build
package for running Generator
s. This means that the top level build
and generate
functions are no longer available, and have been replaced by the top level build
, watch
, and serve
functions from the build
package, and the GeneratorBuilder
class. See tool/build.dart
, tool/watch.dart
, and tool/phases.dart
for usage.
build
package is experimental, and likely to change.Breaking: The build package provides an abstraction for reading/writing files via the BuildStep
class, and that is now also provided to Generator#generate
and GeneratorForAnnotation#generateForAnnotatedElement
as a second argument.
Timestamps are no longer included in generated code.
There is no longer a need to specify the files related to an individual generator via AssociatedFileSet
. Simply use the BuildStep
instance to read and write files and the build
package will track any files you read in and run incremental rebuilds as necessary.
Added support for Symbol
and Type
in annotations.
Improved error output when unable to create an instance from an annotation.
analyzer '^0.27.1'
and removed a work-around for a fixed analyzer
issue.analyzer '^0.27.0'
.JsonSerializableGenerator
now supports classes with read-only properties.JsonSerializable
: Added JsonKey
annotation.
Improved output of generation errors and stack traces.
Require analyzer '^0.26.2'
.
null
values for List
properties.JsonSerializable
: add support for List
values.README.md
to highlight the build_system
package and de-emphasize Dart Editor.Added omitGenerateTimestamp
and followLinks
named args to build
.
Added followLinks
to generate
.
Require Dart 1.12
.
Add implicit support for .packages
. If the file exists, it is used. If not, we fall back to using the packages
directory.
Support the latest releases of analyzer
and dart_style
packages.
fromJson
if it's defined in a child field.analyzer
and args
.README.md
.dart-lang
org on GitHub.BREAKING Returning a descriptive value from generate
.
BREAKING Fixed incorrectly named argument omitGenerateTimestamp
.
JsonSerializable
: Handle dynamic
and var
as field types.
associatedFileSet
to Generator
. Allows a generator to specify that changes to any file in a directory next to a Dart source file can initiate a generation run.Use async *
. Requires SDK >= 1.9.0-dev.10
Protect against crash during code format.
Added omitGenerateTimestamp
(incorrectly spelled) named argument to generate
method.
Generator.generate
is now called with the LibraryElement
, too.
Fixed critical bug affecting annotation matching. #35
Started using published dart_style
package.
README.md
with new examples.CHANGELOG.md
.JsonLiteral
generator.JsonGenerator
DateTime
.JsonGenerator
.README.md
updates.Generator.generate
is now async – returns Future<String>
README.md
.