Skip to content

Commit 379dbb0

Browse files
retronymretronym
committed
Merge pull request #3984 from gourlaysama/wip/spec
General formatting improvements in the spec
2 parents 79f59c5 + d24ad90 commit 379dbb0

20 files changed

+656
-773
lines changed

‎spec/01-lexical-syntax.md‎

Lines changed: 28 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Scala programs are written using the Unicode Basic Multilingual Plane
1111
presently supported. This chapter defines the two modes of Scala's
1212
lexical syntax, the Scala mode and the _XML mode_. If not
1313
otherwise mentioned, the following descriptions of Scala tokens refer
14-
to _Scala mode_, and literal characters ‘c’ refer to the ASCII fragment
14+
to _Scala mode_, and literal characters ‘c’ refer to the ASCII fragment
1515
`\u0000` – `\u007F`.
1616

1717
In Scala mode, _Unicode escapes_ are replaced by the corresponding
@@ -29,7 +29,7 @@ but I can't make it work nor can I imagine how this would make sense,
2929
so I removed it for now.
3030
-->
3131

32-
To construct tokens, characters are distinguished according to the following
32+
To construct tokens, characters are distinguished according to the following
3333
classes (Unicode general category given in parentheses):
3434

3535
1. Whitespace characters. `\u0020 | \u0009 | \u000D | \u000A`.
@@ -41,13 +41,13 @@ classes (Unicode general category given in parentheses):
4141
1. Parentheses `‘(’ | ‘)’ | ‘[’ | ‘]’ | ‘{’ | ‘}’ `.
4242
1. Delimiter characters ``‘`’ | ‘'’ | ‘"’ | ‘.’ | ‘;’ | ‘,’ ``.
4343
1. Operator characters. These consist of all printable ASCII characters
44-
`\u0020` - `\u007F` which are in none of the sets above, mathematical
44+
`\u0020` - `\u007F` which are in none of the sets above, mathematical
4545
symbols (`Sm`) and other symbols (`So`).
4646

4747
## Identifiers
4848

4949
```ebnf
50-
op ::= opchar {opchar}
50+
op ::= opchar {opchar}
5151
varid ::= lower idrest
5252
plainid ::= upper idrest
5353
| varid
@@ -61,14 +61,14 @@ There are three ways to form an identifier. First, an identifier can
6161
start with a letter which can be followed by an arbitrary sequence of
6262
letters and digits. This may be followed by underscore ‘_’
6363
characters and another string composed of either letters and digits or
64-
of operator characters. Second, an identifier can start with an operator
64+
of operator characters. Second, an identifier can start with an operator
6565
character followed by an arbitrary sequence of operator characters.
6666
The preceding two forms are called _plain_ identifiers. Finally,
6767
an identifier may also be formed by an arbitrary string between
6868
back-quotes (host systems may impose some restrictions on which
6969
strings are legal for identifiers). The identifier then is composed
7070
of all characters excluding the backquotes themselves.
71-
71+
7272
As usual, a longest match rule applies. For instance, the string
7373

7474
```scala
@@ -92,8 +92,8 @@ do else extends false final
9292
finally for forSome if implicit
9393
import lazy match new null
9494
object override package private protected
95-
return sealed super this throw
96-
trait try true type val
95+
return sealed super this throw
96+
trait try true type val
9797
var while with yield
9898
_ : = => <- <: <% >: # @
9999
```
@@ -115,7 +115,6 @@ For instance, the statement `Thread.yield()` is illegal, since
115115
`yield` is a reserved word in Scala. However, here's a
116116
work-around: `` Thread.`yield`() ``
117117

118-
119118
## Newline Characters
120119

121120
```ebnf
@@ -134,16 +133,16 @@ The tokens that can terminate a statement are: literals, identifiers
134133
and the following delimiters and reserved words:
135134

136135
```scala
137-
this null true false return type <xml-start>
136+
this null true false return type <xml-start>
138137
_ ) ] }
139138
```
140139

141140
The tokens that can begin a statement are all Scala tokens _except_
142141
the following delimiters and reserved words:
143142

144143
```scala
145-
catch else extends finally forSome match
146-
with yield , . ; : = => <- <: <%
144+
catch else extends finally forSome match
145+
with yield , . ; : = => <- <: <%
147146
>: # [ ) ] }
148147
```
149148

@@ -169,7 +168,7 @@ Newlines are disabled in:
169168
1. Any regions analyzed in [XML mode](#xml-mode).
170169

171170
Note that the brace characters of `{...}` escapes in XML and
172-
string literals are not tokens,
171+
string literals are not tokens,
173172
and therefore do not enclose a region where newlines
174173
are enabled.
175174

@@ -179,7 +178,7 @@ between the two tokens. However, if two tokens are separated by at
179178
least one completely blank line (i.e a line which contains no
180179
printable characters), then two `nl` tokens are inserted.
181180

182-
The Scala grammar (given in full [here](#scala-syntax-summary))
181+
The Scala grammar (given in full [here](13-syntax-summary.html))
183182
contains productions where optional `nl` tokens, but not
184183
semicolons, are accepted. This has the effect that a newline in one of these
185184
positions does not terminate an expression or statement. These positions can
@@ -189,21 +188,21 @@ Multiple newline tokens are accepted in the following places (note
189188
that a semicolon in place of the newline would be illegal in every one
190189
of these cases):
191190

192-
- between the condition of a
191+
- between the condition of a
193192
[conditional expression](06-expressions.html#conditional-expressions)
194193
or [while loop](06-expressions.html#while-loop-expressions) and the next
195194
following expression,
196-
- between the enumerators of a
195+
- between the enumerators of a
197196
[for-comprehension](06-expressions.html#for-comprehensions-and-for-loops)
198197
and the next following expression, and
199-
- after the initial `type` keyword in a
198+
- after the initial `type` keyword in a
200199
[type definition or declaration](04-basic-declarations-and-definitions.html#type-declarations-and-type-aliases).
201200

202201
A single new line token is accepted
203202

204203
- in front of an opening brace ‘{’, if that brace is a legal
205204
continuation of the current statement or expression,
206-
- after an [infix operator](06-expressions.html#prefix-infix-and-postfix-operations),
205+
- after an [infix operator](06-expressions.html#prefix,-infix,-and-postfix-operations),
207206
if the first token on the next line can start an expression,
208207
- in front of a [parameter clause](04-basic-declarations-and-definitions.html#function-declarations-and-definitions), and
209208
- after an [annotation](11-user-defined-annotations.html#user-defined-annotations).
@@ -300,16 +299,15 @@ illegal).
300299
protected class Data { ... }
301300
```
302301

303-
304302
## Literals
305303

306304
There are literals for integer numbers, floating point numbers,
307305
characters, booleans, symbols, strings. The syntax of these literals is in
308306
each case as in Java.
309307

310-
<!-- TODO
308+
<!-- TODO
311309
say that we take values from Java, give examples of some lits in
312-
particular float and double.
310+
particular float and double.
313311
-->
314312

315313
```ebnf
@@ -322,11 +320,10 @@ Literal ::= [‘-’] integerLiteral
322320
| ‘null’
323321
```
324322

325-
326323
### Integer Literals
327324

328325
```ebnf
329-
integerLiteral ::= (decimalNumeral | hexNumeral | octalNumeral)
326+
integerLiteral ::= (decimalNumeral | hexNumeral | octalNumeral)
330327
[‘L’ | ‘l’]
331328
decimalNumeral ::= ‘0’ | nonZeroDigit {digit}
332329
hexNumeral ::= ‘0’ ‘x’ hexDigit {hexDigit}
@@ -356,14 +353,12 @@ is _pt_. The numeric ranges given by these types are:
356353
|`Short` | $-2\^{15}$ to $2\^{15}-1$|
357354
|`Char` | $0$ to $2\^{16}-1$ |
358355

359-
360356
### Example
361357

362358
```scala
363359
0 21 0xFFFFFFFF -42L
364360
```
365361

366-
367362
### Floating Point Literals
368363

369364
```ebnf
@@ -410,7 +405,6 @@ booleanLiteral ::= ‘true’ | ‘false’
410405
The boolean literals `true` and `false` are
411406
members of type `Boolean`.
412407

413-
414408
### Character Literals
415409

416410
```ebnf
@@ -429,11 +423,10 @@ by an [escape sequence](#escape-sequences).
429423

430424
Note that `'\u000A'` is _not_ a valid character literal because
431425
Unicode conversion is done before literal parsing and the Unicode
432-
character \\u000A (line feed) is not a printable
426+
character `\u000A` (line feed) is not a printable
433427
character. One can use instead the escape sequence `'\n'` or
434428
the octal escape `'\12'` ([see here](#escape-sequences)).
435429

436-
437430
### String Literals
438431

439432
```ebnf
@@ -446,7 +439,7 @@ characters are either printable unicode character or are described by
446439
[escape sequences](#escape-sequences). If the string literal
447440
contains a double quote character, it must be escaped,
448441
i.e. `"\""`. The value of a string literal is an instance of
449-
class `String`.
442+
class `String`.
450443

451444
### Example
452445

@@ -500,17 +493,16 @@ evaluates to
500493

501494
```scala
502495
the present string
503-
spans three
496+
spans three
504497
lines.
505498
```
506499

507500
Method `stripMargin` is defined in class
508-
[scala.collection.immutable.StringLike](http://www.scala-lang.org/api/current/index.html#scala.collection.immutable.StringLike).
501+
[scala.collection.immutable.StringLike](http://www.scala-lang.org/api/current/#scala.collection.immutable.StringLike).
509502
Because there is a predefined
510503
[implicit conversion](06-expressions.html#implicit-conversions) from `String` to
511504
`StringLike`, the method is applicable to all strings.
512505

513-
514506
### Escape Sequences
515507

516508
The following escape sequences are recognized in character and string literals.
@@ -526,15 +518,13 @@ The following escape sequences are recognized in character and string literals.
526518
| `‘\‘ ‘'‘` | `\u0027` | single quote | `'` |
527519
| `‘\‘ ‘\‘` | `\u005c` | backslash | `\` |
528520

529-
530521
A character with Unicode between 0 and 255 may also be represented by
531-
an octal escape, i.e. a backslash ‘\’ followed by a
522+
an octal escape, i.e. a backslash `'\'` followed by a
532523
sequence of up to three octal characters.
533524

534525
It is a compile time error if a backslash character in a character or
535526
string literal does not start a valid escape sequence.
536527

537-
538528
### Symbol literals
539529

540530
```ebnf
@@ -557,7 +547,6 @@ caches weak references to `Symbol`s, thus ensuring that
557547
identical symbol literals are equivalent with respect to reference
558548
equality.
559549

560-
561550
## Whitespace and Comments
562551

563552
Tokens may be separated by whitespace characters
@@ -572,7 +561,6 @@ but are required to be properly nested. Therefore, a comment like
572561
`/* /* */` will be rejected as having an unterminated
573562
comment.
574563

575-
576564
## XML mode
577565

578566
In order to allow literal inclusion of XML fragments, lexical analysis
@@ -589,10 +577,10 @@ brace and immediately followed by a character starting an XML name.
589577

590578
The scanner switches from XML mode to Scala mode if either
591579

592-
- the XML expression or the XML pattern started by the initial ‘<’ has been
580+
- the XML expression or the XML pattern started by the initial ‘<’ has been
593581
successfully parsed, or if
594-
- the parser encounters an embedded Scala expression or pattern and
595-
forces the Scanner
582+
- the parser encounters an embedded Scala expression or pattern and
583+
forces the Scanner
596584
back to normal mode, until the Scala expression or pattern is
597585
successfully parsed. In this case, since code and XML fragments can be
598586
nested, the parser has to maintain a stack that reflects the nesting

‎spec/02-identifiers-names-and-scopes.md‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,14 +17,13 @@ which are collectively called _bindings_.
1717
Bindings of different kinds have a precedence defined on them:
1818

1919
1. Definitions and declarations that are local, inherited, or made
20-
available by a package clause in the same compilation unit where the
21-
definition occurs have highest precedence.
20+
available by a package clause in the same compilation unit where the
21+
definition occurs have highest precedence.
2222
1. Explicit imports have next highest precedence.
2323
1. Wildcard imports have next highest precedence.
2424
1. Definitions made available by a package clause not in the
2525
compilation unit where the definition occurs have lowest precedence.
2626

27-
2827
There are two different name spaces, one for [types](03-types.html#types)
2928
and one for [terms](06-expressions.html#expressions). The same name may designate a
3029
type and a term, depending on the context where the name is used.
@@ -33,7 +32,7 @@ A binding has a _scope_ in which the entity defined by a single
3332
name can be accessed using a simple name. Scopes are nested. A binding
3433
in some inner scope _shadows_ bindings of lower precedence in the
3534
same scope as well as bindings of the same or lower precedence in outer
36-
scopes.
35+
scopes.
3736

3837
<!-- TODO: either the example, the spec, or the compiler is wrong
3938
@@ -55,7 +54,7 @@ A reference to an unqualified (type- or term-) identifier $x$ is bound
5554
by the unique binding, which
5655

5756
- defines an entity with name $x$ in the same namespace as the identifier, and
58-
- shadows all other bindings that define entities with name $x$ in that
57+
- shadows all other bindings that define entities with name $x$ in that
5958
namespace.
6059

6160
It is an error if no such binding exists. If $x$ is bound by an
@@ -70,7 +69,6 @@ the member of the type $T$ of $e$ which has the name $x$ in the same
7069
namespace as the identifier. It is an error if $T$ is not a [value type](03-types.html#value-types).
7170
The type of $e.x$ is the member type of the referenced entity in $T$.
7271

73-
7472
### Example
7573

7674
Assume the following two definitions of a objects named `X` in packages `P` and `Q`.
@@ -111,4 +109,3 @@ object A {
111109
println("L20: "+x) // `x' refers to string "abc" here
112110
}}}}}}
113111
```
114-

0 commit comments

Comments
 (0)