code_builder

• Convert imports of implementation libraries under package:fixnum/src/* into imports of package:fixnum/fixnum.dart to prevent issues when version 1.2.0 is released with platform-specific implementation libraries that generated code should not import directly. This is a temporary workaround, it will be replaced by a new way of managing imports in a future major version release.

• Export SpecVisitor, ClosureExpression, LiteralMapExpression LiteralRecordExpression, LiteralSetExpression types.
• Support Expression.newInstanceNamed with empty name
• Consistently add blank lines between => in class-like definitions.
• Fixed bug: Fields declared with static and external now produce code with correct order
• Require built_collection: ^5.1.1
• Require built_value: ^8.10.1
• Require collection: ^1.19.0
• Require matcher: ^0.12.16+1
• Require meta: ^1.16.0
• Require sdk: ^3.7.0

• Require Dart ^3.5.0
• Upgrade to dart_style 2.3.7.
• Move to dart-lang/tools monorepo.

• Add Library.docs to support emitting doc comments on libraries.
• Export RepresentationDeclaration and RepresentationDeclarationBuilder so they can be used when generating extension types.
• Upgrade to dart_style 2.3.4.

• Add Library.generatedByComment to support emitting 'generated by' comments.
• Support emitting an unnamed library with annotations.

• Add Expression.operatorSubtract
• Deprecate Expression.operatorSubstract
• Add Expression.operatorIntDivide
• Add Expression.operatorUnaryPrefixIncrement
• Add Expression.operatorUnaryPostfixIncrement
• Add Expression.operatorUnaryMinus
• Add Expression.operatorUnaryPrefixDecrement
• Add Expression.operatorUnaryPostfixDecrement
• Add Expression.operatorBitwiseAnd
• Add Expression.operatorBitwiseOr
• Add Expression.operatorBitwiseXor
• Add Expression.operatorUnaryBitwiseComplement
• Add Expression.operatorShiftLeft
• Add Expression.operatorShiftRight
• Add Expression.operatorShiftRightUnsigned
• Add Expression.addAssign
• Add Expression.subtractAssign
• Add Expression.multiplyAssign
• Add Expression.divideAssign
• Add Expression.intDivideAssign
• Add Expression.euclideanModuloAssign
• Add Expression.shiftLeftAssign
• Add Expression.shiftRightAssign
• Add Expression.shiftRightUnsignedAssign
• Add Expression.bitwiseAndAssign
• Add Expression.bitwiseXorAssign
• Add Expression.bitwiseOrAssign
• Allow passing an Expression through literal without an exception.
• Add support for extension types.
• Update SDK version constraints to >=3.0.0.

• Add a newline after lambdas.

• Add support for named arguments in enum classes
• Add support for external keyword on fields.
• Add Expression.parenthesized to manually wrap an expression in parenthesis.

• Require Dart 2.19
• Add support for emitting type parameters for typedefs.
• Add support for class modifiers.
• Add support for records (both types and record literals).
• Add literalSpread and literalNullSafeSpread to support adding spreads to literalMap.

void main() {
  // Creates a map
  // {
  //   ...one,
  //   2: two,
  //   ...?three,
  // }
  final map = literalMap({
    literalSpread(): refer('one'),
    2: refer('two'),
    literalNullSafeSpread(): refer('three'),
  });
}

• Mention how the allocator argument relates to imports in the DartEmitter constructor doc.
• Add support for emitting typedefs.
• Add support for emitting leading line comments for libraries.
• Add support for emitting ignore_for_file analyzer directive comments.

• Add support for adding more implementation in enum classes.
• Only emit late keyword when using null safety syntax.
• Use implicit const when assigning to a declareConst variable.
• Deprecate assignVar, assignConst, and assignFinal.
• Add trailing commas to any parameter list, argument list, or collection literal which has more than one element.

• Add an ignore for a lint from the package:lints recommended set. The lint, no_leading_underscores_for_library_prefixes is most useful for hand edited code where the appearance of a private name that is already not visible outside the library is confusing.
• Fix the docs for Expression.assign, ifNullThen, and assignNullAware which had the argument and receiver flipped.
• Add declareConst, declareFinal, and declareVar to replace Expression.assignConst, assignFinal, and assignVar. Add support for late variables with the declare* utilities.
• Add ParameterBuilder.toSuper so support super formal parameters language feature.

• Add Expression.spread for the spread operator ....
• Add support 'late' field modifier.
• Add support for Expression.nullChecked to add a null assertion operator.
• Add support for creating mixins.
• Add Expression.nullSafeSpread for the null aware spread operator ...?.
• A Library can now be annotated.

• Migrate to null safety.
• Changed the DartEmitter constructor to use named optional parameters.
• Add ParenthesizedExpression and ExpressionVisitor.visitParenthesizedExpression.

• Add support for converting a Method to a generic closure, with Method.genericClosure.

• Add support for creating extension methods.
• Expand constraint on built_value to allow null safe migrated version.

• Add support for defining enums.
• Fix keyword ordering for const factory constructors.

• Fix confusing mismatch description from equalsDart. https://github.com/dart-lang/code_builder/issues/293

• Introduce Expression.thrown for throwing an expression.
• Introduce FunctionType.isNullable.
• Update SDK requirement to >=2.7.0 <3.0.0.

• Add ?? null-aware operator.
• Add .. cascade assignment operator.
• Add part directive.
• Introduce TypeReference.isNullable.
• Add an option in DartEmitter to emit nullable types with trailing ? characters.

• Escape newlines in String literals.
• Introduce Expression.or for boolean OR.
• Introduce Expression.negate for boolean NOT.
• No longer emits redundant ,s in FunctionTypes.
• Added support for literalSet and literalConstSet.
• Depend on the latest package:built_value.

• Emit = instead of : for named parameter default values.
• The new keyword will not be used in generated code.
• The const keyword will be omitted when it can be inferred.
• Add an option in DartEmitter to order directives.
• DartEmitter added a startConstCode function to track the creation of constant expression trees.
• BinaryExpression added the final bool isConst field.

• Bump dependency on built_collection to include v4.0.0.

• Set max SDK version to <3.0.0.

• Expression.asA is now wrapped with parenthesis so that further calls may be made on it as an expression.

• Added Expression.asA for creating explicit casts:

void main() {
  test('should emit an explicit cast', () {
    expect(
      refer('foo').asA(refer('String')),
      equalsDart('foo as String'),
    );
  });
}

• Fix a bug that caused all downstream users of code_builder to crash due to build_runner trying to import our private builder (in tool/). Sorry for the inconvenience.

• Require source_gen: ^0.7.5.

• Upgrade to built_value 5.1.0.
• Export the literalNum function.
• BUG FIX: literal supports a Map.

• Adds discovery API to find both a configuration and its location:
  findPackageConfigAndFile and findPackageConfigAndUri.
• Removes support for the .packages file.
  The Dart SDK no longer supports that file, and no new .packages files
  will be generated.
  Since the SDK requirement for this package is above 3.0.0,
  no supporting SDK can use or generate .packages.
• Simplifies API that no longer needs to support two separate files.
  • Renamed readAnyConfigFile to readConfigFile, and removed
    the preferNewest parameter.
  • Same for readAnyConfigFileUri which becomes readConfigFileUri.
  • Old functions still exists as deprecated, forwarding to the new
    functions without the preferNewest argument.
    Makes PackageConfig, Package and LanguageVersion @sealed classes,
    in preparation for making them final in a future update.
• Adds PackageConfig.minVersion to complement .maxVersion.
  Currently both are 2.

• Also infer Constructor.lambda for factory constructors.

• Using equalsDart no longer formats automatically with dartfmt.

• Removed deprecated Annotation and File classes.

• Method.lambda is inferred based on Method.body where possible and now defaults to null.

• Add equalTo, notEqualTo, greaterThan, lessThan, greaterOrEqualTo, and lessOrEqualTo to Expression.

• Using equalsDart and expecting dartfmt by default is deprecated. This requires this package to have a direct dependency on specific versions of dart_style (and transitively analyzer), which is problematic just for testing infrastructure. To future proof, we've exposed the EqualsDart class with a format override:

// Copyright (c) 2017, 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.

import 'package:code_builder/code_builder.dart';
import 'package:dart_style/dart_style.dart';

final DartFormatter _dartfmt = new DartFormatter();
String _format(String source) {
  try {
    return _dartfmt.format(source);
  } on FormatException catch (_) {
    return _dartfmt.formatStatement(source);
  }
}

/// Should be invoked in `main()` of every test in `test/**_test.dart`.
void useDartfmt() => EqualsDart.format = _format;

• Added Expression.isA and Expression.isNotA:

void main() {
  test('should emit an is check', () {
    expect(
      refer('foo').isA(refer('String')),
      equalsDart('foo is String'),
    );
  });
}

• Deprecated Annotation. It is now legal to simply pass any Expression as a metadata annotation to Class, Method, Field, and Parameter. In 3.0.0, the Annotation class will be completely removed:

void main() {
  test('should create a class with a annotated constructor', () {
    expect(
      new Class((b) => b
        ..name = 'Foo'
        ..constructors.add(
          new Constructor((b) => b..annotations.add(refer('deprecated'))))),
      equalsDart(r'''
        class Foo {
          @deprecated
          Foo();
        }
      '''),
    );
  });
}

• Added inference support for Method.lambda and Constructor.lambda. If not explicitly provided and the body of the function originated from an Expression then lambda is inferred to be true. This is not a breaking change yet, as it requires an explicit null value. In 3.0.0 this will be the default:

void main() {
  final animal = new Class((b) => b
    ..name = 'Animal'
    ..extend = refer('Organism')
    ..methods.add(new Method.returnsVoid((b) => b
      ..name = 'eat'
      // In 3.0.0, this may be omitted and still is inferred.
      ..lambda = null
      ..body = refer('print').call([literalString('Yum!')]).code)));
  final emitter = new DartEmitter();
  print(new DartFormatter().format('${animal.accept(emitter)}'));
}

• Added nullSafeProperty to Expression to access properties with ?.
• Added conditional to Expression to use the ternary operator ? :
• Methods taking positionalArguments accept Iterable<Expression>
• BUG FIX: Parameters can take a FunctionType as a type. Reference.type now returns a Reference. Note that this change is technically breaking but should not impacts most clients.

• Imports are prefixed with _i1 rather than _1 which satisfies the lint lowercase_with_underscores. While not a strictly breaking change you may have to fix/regenerate golden file-like tests. We added documentation that the specific prefix is not considered stable.

• Added Expression.index for accessing the [] operator:

void main() {
  test('should emit an index operator', () {
    expect(
      refer('bar').index(literalTrue).assignVar('foo').statement,
      equalsDart('var foo = bar[true];'),
    );
  });

  test('should emit an index operator set', () {
    expect(
      refer('bar')
        .index(literalTrue)
        .assign(literalFalse)
        .assignVar('foo')
        .statement,
      equalsDart('var foo = bar[true] = false;'),
    );
  });
}

• literalList accepts an Iterable argument.

• Fixed an NPE when a method had a return type of a FunctionType:

void main() {
  test('should create a method with a function type return type', () {
    expect(
      new Method((b) => b
        ..name = 'foo'
        ..returns = new FunctionType((b) => b
          ..returnType = refer('String')
          ..requiredParameters.addAll([
            refer('int'),
          ]))),
      equalsDart(r'''
        String Function(int) foo();
      '''),
    );
  });
}

We now require the Dart 2.0-dev branch SDK (>= 2.0.0-dev).

• Added support for raw String literals.
• Automatically escapes single quotes in now-raw String literals.
• Deprecated File, which is now a redirect to the preferred class, Library.

This helps avoid symbol clashes when used with dart:io, a popular library. It is now safe to do the following and get full access to the code_builder API:

import 'dart:io';

import 'package:code_builder/code_builder.dart' hide File;

We will remove File in 3.0.0, so use Library instead.

Re-released without a direct dependency on package:analyzer!

For users of the 1.x branch of code_builder, this is a pretty big breaking change but ultimately is for the better - it's easier to evolve this library now and even add your own builders on top of the library.

// Copyright (c) 2017, 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.

import 'package:code_builder/code_builder.dart';
import 'package:dart_style/dart_style.dart';

void main() {
  final animal = new Class((b) => b
    ..name = 'Animal'
    ..extend = refer('Organism')
    ..methods.add(new Method.returnsVoid((b) => b
      ..name = 'eat'
      ..lambda = true
      ..body = const Code('print(\'Yum\')'))));
  final emitter = new DartEmitter();
  print(new DartFormatter().format('${animal.accept(emitter)}'));
}

...outputs...

class Animal extends Organism {
  void eat() => print('Yum!');
}

Major changes:

• Builders now use built_value, and have a more consistent, friendly API.
• Builders are now consistent - they don't perform work work until code is emitted.
• It's possible to overwrite the built-in code emitting, formatting, etc by providing your own visitors. See DartEmitter as an example of the built-in visitor/emitter.
• Most of the expression and statement-level helpers were removed; in practice, they were difficult to write and maintain, and many users commonly asked for opt-out type APIs. See the Code example below:

void main() {
  var code = new Code('x + y = z');
  code.expression;
  code.statement;
}

See the commit log, examples, and tests for full details. While we want to try and avoid breaking changes, suggestions, new features, and incremental updates are welcome!

• Added lazySpec and lazyCode to lazily create code on visit #145.

• BUG FIX: equalsDart emits the failing source code #147.

• BUG FIX: Top-level lambda Methods no longer emit invalid code #146.

• Complete re-write to not use package:analyzer.
• Code generation now properly uses the builder pattern (via built_value).
• See examples and tests for details.

• Removed Reference.localScope. Just use Reference(symbol) now.
• Allow Reference instead of an explicit TypeReference in most APIs.
  • toType() is performed for you as part the emitter process

final animal = new Class((b) => b
  ..name = 'Animal'
  // Used to need a suffix of .toType().
  ..extend = const Reference('Organism')
  ..methods.add(new Method.returnsVoid((b) => b
    ..name = 'eat'
    ..lambda = true
    ..body = new Code((b) => b..code = 'print(\'Yum\')'))));

• We now support the Dart 2.0 pre-release SDKs (<2.0.0-dev.infinity)
• Removed the ability to treat Class as a TypeReference.
  • Was required for compilation to dart2js, which is now tested on travis.

• Upgraded build_runner from ^0.3.0 to >=0.4.0 <0.6.0.

• Upgraded build_value{_generator} from ^1.0.0 to >=2.0.0 <5.0.0.

• Upgraded source_gen from >=0.5.0 <0.7.0 to ^0.7.0.

• Added MethodModifier to allow emit a Method with async|async*|sync*.

• Added show|hide to Directive.

• Added Directive.importDeferredAs.

• Added a new line character after emitting some types (class, method, etc).

• Added refer as a short-hand for new Reference(...).

  • Reference now implements Expression.

• Added many classes/methods for writing bodies of Code fluently:

  • Expression
  • LiteralExpression
    • literal
    • literalNull
    • literalBool
    • literalTrue
    • literalFalse
    • literalNum
    • literalString
    • literalList and literalConstList
    • literalMap and literalConstMap
  • const Code(staticString)
  • const Code.scope((allocate) => '')

• Removed SimpleSpecVisitor (it was unused).

• Removed implements Reference from Method and Field; not a lot of value.

• SpecVisitor<T>'s methods all have an optional [T context] parameter now.

  • This makes it much easier to avoid allocating extra StringBuffers.

• equalsDart removes insignificant white space before comparing results.

• Added Expression.annotation and Expression.annotationNamed.

• Added Method.closure to create an Expression.

• Added FunctionType.

• Added {new|const}InstanceNamed to Expression #135.

  • Also added a typeArguments option to all invocations.

• Added assign{...} variants to Expression #137.

• Added .awaited and .returned to Expression #138.

• BUG FIX: Block now implements Code #136.

• BUG FIX: new DartEmitter.scoped() applies prefixing #139.

• Renamed many of the .asFoo(...) and .toFoo(...) methods to single getter:

  • asCode() to code
  • asStatement() to statement
  • toExpression() to expression

• Moved {new|const}Instance{[Named]} from Expression to Reference.

• Added isInstanceOf to ExpressionBuilder, which performs an is check:

expect(
  reference('foo').isInstanceOf(_barType),
  equalsSource('foo is Bar'),
);

• Support latest pkg/analyzer and pkg/func.

• Update internals to use newer analyzer API

• Support the latest version of package:dart_style.

First full release. At this point, all changes until 2.0.0 will be backward compatible (new features) or bug fixes that are not breaking. This doesn't mean that the entire Dart language is buildable with our API, though.

Contributions are welcome.

• Exposed uri in ImportBuilder, ExportBuilder, and Part[Of]Builder.

• Add support for async, sync, sync* functions
• Add support for expression asAwait, asYield, asYieldStar
• Add toExportBuilder and toImportBuilder to types and references
• Fix an import scoping bug in return statements and named constructor invocations.
• Added constructor initializer support
• Add while and do {} while loop support
• Add for and for-in support
• Added a name getter for ParameterBuilder

• Add support for switch statements
• Add support for a raw expression and statement
  • new ExpressionBuilder.raw(...)
  • new StatementBuilder.raw(...)

This should help cover any cases not covered with builders today.

• Allow referring to a ClassBuilder and TypeBuilder as an expression
• Add support for accessing the index [] operator on an expression

BREAKING CHANGES

• Changed ExpressionBuilder.asAssign to always take an ExpressionBuilder as target and removed the value property. Most changes are pretty simple, and involve just using reference(...). For example:

literal(true).asAssign(reference('flag'))

... emits flag = true.

• Added support for genericTypes parameter for ExpressionBuilder#invoke:

expect(
  explicitThis.invoke('doThing', [literal(true)], genericTypes: [
    lib$core.bool,
  ]),
  equalsSource(r'''
    this.doThing<bool>(true)
  '''),
);

• Added a castAs method to ExpressionBuilder:

expect(
  literal(1.0).castAs(lib$core.num),
  equalsSource(r'''
    1.0 as num
  '''),
);

BREAKING CHANGES

• Removed namedNewInstance and namedConstInstance, replaced with constructor::

expect(
  reference('Foo').newInstance([], constructor: 'other'),
  equalsSource(r'''
    new Foo.other()
  '''),
);

• Renamed named parameter to namedArguments:

expect(
  reference('doThing').call(
    [literal(true)],
    namedArguments: {
      'otherFlag': literal(false),
    },
  ),
  equalsSource(r'''
    doThing(true, otherFlag: false)
  '''),
);

• Renamed PartBuilder to PartOfBuilder.
• Added a new class, PartBuilder, to represent part '...dart' directives.
• Added the HasAnnotations interface to all library/part/directive builders.
• Added asFactory and asConst to ConstructorBuilder.
• Added ConstructorBuilder.redirectTo for a redirecting factory constructor.
• Added a name getter to ReferenceBuilder.
• Supplying an empty constructor name ('') is equivalent to null (default).
• Automatically encodes string literals with multiple lines as '''.
• Added asThrow to ExpressionBuilder.
• Fixed a bug that prevented FieldBuilder from being used at the top-level.

• Re-published the package without merge conflicts.

• Added TypeDefBuilder.
• Added FunctionParameterBuilder.
• Added asAbstract to various MethodBuilder constructors.

• Added ExpressionBuilder#ternary.

• Large refactor that makes the library more feature complete.

• Added returnVoid to well, return;
• Added support for top-level field assignments:

new LibraryBuilder()..addMember(literal(false).asConst('foo'))

• Added support for specifying a target when using asAssign:

// Outputs bank.bar = goldBar
reference('goldBar').asAssign('bar', target: reference('bank'))

• Added support for the cascade operator:

// Outputs foo..doThis()..doThat()
reference('foo').cascade((c) => <ExpressionBuilder> [
  c.invoke('doThis', []),
  c.invoke('doThat', []),
]);

• Added support for accessing a property

// foo.bar
reference('foo').property('bar');

• Add support for the latest pkg/analyzer.

• MethodBuilder with no statements will create an empty block instead of a semicolon.

// main() {}
method('main')

• Fix lambdas and closures to not include a trailing semicolon when used as an expression.

 // () => false
 new MethodBuilder.closure(returns: literal(false));

• MethodBuilder.closure emits properly as a top-level function

• Make use of the new analyzer APIs in preparation for analyzer version 0.30.