sdk/docs/language/informal/implicit-creation.md

# Implicit Creation

Author: eernst@.

Version: 0.7 (2018-04-10)

Status: Background material, normative language now in dartLangSpec.tex.

**This document** is an informal specification of the *implicit creation*
feature. **The feature** adds support for omitting some occurrences of the
reserved words `new` and `const` in instance creation expressions.

This feature specification was written with a
[combined proposal](https://github.com/dart-lang/sdk/blob/master/docs/language/informal/optional-new-const.md)
as the starting point. That proposal presents optional new and optional const
together with several other features.


## Motivation

In Dart without implicit creation, the reserved word `new` is present in
almost all expressions whose evaluation invokes a constructor at run time,
and `const` is present in the corresponding constant expressions. These
expressions are known as *instance creation expressions*. If `new` or
`const` is removed from such an instance creation expression, the remaining
phrase is still syntactically correct in most cases. This feature
specification updates the grammar to make them all syntactically correct.

With that grammar update, all instance creation expressions can technically
omit `new` or `const` because tools (compilers, analyzers) are able to
parse these expressions.  The tools are able to recognize that these
expressions denote instance creations (rather than, say, static function
invocations), because the part before the arguments is statically known to
denote a constructor.

For instance, `p.C.foo` may resolve statically to a constructor named `foo` in
a class `C` imported with prefix `p`. Similarly, `D` may resolve to a class, in
which case `D(42)` is statically known to be a constructor invocation because
the other interpretation is statically known to be incorrect (that is, cf.
section '16.14.3 Unqualified Invocation' in the language specification,
evaluating `(D)(42)`: `(D)` is an instance of `Type` which is not a function
type and does not have a method named `call`, so we cannot call `(D)`).

In short, even without the keyword, we can still unambiguously recognize the
expressions that create objects. In that sense, the keywords are superfluous.

For human readers, however, it may be helpful to document that a particular
expression will yield a fresh instance, and this is the most common argument why
`new` should *not* be omitted: It can be good documentation. But Dart already
allows instance creation expressions to invoke a factory constructor, which is
not guaranteed to return a newly created object, so Dart developers never had
any firm local guarantees that any particular expression would yield a fresh
object. This means that it may very well be justified to have an explicit `new`,
but it will never be a rigorous guarantee of freshness.

Similarly, it may be important for developers to ensure that certain expressions
are constant, because of the improved performance and the guaranteed
canonicalization. This is a compelling argument in favor of making certain
instance creation expressions constant: It is simply a bug for that same
expression to have `new` because object identity is an observable
characteristic, and it may be crucial for performance that the expression is
constant.

In summary, both `new` and `const` may always be omitted from an instance
creation expression, but it is useful and reasonable to allow an explicit `new`,
and it is necessary to allow an explicit `const`. Based on that line of
reasoning, we've decided to make them optional. It will then be possible for
developers to make many expressions considerably more concise, and they can
still enforce the desired semantics as needed.

Obviously, this underscores the importance of the default: When a given
instance creation expression omits the keyword, should it be `const` or
`new`?

**As a general rule** `const` is used whenever it is required, and
otherwise `new` is used. This requirement arises from the syntactic
context, based on the fact that a non-constant expression would be a
compile-time error.

In summary, the implicit creation feature allows for concise construction
of objects, and it still allows developers to explicitly specify `new` or
`const`, whenever needed and whenever it is considered to be good
documentation.


## Syntax

The syntax changes associated with this feature are the following:

```
postfixExpression ::=
    assignableExpression postfixOperator |
    constructorInvocation selector* |  // NEW
    primary selector*
constructorInvocation ::=  // NEW
    typeName typeArguments '.' identifier arguments
assignableExpression ::=
    SUPER unconditionalAssignableSelector |
    constructorInvocation assignableSelectorPart+ |  // NEW
    identifier |
    primary assignableSelectorPart+
assignableSelectorPart ::=
    argumentPart* assignableSelector
```


## Static analysis

We specify a type directed source code transformation which eliminates the
feature by expressing the same semantics with different syntax. The static
analysis proceeds to work on the transformed program.

*This means that the feature is "static semantic sugar". We do not specify the
dynamic semantics for this feature, because the feature is eliminated in this
transformation step.*

We need to treat expressions differently in different locations, hence the
following definition: An expression _e_ is said to *occur in a constant
context*,

- if _e_ is an element of a constant list literal, or a key or value of
  an entry of a constant map literal.
- if _e_ is an actual argument of a constant object expression or of a
  metadata annotation.
- if _e_ is the initializing expression of a constant variable declaration.
- if _e_ is a switch case expression.
- if _e_ is an immediate subexpression of an expression _e1_ which occurs in
  a constant context, unless _e1_ is a `throw` expression or a function
  literal.

*This roughly means that everything which is inside a syntactically
constant expression or declaration is in a constant context. Note that a
`const` modifier which is introduced by the source code transformation does
not create a constant context, it is only the explicit occurrences of
`const` in the program that create a constant context. Also note that a
`throw` expression is currently not allowed in a constant expression, but
extensions affecting that status may be considered. A similar situation
arises for function literals.*

*A formal parameter may have a default value, which must be a constant
expression. We have chosen to not put such default values into a constant
context. They must be constant, and it may be necessary to add the keyword
`const` in order to make them so. This may seem inconvenient at times, but
the rationale is that it allows for future generalizations of default value
expressions allowing them to be non-constant. Still, there is no guarantee
that such features will be added to Dart.*

*For a class which contains a constant constructor and an instance variable
which is initialized by an expression _e_, it is a compile-time error if
_e_ is not constant. We have chosen to not put such initializers into a
constant context, and hence an explicit `const` may be required. This may
again seem inconvenient at times, but the rationale is that the reason for
the constancy requirement is non-local (the constant constructor
declaration may be many lines away from the instance variable declaration);
it may break programs in surprising and confusing ways if a constructor is
changed to be constant; and it may cause subtle bugs at run time due to the
change in identity, if such a change is made and it does not cause any
compile-time errors.*

We define *new/const insertion* as the following transformation, which will
be applied to specific parts of the program as specified below:

- if the expression _e_ occurs in a constant context, replace _e_ by
  `const` _e_,
- otherwise replace _e_ by `new` _e_.

*Note that new/const insertion is just a syntactic transformation, it is
specified below where to apply it, including which syntactic constructs may
play the role of _e_.*

*Also note that the outcome of new/const insertion may have static semantic
errors, e.g., actual arguments to a constructor invocation may have wrong
types because that's how the program was written, or a `const` list may
have elements which are not constant expressions. In such cases, tools like
analyzers and compilers should emit diagnostic messages that are meaningful
in relation to the original source of the program, which might mean that
the blame is assigned to a larger syntactic construct than the one that
directly has a compile-time error after the transformation.*

*We specify the transformation as based on a depth-first traversal of an
abstract syntax tree (AST). This means that the program is assumed to be
free of syntax errors, and when the current AST is, e.g., a
`postfixExpression`, the program as a whole has such a structure that the
current location was parsed as a `postfixExpression`. This is different
from the situation where we just require that a given subsequence of the
tokens of the program allows for such a parsing in isolation. For instance,
an identifier like `x` parses as an `assignableExpression` in isolation,
but if it occurs in the context `var x = 42;` or `var y = x;` then it will
not be parsed as an `assignableExpression`, it will be parsed as a plain
`identifier` which is part of a `declaredIdentifier` in the first case, and
as a `primary` which is a `postfixExpression`, which is a
`unaryExpression`, etc., in the second case. In short, we are transforming
the AST of the program as a whole, not isolated snippets of code.*

*In scientific literature, this kind of transformation is commonly
specified as an inductive transformation where `[[e1 e2]] = [[e1]] [[e2]]`
when the language supports a construct of the form `e1 e2`, etc. The reader
may prefer to view the transformation in that light, and we would then say
that we have omitted all the congruence rules.*

For the purposes of describing the transformation on assignable expressions
we need the following syntactic entity:

```
assignableExpressionTail ::=
    arguments assignableSelector assignableSelectorPart*
```

The transformation proceeds as follows, with three groups of situations
where a transformation is applied:

1.  With a `postfixExpression` _e_,

    - if _e_ is of the form `constructorInvocation selector*`, i.e.,
      `typeName typeArguments '.' identifier arguments selector*` then
      perform new/const insertion on the initial `constructorInvocation`.
    - if _e_ is of the form `typeIdentifier arguments` where
      `typeIdentifier` denotes a class then perform new/const insertion on
      _e_.
    - if _e_ is of the form `identifier1 '.' identifier2 arguments` where
      `identifier1` denotes a class and `identifier2` is the name of a
      named constructor in that class, or `identifier1` denotes a prefix
      for a library _L_ and `identifier2` denotes a class exported by _L_,
      perform new/const insertion on _e_.
    - if _e_ is of the form 
      `identifier1 '.' typeIdentifier '.' identifier2 arguments`
      where `identifier1` denotes a library prefix for a library _L_,
      `typeIdentifier` denotes a class _C_ exported by _L_, and
      `identifier2` is the name of a named constructor in _C_, perform
      new/const insertion on _e_.

2.  With an `assignableExpression` _e_,

    - if _e_ is of the form
      `constructorInvocation assignableSelectorPart+`
      then perform new/const insertion on the initial
      `constructorInvocation`.
    - if _e_ is of the form `typeIdentifier assignableExpressionTail` where
      `typeIdentifier` denotes a class then perform new/const insertion on
      the initial `typeIdentifier arguments`.
    - if _e_ is of the form
      `typeIdentifier '.' identifier assignableExpressionTail`
      where `typeIdentifier` denotes a class and `identifier` is the name
      of a named constructor in that class, or `typeIdentifier` denotes a
      prefix for a library _L_ and `identifier` denotes a class exported by
      _L_ then perform new/const insertion on the initial
      `typeIdentifier '.' identifier arguments`.
    - if _e_ is of the form
      `typeIdentifier1 '.' typeIdentifier2 '.' identifier
      assignableExpressionTail`
      where `typeIdentifier1` denotes a library prefix for a library _L_,
      `typeIdentifier2` denotes a class _C_ exported by _L_, and
      `identifier` is the name of a named constructor in _C_ then perform
      new/const insertion on the initial 
      `typeIdentifier1 '.' typeIdentifier2 '.' identifier arguments`.

3.  If _e_ is a literal list or a literal map which occurs in a constant
    context and does not have the modifier `const`, it is replaced by
    `const` _e_.

*In short, `const` is added implicitly in almost all situations where it is
required by the context, and in other situations `new` is added on instance
creations. It is easy to verify that each of the replacements can be
derived from `postfixExpression` via `primary selector*` and similarly for
`assignableExpression`. Hence, the transformation preserves syntactic
correctness.*


## Dynamic Semantics

There is no dynamic semantics to specify for this feature, because it is
eliminated by the code transformation.


## Revisions

- 0.7 (2018-04-10) Clarified the structure of the algorithm. Added
  commentary about cases where there is no constant context even though a
  constant expression is required, with a motivation for why it is so.

- 0.6 (2018-04-06) Removed "magic const" again, due to the risks
  associated with this feature (getting it specified and implemented
  robustly, in time).

- 0.5 (2018-01-04) Rewritten to use `const` whenever possible (aka "magic
  const") and adjusted to specify optional const as well as optional new
  together, because they are now very closely connected. This document was
  renamed to 'implicit-creation.md', and the document 'optional-const.md'
  was deleted.

- 0.4 (2017-10-17) Reverted to use 'immediate subexpression' again, for
  correctness. Adjusted terminology for consistency. Clarified the semantics
  of the transformation.

- 0.3 (2017-09-08) Included missing rule for transformation of composite
  literals (lists and maps). Eliminated the notion of an immediate
  subexpression, for improved precision.

- 0.2 (2017-07-30) Updated the document to specify the previously missing
  transformations for `assignableExpression`, and to specify a no-magic
  approach (where no `const` is introduced except when forced by the
  syntactic context).

- 0.1 (2017-08-15) Stand-alone informal specification for optional new created,
  using version 0.8 of the combined proposal
  [optional-new-const.md](https://github.com/dart-lang/sdk/blob/master/docs/language/informal/optional-new-const.md)
  as the starting point.