-
Notifications
You must be signed in to change notification settings - Fork 715
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update keyword list #5681
Update keyword list #5681
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -0,0 +1,207 @@ | ||||||
- term: 'abstract' | ||||||
link: /language/class-modifiers#abstract | ||||||
type: bit | ||||||
- term: 'as' | ||||||
link: /language/operators#type-test-operators | ||||||
type: bit | ||||||
- term: 'assert' | ||||||
link: /language/error-handling#assert | ||||||
type: reserved | ||||||
- term: 'async' | ||||||
link: /language/async | ||||||
type: context | ||||||
- term: 'await' | ||||||
link: /language/async | ||||||
type: context | ||||||
- term: 'base' | ||||||
link: /language/class-modifiers#base | ||||||
type: bit | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
- term: 'break' | ||||||
link: /language/loops#break-and-continue | ||||||
type: reserved | ||||||
- term: 'case' | ||||||
link: /language/branches#switch | ||||||
type: reserved | ||||||
- term: 'catch' | ||||||
link: /language/error-handling#catch | ||||||
type: reserved | ||||||
- term: 'class' | ||||||
link: /language/classes#instance-variables | ||||||
type: reserved | ||||||
- term: 'const' | ||||||
link: /language/variables#final-and-const | ||||||
type: reserved | ||||||
- term: 'continue' | ||||||
link: /language/loops#break-and-continue | ||||||
type: reserved | ||||||
- term: 'covariant' | ||||||
link: /guides/language/sound-problems#the-covariant-keyword | ||||||
type: context | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
- term: 'default' | ||||||
link: /language/branches#switch | ||||||
type: reserved | ||||||
- term: 'deferred' | ||||||
link: /language/libraries#lazily-loading-a-library | ||||||
type: bit | ||||||
- term: 'do' | ||||||
link: /language/loops#while-and-do-while | ||||||
type: reserved | ||||||
- term: 'dynamic' | ||||||
link: /language#important-concepts | ||||||
type: reserved | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
- term: 'else' | ||||||
link: /language/branches#if | ||||||
type: reserved | ||||||
- term: 'enum' | ||||||
link: /language/enums | ||||||
type: reserved | ||||||
- term: 'export' | ||||||
link: /guides/libraries/create-packages | ||||||
type: bit | ||||||
- term: 'extends' | ||||||
link: /language/extend | ||||||
type: reserved | ||||||
- term: 'extension' | ||||||
link: /language/extension-methods | ||||||
type: bit | ||||||
- term: 'external' | ||||||
link: /language/functions#external | ||||||
type: bit | ||||||
- term: 'factory' | ||||||
link: /language/constructors#factory-constructors | ||||||
type: bit | ||||||
- term: 'false' | ||||||
link: /language/built-in-types#booleans | ||||||
type: reserved | ||||||
- term: 'final (var)' | ||||||
link: /language/variables#final-and-const | ||||||
type: reserved | ||||||
- term: 'final (class)' | ||||||
link: /language/class-modifiers#final | ||||||
type: bit | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
- term: 'finally' | ||||||
link: /language/error-handling#finally | ||||||
type: reserved | ||||||
- term: 'for' | ||||||
link: /language/loops#for-loops | ||||||
type: reserved | ||||||
- term: 'Function' | ||||||
link: /language/functions | ||||||
type: bit | ||||||
- term: 'get' | ||||||
link: /language/methods#getters-and-setters | ||||||
type: bit | ||||||
- term: 'hide' | ||||||
link: /language/libraries#importing-only-part-of-a-library | ||||||
type: reserved | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
- term: 'if' | ||||||
link: /language/branches#if | ||||||
type: reserved | ||||||
- term: 'implements' | ||||||
link: /language/classes#implicit-interfaces | ||||||
type: bit | ||||||
- term: 'import' | ||||||
link: /language/libraries#using-libraries | ||||||
type: bit | ||||||
- term: 'in' | ||||||
link: /language/loops#for-loops | ||||||
type: reserved | ||||||
- term: 'interface' | ||||||
link: /language/class-modifiers#interface | ||||||
type: bit | ||||||
- term: 'is' | ||||||
link: /language/operators#type-test-operators | ||||||
type: reserved | ||||||
- term: 'late' | ||||||
link: /language/variables#late-variables | ||||||
type: bit | ||||||
- term: 'library' | ||||||
link: /language/libraries | ||||||
type: bit | ||||||
- term: 'mixin' | ||||||
link: /language/mixins | ||||||
type: bit | ||||||
- term: 'new' | ||||||
link: /language/classes#using-constructors | ||||||
type: reserved | ||||||
- term: 'null' | ||||||
link: /language/variables#default-value | ||||||
type: reserved | ||||||
- term: 'of' | ||||||
link: /guides/libraries/create-packages#organizing-a-package | ||||||
type: context | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
- term: 'on' | ||||||
link: /language/error-handling#catch | ||||||
type: context | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
- term: 'operator' | ||||||
link: /language/methods#operators | ||||||
type: bit | ||||||
- term: 'part' | ||||||
link: /guides/libraries/create-packages#organizing-a-package | ||||||
type: bit | ||||||
- term: 'required' | ||||||
link: /language/functions#named-parameters | ||||||
type: bit | ||||||
- term: 'rethrow' | ||||||
link: /language/error-handling#catch | ||||||
type: reserved | ||||||
- term: 'return' | ||||||
link: /language/functions#return-values | ||||||
type: reserved | ||||||
- term: 'sealed' | ||||||
link: /language/class-modifiers#sealed | ||||||
type: bit | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
- term: 'set' | ||||||
link: /language/methods#getters-and-setters | ||||||
type: bit | ||||||
- term: 'show' | ||||||
link: /language/libraries#importing-only-part-of-a-library | ||||||
type: context | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
- term: 'static' | ||||||
link: /language/classes#class-variables-and-methods | ||||||
type: bit | ||||||
- term: 'super' | ||||||
link: /language/extend | ||||||
type: reserved | ||||||
- term: 'switch' | ||||||
link: /language/branches#switch | ||||||
type: reserved | ||||||
- term: 'sync' | ||||||
link: /language/functions#generators | ||||||
type: context | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
- term: 'this' | ||||||
link: /language/constructors | ||||||
type: reserved | ||||||
- term: 'throw' | ||||||
link: /language/error-handling#throw | ||||||
type: reserved | ||||||
- term: 'true' | ||||||
link: /language/built-in-types#booleans | ||||||
type: reserved | ||||||
- term: 'try' | ||||||
link: /language/error-handling#catch | ||||||
type: reserved | ||||||
- term: 'type' | ||||||
link: /language/extension-types | ||||||
type: reserved | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This one is really tricky. I couldn't convince the language team to make it a built-in identifier, so it isn't. But it is just like a built-in identifier in that it cannot be the name of "some" kinds of declarations, except that it is only forbidden for an
Suggested change
|
||||||
- term: 'typedef' | ||||||
link: /language/typedefs | ||||||
type: bit | ||||||
- term: 'var' | ||||||
link: /language/variables | ||||||
type: reserved | ||||||
- term: 'void' | ||||||
link: /language/built-in-types | ||||||
type: reserved | ||||||
- term: 'when' | ||||||
link: /language/branches#when | ||||||
type: reserved | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
- term: 'with' | ||||||
link: /language/mixins | ||||||
type: reserved | ||||||
- term: 'while' | ||||||
link: /language/loops#while-and-do-while | ||||||
type: reserved | ||||||
- term: 'yield' | ||||||
link: /language/functions#generators | ||||||
type: context |
Original file line number | Diff line number | Diff line change | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
@@ -10,123 +10,28 @@ nextpage: | |||||||||||||||
title: Built-in types | ||||||||||||||||
--- | ||||||||||||||||
|
||||||||||||||||
The following table lists the words that the Dart language treats specially. | ||||||||||||||||
|
||||||||||||||||
{% assign ckw = ' <sup title="contextual keyword" alt="contextual keyword">1</sup>' %} | ||||||||||||||||
{% assign bii = ' <sup title="built-in-identifier" alt="built-in-identifier">2</sup>' %} | ||||||||||||||||
{% assign lrw = ' <sup title="limited reserved word" alt="limited reserved word">3</sup>' %} | ||||||||||||||||
|
||||||||||||||||
<div class="table-wrapper"> | ||||||||||||||||
|
||||||||||||||||
||||| | ||||||||||||||||
|-|-|-|-| | ||||||||||||||||
| [abstract][]{{bii}} | [else][] | [import][]{{bii}} | [show][]{{ckw}} | | ||||||||||||||||
| [as][]{{bii}} | [enum][] | [in][] | [static][]{{bii}} | | ||||||||||||||||
| [assert][] | [export][]{{bii}} | [interface][]{{bii}} | [super][] | | ||||||||||||||||
| [async][]{{ckw}} | [extends][] | [is][] | [switch][] | | ||||||||||||||||
| [await][]{{lrw}} | [extension][]{{bii}} | [late][]{{bii}} | [sync][]{{ckw}} | | ||||||||||||||||
| [base][]{{bii}} | [external][]{{bii}} | [library][]{{bii}} | [this][] | | ||||||||||||||||
| [break][] | [factory][]{{bii}} | [mixin][]{{bii}} | [throw][] | | ||||||||||||||||
| [case][] | [false][] | [new][] | [true][] | | ||||||||||||||||
| [catch][] | [final (variable)][] | [null][] | [try][] | | ||||||||||||||||
| [class][] | [final (class)][]{{bii}} | [on][]{{ckw}} | [type][]{{lrw}} | | ||||||||||||||||
| [const][] | [finally][] | [operator][]{{bii}} | [typedef][]{{bii}} | | ||||||||||||||||
| [continue][] | [for][] | [part][]{{bii}} | [var][] | | ||||||||||||||||
| [covariant][]{{bii}} | [Function][]{{bii}} | [required][]{{bii}} | [void][] | | ||||||||||||||||
| [default][] | [get][]{{bii}} | [rethrow][] | [when][] | | ||||||||||||||||
| [deferred][]{{bii}} | [hide][]{{ckw}} | [return][] | [while][] | | ||||||||||||||||
| [do][] | [if][] | [sealed][]{{bii}} | [with][] | | ||||||||||||||||
| [dynamic][]{{bii}} | [implements][]{{bii}} | [set][]{{bii}} | [yield][]{{lrw}} | | ||||||||||||||||
|
||||||||||||||||
{:.table .table-striped .nowrap} | ||||||||||||||||
</div> | ||||||||||||||||
|
||||||||||||||||
[abstract]: /language/class-modifiers#abstract | ||||||||||||||||
[as]: /language/operators#type-test-operators | ||||||||||||||||
[assert]: /language/error-handling#assert | ||||||||||||||||
[async]: /language/async | ||||||||||||||||
[await]: /language/async | ||||||||||||||||
[base]: /language/class-modifiers#base | ||||||||||||||||
[break]: /language/loops#break-and-continue | ||||||||||||||||
[case]: /language/branches#switch | ||||||||||||||||
[catch]: /language/error-handling#catch | ||||||||||||||||
[class]: /language/classes#instance-variables | ||||||||||||||||
[const]: /language/variables#final-and-const | ||||||||||||||||
[continue]: /language/loops#break-and-continue | ||||||||||||||||
[covariant]: /guides/language/sound-problems#the-covariant-keyword | ||||||||||||||||
[default]: /language/branches#switch | ||||||||||||||||
[deferred]: /language/libraries#lazily-loading-a-library | ||||||||||||||||
[do]: /language/loops#while-and-do-while | ||||||||||||||||
[dynamic]: /language#important-concepts | ||||||||||||||||
[else]: /language/branches#if | ||||||||||||||||
[enum]: /language/enums | ||||||||||||||||
[export]: /guides/libraries/create-packages | ||||||||||||||||
[extends]: /language/extend | ||||||||||||||||
[extension]: /language/extension-methods | ||||||||||||||||
[external]: /language/functions#external | ||||||||||||||||
[factory]: /language/constructors#factory-constructors | ||||||||||||||||
[false]: /language/built-in-types#booleans | ||||||||||||||||
[final (variable)]: /language/variables#final-and-const | ||||||||||||||||
[final (class)]: /language/class-modifiers#final | ||||||||||||||||
[finally]: /language/error-handling#finally | ||||||||||||||||
[for]: /language/loops#for-loops | ||||||||||||||||
[Function]: /language/functions | ||||||||||||||||
[get]: /language/methods#getters-and-setters | ||||||||||||||||
[hide]: /language/libraries#importing-only-part-of-a-library | ||||||||||||||||
[if]: /language/branches#if | ||||||||||||||||
[implements]: /language/classes#implicit-interfaces | ||||||||||||||||
[import]: /language/libraries#using-libraries | ||||||||||||||||
[in]: /language/loops#for-loops | ||||||||||||||||
[interface]: /language/class-modifiers#interface | ||||||||||||||||
[is]: /language/operators#type-test-operators | ||||||||||||||||
[late]: /language/variables#late-variables | ||||||||||||||||
[library]: /language/libraries | ||||||||||||||||
[mixin]: /language/mixins | ||||||||||||||||
[new]: /language/classes#using-constructors | ||||||||||||||||
[null]: /language/variables#default-value | ||||||||||||||||
[on]: /language/error-handling#catch | ||||||||||||||||
[operator]: /language/methods#operators | ||||||||||||||||
[part]: /guides/libraries/create-packages#organizing-a-package | ||||||||||||||||
[required]: /language/functions#named-parameters | ||||||||||||||||
[rethrow]: /language/error-handling#catch | ||||||||||||||||
[return]: /language/functions#return-values | ||||||||||||||||
[sealed]: /language/class-modifiers#sealed | ||||||||||||||||
[set]: /language/methods#getters-and-setters | ||||||||||||||||
[show]: /language/libraries#importing-only-part-of-a-library | ||||||||||||||||
[static]: /language/classes#class-variables-and-methods | ||||||||||||||||
[super]: /language/extend | ||||||||||||||||
[switch]: /language/branches#switch | ||||||||||||||||
[sync]: /language/functions#generators | ||||||||||||||||
[this]: /language/constructors | ||||||||||||||||
[throw]: /language/error-handling#throw | ||||||||||||||||
[true]: /language/built-in-types#booleans | ||||||||||||||||
[try]: /language/error-handling#catch | ||||||||||||||||
[type]: /language/extension-types | ||||||||||||||||
[typedef]: /language/typedefs | ||||||||||||||||
[var]: /language/variables | ||||||||||||||||
[void]: /language/built-in-types | ||||||||||||||||
[when]: /language/branches#when | ||||||||||||||||
[with]: /language/mixins | ||||||||||||||||
[while]: /language/loops#while-and-do-while | ||||||||||||||||
[yield]: /language/functions#generators | ||||||||||||||||
|
||||||||||||||||
Avoid using these words as identifiers. | ||||||||||||||||
However, if necessary, the keywords marked with superscripts can be identifiers: | ||||||||||||||||
|
||||||||||||||||
* Words with the superscript **1** are **contextual keywords**, | ||||||||||||||||
which have meaning only in specific places. | ||||||||||||||||
They're valid identifiers everywhere. | ||||||||||||||||
|
||||||||||||||||
* Words with the superscript **2** are **built-in identifiers**. | ||||||||||||||||
These keywords are valid identifiers in most places, | ||||||||||||||||
but they can't be used as class or type names, or as import prefixes. | ||||||||||||||||
|
||||||||||||||||
* Words with the superscript **3** are limited reserved words related to | ||||||||||||||||
[asynchrony support][]. | ||||||||||||||||
You can't use `await` or `yield` as an identifier | ||||||||||||||||
in any function body marked with `async`, `async*`, or `sync*`. | ||||||||||||||||
|
||||||||||||||||
All other words in the table are **reserved words**, | ||||||||||||||||
which can't be identifiers. | ||||||||||||||||
|
||||||||||||||||
[asynchrony support]: /language/async | ||||||||||||||||
{% assign ckw = ' <sup>1</sup>' %} | ||||||||||||||||
{% assign bii = ' <sup>2</sup>' %} | ||||||||||||||||
|
||||||||||||||||
The following table lists the words | ||||||||||||||||
that the Dart language reserves for its own use. | ||||||||||||||||
Don't use these terms as identifiers unless the term notes an exception. | ||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think some form of the original guidance is appropriate here. It's almost never good style to use any of these as identifiers. So maybe say something like "These words cannot be used as identifiers unless otherwise noted. Even when allowed, using keywords as identifiers is confusing and should be avoided."? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't see a reason to discourage the user of, fx, The thing users need to know are the actual restrictions: reserved words that cannot be used as a name, ever, and built-in identifiers that cannot be used as a type or prefix name. The rest are not really important. If this is a list of every word that occurs as a "keyword" (managing: not as a resolvable name) anywhere in the grammar, then those words should be included, and linked to the descriptions of the constructs where the word can occur. That index can also double as the list of restrictions, saying which words are restricted words and built-in identifiers, wish it's useful information. It can even mention that |
||||||||||||||||
To learn more about identifier usage, click on the term. | ||||||||||||||||
|
||||||||||||||||
<table class="table table-striped"> | ||||||||||||||||
|
||||||||||||||||
{% tablerow keyword in keywords cols: 4 %} | ||||||||||||||||
<a href="{{keyword.link}}">{{keyword.term}}</a> | ||||||||||||||||
{%- case keyword.type %} | ||||||||||||||||
{% when 'bit' %}{{bii}} | ||||||||||||||||
{% when 'context' %}{{ckw}} | ||||||||||||||||
{% endcase %} | ||||||||||||||||
{% endtablerow %} | ||||||||||||||||
</table> | ||||||||||||||||
|
||||||||||||||||
{{ckw}} These keywords can be used as an identifier | ||||||||||||||||
depending on **context**. | ||||||||||||||||
Comment on lines
+32
to
+33
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Using a singlar form for consistency with lines 35-37:
Suggested change
Also, 'these keywords' can be used as 'an identifier' isn't quite congruent. |
||||||||||||||||
|
||||||||||||||||
{{bii}} These keywords can't be used as class names, type names, | ||||||||||||||||
or import prefixes. They can be used as identifiers in all other | ||||||||||||||||
circumstances. | ||||||||||||||||
Comment on lines
+35
to
+37
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 'Class names' is a subset of 'type names', and we may also want to mention a few other kinds of type names. Perhaps:
Suggested change
I'm using a singular form because it makes everything in this paragraph a bit more straightforward and unambiguous, and also because a reader would often arrive at this paragraph because they want to know more about one specific identifier that they were looking at. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
async
is one of those identifiers that occur verbatim in a grammar rule, but there are no restrictions on the use of this identifier (it can be the name of a variable, a type, an import prefix, anything).We need a separate category for these identifiers. I'll use
nothing
as a strawman here, because there's nothing special about these words. They will be recognized as being a structural part of certain syntactic forms, not just as the name of a declared entity (like other identifiers).I'm using the same
type
in several cases below, for the same reason.