Skip to content

Commit 143a0aa

Browse files
oderskyodersky
committed
Align the two synyax.md versions
There was quite some breakage over time where one version but not the other was edited.
1 parent 293f18c commit 143a0aa

File tree

2 files changed

+59
-26
lines changed

2 files changed

+59
-26
lines changed

‎docs/_docs/internals/syntax.md

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,20 @@ layout: doc-page
33
title: "Scala 3 Syntax Summary"
44
---
55

6+
<!--
7+
8+
This page has a companion page at _docs/reference/syntax.md.
9+
10+
!! Make sure to edit both pages in sync. !!
11+
12+
reference/syntax.md shows the official Scala 3 syntax, without deprecated or experimental features.
13+
14+
internals/syntax.md shows the Scala 3 syntax as supported by the parser, including
15+
deprecated and experimental features. It also gives some indications how
16+
productions map to AST nodes.
17+
18+
-->
19+
620
The following description of Scala tokens uses literal characters `‘c’` when
721
referring to the ASCII fragment `\u0000` – `\u007F`.
822

@@ -88,7 +102,6 @@ nl ::= “new line character”
88102
semi ::= ‘;’ | nl {nl}
89103
```
90104

91-
92105
## Optional Braces
93106

94107
The lexical analyzer also inserts `indent` and `outdent` tokens that represent regions of indented code [at certain points](../reference/other-new-features/indentation.md)
@@ -127,7 +140,7 @@ type val var while with yield
127140
### Soft keywords
128141

129142
```
130-
as derives end extension infix inline opaque open transparent using | * + -
143+
as derives end extension infix inline opaque open throws transparent using | * + -
131144
```
132145

133146
See the [separate section on soft keywords](../reference/soft-modifier.md) for additional
@@ -234,13 +247,13 @@ Expr1 ::= [‘inline’] ‘if’ ‘(’ Expr ‘)’ {nl} Expr [[
234247
Ascription ::= ‘:’ InfixType Typed(expr, tp)
235248
| ‘:’ Annotation {Annotation} Typed(expr, Annotated(EmptyTree, annot)*)
236249
Catches ::= ‘catch’ (Expr | ExprCaseClause)
237-
PostfixExpr ::= InfixExpr [id] PostfixOp(expr, op)
250+
PostfixExpr ::= InfixExpr [id] PostfixOp(expr, op) -- only if language.postfixOperators is enabled
238251
InfixExpr ::= PrefixExpr
239252
| InfixExpr id [nl] InfixExpr InfixOp(expr, op, expr)
240253
| InfixExpr id ColonArgument
241254
| InfixExpr MatchClause
242255
MatchClause ::= ‘match’ <<< CaseClauses >>> Match(expr, cases)
243-
PrefixExpr ::= [PrefixOperator] SimpleExpr PrefixOp(expr, op)
256+
PrefixExpr ::= [PrefixOperator] SimpleExpr PrefixOp(expr, op)
244257
PrefixOperator ::= ‘-’ | ‘+’ | ‘~’ | ‘!’
245258
SimpleExpr ::= SimpleRef
246259
| Literal
@@ -258,11 +271,13 @@ SimpleExpr ::= SimpleRef
258271
| SimpleExpr ArgumentExprs Apply(expr, args)
259272
| SimpleExpr ColonArgument -- under language.experimental.fewerBraces
260273
| SimpleExpr ‘_’ PostfixOp(expr, _) (to be dropped)
261-
| XmlExpr -- to be dropped
262-
ColonArgument ::= colon [LambdaStart]
263-
indent (CaseClauses | Block) outdent
264-
LambdaStart ::= FunParams (‘=>’ | ‘?=>’)
265-
| HkTypeParamClause ‘=>’
274+
| XmlExpr -- to be dropped
275+
ColonArgument ::= colon [LambdaStart]
276+
indent (CaseClauses | Block) outdent
277+
LambdaStart ::= FunParams (‘=>’ | ‘?=>’)
278+
| HkTypeParamClause ‘=>’
279+
Quoted ::= ‘'’ ‘{’ Block ‘}’
280+
| ‘'’ ‘[’ Type ‘]’
266281
ExprSplice ::= spliceId -- if inside quoted block
267282
| ‘$’ ‘{’ Block ‘}’ -- unless inside quoted pattern
268283
| ‘$’ ‘{’ Pattern ‘}’ -- when inside quoted pattern
@@ -303,7 +318,7 @@ TypeCaseClause ::= ‘case’ (InfixType | ‘_’) ‘=>’ Type [semi]
303318
304319
Pattern ::= Pattern1 { ‘|’ Pattern1 } Alternative(pats)
305320
Pattern1 ::= Pattern2 [‘:’ RefinedType] Bind(name, Typed(Ident(wildcard), tpe))
306-
Pattern2 ::= [id ‘@’] InfixPattern Bind(name, pat)
321+
Pattern2 ::= [id ‘@’] InfixPattern [‘*’] Bind(name, pat)
307322
InfixPattern ::= SimplePattern { id [nl] SimplePattern } InfixOp(pat, op, pat)
308323
SimplePattern ::= PatVar Ident(wildcard)
309324
| Literal Bind(name, Ident(wildcard))

‎docs/_docs/reference/syntax.md

Lines changed: 34 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,20 @@ title: "Scala 3 Syntax Summary"
44
nightlyOf: https://docs.scala-lang.org/scala3/reference/syntax.html
55
---
66

7+
<!--
8+
9+
This page has a companion page at _docs/internals/syntax.md.
10+
11+
!! Make sure to edit both pages in sync. !!
12+
13+
reference/syntax.md shows the official Scala 3 syntax, without deprecated or experimental features.
14+
15+
internals/syntax.md shows the Scala 3 syntax as supported by the parser, including
16+
deprecated and experimental features. It also gives some indications how
17+
productions map to AST nodes.
18+
19+
-->
20+
721
The following description of Scala tokens uses literal characters `‘c’` when
822
referring to the ASCII fragment `\u0000` – `\u007F`.
923

@@ -28,12 +42,12 @@ upper ::= ‘A’ | … | ‘Z’ | ‘\$’ | ‘_’ “… and U
2842
lower ::= ‘a’ | … | ‘z’ “… and Unicode category Ll”
2943
letter ::= upper | lower “… and Unicode categories Lo, Lt, Nl”
3044
digit ::= ‘0’ | … | ‘9’
31-
paren ::= ‘(’ | ‘)’ | ‘[’ | ‘]’ | ‘{’ | ‘}’ | ‘'(’ | ‘'[’ | ‘'{’
45+
paren ::= ‘(’ | ‘)’ | ‘[’ | ‘]’ | ‘{’ | ‘}’
3246
delim ::= ‘`’ | ‘'’ | ‘"’ | ‘.’ | ‘;’ | ‘,’
33-
opchar ::= “printableChar not matched by (whiteSpace | upper |
34-
lower | letter | digit | paren | delim | opchar |
35-
Unicode_Sm | Unicode_So)”
36-
printableChar ::= “all characters in [\u0020, \u007F] inclusive”
47+
opchar ::= ‘!’ | ‘#’ | ‘%’ | ‘&’ | ‘*’ | ‘+’ | ‘-’ | ‘/’ | ‘:’ |
48+
‘<’ | ‘=’ | ‘>’ | ‘?’ | ‘@’ | ‘\’ | ‘^’ | ‘|’ | ‘~’
49+
“… and Unicode categories Sm, So”
50+
printableChar ::= “all characters in [\u0020, \u007E] inclusive”
3751
charEscapeSeq ::= ‘\’ (‘b’ | ‘t’ | ‘n’ | ‘f’ | ‘r’ | ‘"’ | ‘'’ | ‘\’)
3852
3953
op ::= opchar {opchar}
@@ -46,6 +60,7 @@ id ::= plainid
4660
| ‘`’ { charNoBackQuoteOrNewline | UnicodeEscape | charEscapeSeq } ‘`’
4761
idrest ::= {letter | digit} [‘_’ op]
4862
quoteId ::= ‘'’ alphaid
63+
spliceId ::= ‘$’ alphaid ;
4964
5065
integerLiteral ::= (decimalNumeral | hexNumeral) [‘L’ | ‘l’]
5166
decimalNumeral ::= ‘0’ | nonZeroDigit [{digit | ‘_’} digit]
@@ -95,13 +110,17 @@ The lexical analyzer also inserts `indent` and `outdent` tokens that represent r
95110
In the context-free productions below we use the notation `<<< ts >>>`
96111
to indicate a token sequence `ts` that is either enclosed in a pair of braces `{ ts }` or that constitutes an indented region `indent ts outdent`. Analogously, the
97112
notation `:<<< ts >>>` indicates a token sequence `ts` that is either enclosed in a pair of braces `{ ts }` or that constitutes an indented region `indent ts outdent` that follows
98-
a `:` at the end of a line.
113+
a `colon` token.
114+
115+
A `colon` token reads as the standard colon "`:`" but is generated instead of it where `colon` is legal according to the context free syntax, but only if the previous token
116+
is an alphanumeric identifier, a backticked identifier, or one of the tokens `this`, `super`, `new`, "`)`", and "`]`".
99117

100118
```
119+
colon ::= ':' -- with side conditions explained above
101120
<<< ts >>> ::= ‘{’ ts ‘}’
102121
| indent ts outdent
103122
:<<< ts >>> ::= [nl] ‘{’ ts ‘}’
104-
| `:` indent ts outdent
123+
| colon indent ts outdent
105124
```
106125

107126
## Keywords
@@ -115,15 +134,14 @@ given if implicit import lazy match new
115134
null object override package private protected return
116135
sealed super then throw trait true try
117136
type val var while with yield
118-
: = <- => <: :> #
137+
: = <- => <: >: #
119138
@ =>> ?=>
120139
```
121140

122141
### Soft keywords
123142

124143
```
125-
as derives end extension infix inline opaque open throws
126-
transparent using | * + -
144+
as derives end extension infix inline opaque open transparent using | * + -
127145
```
128146

129147
See the [separate section on soft keywords](./soft-modifier.md) for additional
@@ -182,8 +200,6 @@ SimpleType ::= SimpleLiteral
182200
| Singleton ‘.’ ‘type’
183201
| ‘(’ Types ‘)’
184202
| Refinement
185-
| ‘$’ ‘{’ Block ‘}’ -- unless inside quoted pattern
186-
| ‘$’ ‘{’ Pattern ‘}’ -- only inside quoted pattern
187203
| SimpleType1 TypeArgs
188204
| SimpleType1 ‘#’ id
189205
Singleton ::= SimpleRef
@@ -196,7 +212,7 @@ FunArgTypes ::= FunArgType { ‘,’ FunArgType }
196212
ParamType ::= [‘=>’] ParamValueType
197213
ParamValueType ::= Type [‘*’]
198214
TypeArgs ::= ‘[’ Types ‘]’
199-
Refinement ::= ‘{’ [RefineDcl] {semi [RefineDcl]} ‘}’
215+
Refinement ::= :<<< [RefineDcl] {semi [RefineDcl]} >>>
200216
TypeBounds ::= [‘>:’ Type] [‘<:’ Type]
201217
TypeParamBounds ::= TypeBounds {‘:’ Type}
202218
Types ::= Type {‘,’ Type}
@@ -241,8 +257,7 @@ SimpleExpr ::= SimpleRef
241257
| Literal
242258
| ‘_’
243259
| BlockExpr
244-
| ‘$’ ‘{’ Block ‘}’ -- unless inside quoted pattern
245-
| ‘$’ ‘{’ Pattern ‘}’ -- only inside quoted pattern
260+
| ExprSplice
246261
| Quoted
247262
| quoteId -- only inside splices
248263
| ‘new’ ConstrApp {‘with’ ConstrApp} [TemplateBody]
@@ -254,6 +269,9 @@ SimpleExpr ::= SimpleRef
254269
| SimpleExpr ArgumentExprs
255270
Quoted ::= ‘'’ ‘{’ Block ‘}’
256271
| ‘'’ ‘[’ Type ‘]’
272+
ExprSplice ::= spliceId -- if inside quoted block
273+
| ‘$’ ‘{’ Block ‘}’ -- unless inside quoted pattern
274+
| ‘$’ ‘{’ Pattern ‘}’ -- when inside quoted pattern
257275
ExprsInParens ::= ExprInParens {‘,’ ExprInParens}
258276
ExprInParens ::= PostfixExpr ‘:’ Type
259277
| Expr
@@ -284,7 +302,7 @@ CaseClauses ::= CaseClause { CaseClause }
284302
CaseClause ::= ‘case’ Pattern [Guard] ‘=>’ Block
285303
ExprCaseClause ::= ‘case’ Pattern [Guard] ‘=>’ Expr
286304
TypeCaseClauses ::= TypeCaseClause { TypeCaseClause }
287-
TypeCaseClause ::= ‘case’ InfixType ‘=>’ Type [semi]
305+
TypeCaseClause ::= ‘case’ (InfixType | ‘_’) ‘=>’ Type [semi]
288306
289307
Pattern ::= Pattern1 { ‘|’ Pattern1 }
290308
Pattern1 ::= Pattern2 [‘:’ RefinedType]

0 commit comments

Comments
 (0)