Document null-aware elements

[parlough]

Page to update

https://dart.dev/language/collections#operators

Notes

Feature specification: https://github.com/dart-lang/language/blob/main/accepted/future-releases/0323-null-aware-elements/feature-specification.md

[From @antfitch]
Do we have a conditional expression section? This is normally where I would look to find documentation for if and case expressions. To me, it looks like we are adding conditional expression that is a shortcut for an if expression? If this is true, is it a shortcut for any other types of expressions? Is null-aware an expression? I'm curious as to why we call this an element. @munificent can you provide guidance?

After a chat with @munificent, it looks like we should add documentation for this in https://dart.dev/language/collections. Right now we have an H2 called Operators, which where this should live, but we should also re-name this section to make it clear that Operators isn't a type of collection.

Suggested new right-pane TOC:

• Lists
• Sets
• Maps
• Supplemental support
  • Spread operator
  • Control-flow operator
  • Null-aware elements

References

Python conditional expressions:
https://docs.python.org/3/reference/expressions.html#conditional-expressions

[parlough]

@chloestefantsova Do you have any update on the state of null-aware elements? Is it in a good state to try with the null-aware-elements flag on the dev channels or is it a goal to have it enabled with a 3.8 language version?

Thanks for your hard work on the feature!

[chloestefantsova]

is it a goal to have it enabled with a 3.8 language version?

Yes, I'm working on it at https://dart-review.googlesource.com/c/sdk/+/412301.

[munificent]

Some more context in case it helps...

The language grammar is organized into a few different categories:

• Statements are the things that appear inside a function body or block. Most of the familiar control flow constructs are here: if, for, while, return, etc. Semantically, statements are executed to produce some side effect.

• Expressions are bits of code that evaluate to some value. 123, "a string", a + b, yes || no, await someFuture, and function(call) are all expressions.

This is mostly inherited from C, Java, etc. It gets a little more complex in Dart. We have a third category:

• Elements are the things that appear inside a list, set, or map literal. In most languages, these are just expressions. In Dart, you can use any expression as an element, but there are other elements that aren't expressions: ... ("spread"), if, for, and the upcoming null-aware element (?). So we needed to come up with a term and "element" seemed to do the job.

(There are other grammatical categories too for patterns, type annotations, top-level declarations, etc. But these are the main ones.)

The distinction between these categories matters because in some contexts only one is allowed. You can't do, for example:

print(return 123;); // Can't have a statement where an expression is expected.

var y = ...x; // Can't have an element where an expression is expected.

The line between these categories gets blurry because there is an expression statement (an expression followed by ;) that lets you put any expression where a statement is expected. And there is an expression element (just an expression) that lets you put any expression directly inside a collection literal.

To make things a little more confusing (for the documenters, users generally seem to figure it out OK), we reuse some of the syntax across those categories. So there is an if statement and an if element and they work pretty much the same. There is no if expression, just the old ?:, conditional expression instead.

The structure of the documentation doesn't super closely mirror the grammatical structure of the language. That's probably good because it means we can document general concepts like "control flow" in one place. But it does mean that the distinction between these categories might be obscured in ways that could be confusing for users.