Skip to content

Commit f23b9dc

Browse files
bracevacbracevac
committed
Grammar documentation
1 parent cebba7c commit f23b9dc

File tree

2 files changed

+41
-18
lines changed

2 files changed

+41
-18
lines changed

‎compiler/src/dotty/tools/dotc/parsing/Parsers.scala‎

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -220,18 +220,19 @@ object Parsers {
220220
def isErased = isIdent(nme.erased) && in.erasedEnabled
221221
// Are we seeing an `erased` soft keyword that will not be an identifier?
222222
def isErasedKw = isErased && in.isSoftModifierInParamModifierPosition
223-
// Are we seeing a `cap` soft keyword for declaring a capture-set member or at the beginning a capture-variable parameter list?
223+
// Are we seeing a `cap` soft keyword for declaring a capture-set member or a capture-variable parameter?
224224
def isCapKw = Feature.ccEnabled && isIdent(nme.cap)
225-
// 'cap type' ?
225+
// Are we seeing 'cap type' ?
226226
def isCapTypeKw = isCapKw && in.lookahead.token == TYPE
227-
// Are the next two tokens 'cap type'?
227+
// Are the next two tokens after the current 'cap type'?
228228
def isCapTypeKwNext = {
229229
if Feature.ccEnabled then
230230
val lookahead = in.LookaheadScanner()
231231
lookahead.nextToken()
232232
lookahead.isIdent(nme.cap) && lookahead.lookahead.token == TYPE
233233
else false
234234
}
235+
// Are we seeing a named cap parameter assignment? `'cap' id '='` (under namedTypeArguments)
235236
def isCapAssignmentNext = {
236237
if isCapKw then
237238
val lookahead = in.LookaheadScanner()
@@ -1620,8 +1621,8 @@ object Parsers {
16201621
case _ => None
16211622
}
16221623

1623-
/** CaptureRef ::= { SimpleRef `.` } SimpleRef [`*`] [`.` rd] -- under captureChecking
1624-
* | [ { SimpleRef `.` } SimpleRef `.` ] id
1624+
/** CaptureRef ::= { SimpleRef ‘.’ } SimpleRef [‘*’] [‘.’ ‘rd’] -- under captureChecking
1625+
* | [ { SimpleRef ‘.’ } SimpleRef ‘.’ ] id
16251626
*/
16261627
def captureRef(): Tree =
16271628

@@ -1645,7 +1646,7 @@ object Parsers {
16451646
recur(simpleRef())
16461647
end captureRef
16471648

1648-
/** CaptureSet ::= `{` CaptureRef {`,` CaptureRef} `}` -- under captureChecking
1649+
/** CaptureSet ::= ‘{’ CaptureRef {‘,’ CaptureRef} ‘}’ -- under captureChecking
16491650
*/
16501651
def captureSet(): List[Tree] = inBraces {
16511652
if in.token == RBRACE then Nil else commaSeparated(captureRef)
@@ -1663,9 +1664,9 @@ object Parsers {
16631664
* | InfixType
16641665
* FunType ::= (MonoFunType | PolyFunType)
16651666
* MonoFunType ::= FunTypeArgs (‘=>’ | ‘?=>’) Type
1666-
* | (‘->’ | ‘?->’ ) [CaptureSet] Type -- under pureFunctions
1667+
* | (‘->’ | ‘?->’ ) [CaptureSet] Type -- under pureFunctions and captureChecking
16671668
* PolyFunType ::= TypTypeParamClause '=>' Type
1668-
* | TypTypeParamClause ‘->’ [CaptureSet] Type -- under pureFunctions
1669+
* | TypTypeParamClause ‘->’ [CaptureSet] Type -- under pureFunctions and captureChecking
16691670
* FunTypeArgs ::= InfixType
16701671
* | `(' [ FunArgType {`,' FunArgType } ] `)'
16711672
* | '(' [ TypedFunParam {',' TypedFunParam } ')'
@@ -2192,8 +2193,8 @@ object Parsers {
21922193
* | NamedTypeArg {‘,’ NamedTypeArg}
21932194
* TypeArg ::= Type
21942195
* | CaptureSet -- under captureChecking
2195-
* NamedTypeArg ::= id ‘=’ Type
2196-
* | ‘cap’ id ‘=’ CaptureSet -- under captureChecking
2196+
* NamedTypeArg ::= id ‘=’ Type -- under namedTypeArguments
2197+
* | ‘cap’ id ‘=’ CaptureSet -- under namedTypeArguments and captureChecking
21972198
* NamesAndTypes ::= NameAndType {‘,’ NameAndType}
21982199
* NameAndType ::= id ‘:’ Type
21992200
*/
@@ -2272,7 +2273,7 @@ object Parsers {
22722273
PostfixOp(t, Ident(tpnme.raw.STAR))
22732274
else t
22742275

2275-
/** TypeArgs ::= `[' Type {`,' Type} `]'
2276+
/** TypeArgs ::= `[' TypeArg {`,' TypeArg} `]'
22762277
* NamedTypeArgs ::= `[' NamedTypeArg {`,' NamedTypeArg} `]'
22772278
*/
22782279
def typeArgs(namedOK: Boolean, wildOK: Boolean): List[Tree] =
@@ -3540,22 +3541,22 @@ object Parsers {
35403541
/** ClsTypeParamClause::= ‘[’ ClsTypeParam {‘,’ ClsTypeParam} ‘]’
35413542
* ClsTypeParam ::= {Annotation} [‘+’ | ‘-’]
35423543
* id [HkTypeParamClause] TypeAndCtxBounds
3543-
* | {Annotation} ‘cap’ id CaptureSetAndCtxBounds -- under captureChecking
3544+
* | {Annotation} ‘cap’ id CaptureSetAndCtxBounds -- under captureChecking
35443545
*
35453546
* DefTypeParamClause::= ‘[’ DefTypeParam {‘,’ DefTypeParam} ‘]’
35463547
* DefTypeParam ::= {Annotation}
35473548
* id [HkTypeParamClause] TypeAndCtxBounds
3548-
* | {Annotation} ‘cap’ id CaptureSetAndCtxBounds -- under captureChecking
3549+
* | {Annotation} ‘cap’ id CaptureSetAndCtxBounds -- under captureChecking
35493550
*
35503551
* TypTypeParamClause::= ‘[’ TypTypeParam {‘,’ TypTypeParam} ‘]’
35513552
* TypTypeParam ::= {Annotation}
35523553
* (id | ‘_’) [HkTypeParamClause] TypeAndCtxBounds
3553-
* | {Annotation} ‘cap’ (id | ‘_’) CaptureSetAndCtxBounds -- under captureChecking
3554+
* | {Annotation} ‘cap’ (id | ‘_’) CaptureSetAndCtxBounds -- under captureChecking
35543555
*
35553556
* HkTypeParamClause ::= ‘[’ HkTypeParam {‘,’ HkTypeParam} ‘]’
35563557
* HkTypeParam ::= {Annotation} [‘+’ | ‘-’]
35573558
* (id | ‘_’) [HkTypePamClause] TypeBounds
3558-
* | {Annotation} ‘cap’ (id | ‘_’) CaptureSetBounds -- under captureChecking
3559+
* | {Annotation} ‘cap’ (id | ‘_’) CaptureSetBounds -- under captureChecking
35593560
*/
35603561
def typeParamClause(paramOwner: ParamOwner): List[TypeDef] = inBracketsWithCommas {
35613562

‎docs/_docs/internals/syntax.md‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ type val var while with yield
141141
### Soft keywords
142142

143143
```
144-
as derives end erased extension infix inline opaque open throws tracked transparent using | * + -
144+
as cap derives end erased extension infix inline mut opaque open throws tracked transparent using | * + -
145145
```
146146

147147
See the [separate section on soft keywords](../reference/soft-modifier.md) for additional
@@ -182,15 +182,19 @@ Type ::= FunType
182182
| MatchType
183183
| InfixType
184184
FunType ::= FunTypeArgs (‘=>’ | ‘?=>’) Type Function(ts, t) | FunctionWithMods(ts, t, mods, erasedParams)
185-
| TypTypeParamClause '=>' Type PolyFunction(ps, t)
185+
| FunTypeArgs (‘->’ | ‘?->’) [CaptureSet] Type -- under pureFunctions and captureChecking
186+
| TypTypeParamClause ‘=>’ Type PolyFunction(ps, t)
187+
| TypTypeParamClause ‘->’ [CaptureSet] Type -- under pureFunctions and captureChecking
186188
FunTypeArgs ::= InfixType
187189
| ‘(’ [ FunArgTypes ] ‘)’
188190
| FunParamClause
189191
FunParamClause ::= ‘(’ TypedFunParam {‘,’ TypedFunParam } ‘)’
190192
TypedFunParam ::= [`erased`] id ‘:’ Type
191193
MatchType ::= InfixType `match` <<< TypeCaseClauses >>>
192194
InfixType ::= RefinedType {id [nl] RefinedType} InfixOp(t1, op, t2)
195+
| RefinedType ‘^’ -- under captureChecking
193196
RefinedType ::= AnnotType {[nl] Refinement} RefinedTypeTree(t, ds)
197+
| AnnotType {[nl] Refinement} [‘^’ CaptureSet] -- under captureChecking
194198
AnnotType ::= SimpleType {Annotation} Annotated(t, annot)
195199
AnnotType1 ::= SimpleType1 {Annotation} Annotated(t, annot)
196200
@@ -210,16 +214,18 @@ Singleton ::= SimpleRef
210214
| Singleton ‘.’ id
211215
FunArgType ::= Type
212216
| ‘=>’ Type PrefixOp(=>, t)
217+
| ‘->’ [CaptureSet] Type -- under captureChecking
213218
FunArgTypes ::= FunArgType { ‘,’ FunArgType }
214219
ParamType ::= [‘=>’] ParamValueType
220+
| ‘->’ [CaptureSet] ParamValueType -- under captureChecking
215221
ParamValueType ::= Type [‘*’] PostfixOp(t, "*")
216222
| IntoType
217223
| ‘(’ IntoType ‘)’ ‘*’ PostfixOp(t, "*")
218224
IntoType ::= [‘into’] IntoTargetType Into(t)
219225
| ‘(’ IntoType ‘)’
220226
IntoTargetType ::= Type
221227
| FunTypeArgs (‘=>’ | ‘?=>’) IntoType
222-
TypeArgs ::= ‘[’ Types ‘]’ ts
228+
TypeArgs ::= ‘[’ TypeArg {‘,’ TypeArg} ‘]’ ts
223229
Refinement ::= :<<< [RefineDcl] {semi [RefineDcl]} >>> ds
224230
TypeBounds ::= [‘>:’ Type] [‘<:’ Type] TypeBoundsTree(lo, hi)
225231
TypeAndCtxBounds ::= TypeBounds [‘:’ ContextBounds] ContextBounds(typeBounds, tps)
@@ -228,8 +234,15 @@ ContextBounds ::= ContextBound
228234
| '{' ContextBound {',' ContextBound} '}'
229235
ContextBound ::= Type ['as' id]
230236
Types ::= Type {‘,’ Type}
237+
TypeArg ::= Type
238+
| CaptureSet -- under captureChecking
231239
NamesAndTypes ::= NameAndType {‘,’ NameAndType}
232240
NameAndType ::= id ':' Type
241+
CaptureSet ::= ‘{’ CaptureRef {‘,’ CaptureRef} ‘}’ -- under captureChecking
242+
CaptureRef ::= { SimpleRef ‘.’ } SimpleRef [‘*’] [‘.’ ‘rd’] -- under captureChecking
243+
| [ { SimpleRef ‘.’ } SimpleRef ‘.’ ] id -- under captureChecking
244+
CaptureSetBounds ::= [‘>:’ CaptureSet ] [‘<:’ CaptureSet ] -- under captureChecking
245+
CaptureSetAndCtxBounds ::= CaptureSetBounds [‘:’ ContextBounds] -- under captureChecking
233246
```
234247

235248
### Expressions
@@ -365,16 +378,20 @@ ArgumentPatterns ::= ‘(’ [Patterns] ‘)’
365378
ClsTypeParamClause::= ‘[’ ClsTypeParam {‘,’ ClsTypeParam} ‘]’
366379
ClsTypeParam ::= {Annotation} [‘+’ | ‘-’] TypeDef(Modifiers, name, tparams, bounds)
367380
id [HkTypeParamClause] TypeAndCtxBounds Bound(below, above, context)
381+
| {Annotation} ‘cap’ id CaptureSetAndCtxBounds -- under captureChecking
368382
369383
DefTypeParamClause::= [nl] ‘[’ DefTypeParam {‘,’ DefTypeParam} ‘]’
370384
DefTypeParam ::= {Annotation} id [HkTypeParamClause] TypeAndCtxBounds
385+
| {Annotation} ‘cap’ id CaptureSetAndCtxBounds -- under captureChecking
371386
372387
TypTypeParamClause::= ‘[’ TypTypeParam {‘,’ TypTypeParam} ‘]’
373388
TypTypeParam ::= {Annotation} (id | ‘_’) [HkTypeParamClause] TypeBounds
389+
| {Annotation} ‘cap’ id CaptureSetAndCtxBounds -- under captureChecking
374390
375391
HkTypeParamClause ::= ‘[’ HkTypeParam {‘,’ HkTypeParam} ‘]’
376392
HkTypeParam ::= {Annotation} [‘+’ | ‘-’] (id | ‘_’) [HkTypeParamClause]
377393
TypeBounds
394+
| {Annotation} ‘cap’ id CaptureSetAndCtxBounds -- under captureChecking
378395
379396
ClsParamClauses ::= {ClsParamClause} [[nl] ‘(’ [‘implicit’] ClsParams ‘)’]
380397
ClsParamClause ::= [nl] ‘(’ ClsParams ‘)’
@@ -419,6 +436,8 @@ LocalModifier ::= ‘abstract’
419436
| ‘infix’
420437
| ‘erased’
421438
| ‘tracked’
439+
| ‘mut’ -- under captureChecking
440+
| ‘cap’ -- under captureChecking
422441
423442
AccessModifier ::= (‘private’ | ‘protected’) [AccessQualifier]
424443
AccessQualifier ::= ‘[’ id ‘]’
@@ -448,13 +467,15 @@ RefineDcl ::= ‘val’ ValDcl
448467
| ‘var’ ValDcl
449468
| ‘def’ DefDcl
450469
| ‘type’ {nl} TypeDef
470+
| ‘cap’ ‘type’ {nl} CapDef -- under captureChecking
451471
ValDcl ::= ids ‘:’ Type
452472
DefDcl ::= DefSig ‘:’ Type
453473
454474
Def ::= ‘val’ PatDef
455475
| ‘var’ PatDef
456476
| ‘def’ DefDef
457477
| ‘type’ {nl} TypeDef
478+
| ‘cap’ ‘type’ {nl} CapDef -- under captureChecking
458479
| TmplDef
459480
PatDef ::= ids [‘:’ Type] [‘=’ Expr]
460481
| Pattern2 [‘:’ Type] [‘=’ Expr] PatDef(_, pats, tpe?, expr)
@@ -463,6 +484,7 @@ DefDef ::= DefSig [‘:’ Type] [‘=’ Expr]
463484
DefSig ::= id [DefParamClauses] [DefImplicitClause]
464485
TypeDef ::= id [HkTypeParamClause] {FunParamClause} TypeAndCtxBounds TypeDefTree(_, name, tparams, bound
465486
[‘=’ Type]
487+
CapDef ::= id CaptureSetAndCtxBounds [‘=’ CaptureSet] -- under captureChecking
466488
467489
TmplDef ::= ([‘case’] ‘class’ | ‘trait’) ClassDef
468490
| [‘case’] ‘object’ ObjectDef

0 commit comments

Comments
 (0)