Technical Documentation: scala/scala3

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Scala 3

This is the home of the Scala 3 standard library, compiler, and language spec.
More documentation here.

Building a Local Distribution

1. sbt dist/Universal/packageBin
2. Find the newly-built distributions in dist/target/

Code of Conduct

Scala 3 uses the Scala Code of Conduct
for all communication and discussion. This includes both GitHub, Discord and
other more direct lines of communication such as email.

How to Contribute

• Contributing guide
• Issues where help is wanted
• Policy regarding the use of LLM-based tools

License

Scala 3 is licensed under the Apache License Version 2.0

Overview (`bench/README.md`) Copy Section

Scala 3 Compilation Benchmarks

Compilation benchmarks moved to a separate repository: lampepfl/scala3-benchmarks.

Overview (`community-build/README.md`) Copy Section

Scala 3 Community Build

For information on the community build check out the Community Build section of
the Contributing
Docs.

Overview (`directives-parser/README.md`) Copy Section

Using Directives Parser

The scala3-directives-parser module parses //> using directives from source files.
It is shared between the Scala 3 compiler (REPL, test harness) and
Scala CLI.

The public entry point is UsingDirectivesParser.parse(IndexedSeq[Char]): UsingDirectivesResult.

Pipeline Copy Chapter

Parsing proceeds in three phases:

flowchart LR
  source["Source file"] --> extract["CommentExtractor"]
  extract --> lex["Lexer"]
  lex --> parse["Parser"]
  parse --> result["UsingDirectivesResult"]

1. CommentExtractor scans the source and collects //> using lines from the
   directive region at the top of the file.
2. Lexer tokenizes each directive line into a stream of tokens.
3. Parser converts the token stream into UsingDirective nodes and diagnostics.

Directive region Copy Chapter

Directives must appear in a preamble at the top of the file, before the first
line of code. The result includes a codeOffset field: the byte offset in the
original file where code begins.

Allowed before code Copy Section

• Blank lines
• A #! shebang on the very first line only
• Line comments (// ..., but not //> using ...)
• Block comments (/* ... */), including multi-line and nested comments
• Leading whitespace (spaces or tabs) before //> using
• A UTF-8 BOM (\uFEFF) at the start of the file (stripped before parsing)

Not allowed / ignored Copy Section

• Directives inside block comments, line comments, or ScalaDoc comments
• Directives after the first line of code (ignored with a warning)
• A package declaration or any other code before directives (treats the file as
  having no directive region; post-code directives warn)
• //> using on the same line after a block comment closes (/* comment */ //> using ...)
• Inline block comments within a directive line (not supported; /* becomes part of the key)

Prefix requirement Copy Section

The prefix //> using is required, with zero or more whitespace characters after >:

• //> using scala 3 — valid
• //>using scala 3 — valid
• //> using scala 3 — valid
• //> using scala 3 (with a tab) — valid
• //> notUsing foo — treated as code

Grammar Copy Chapter

Directives ::= { Directive }
Directive  ::= "using" Key Values
Key        ::= Ident                  (dotted keys are a single Ident, e.g. "test.dep")
Values     ::= { [Comma] Value }
Value      ::= StringLit | BoolLit | Ident

When no values follow the key, a single EmptyVal is produced (equivalent to a
flag with no argument).

Each directive occupies one line. Multiple directives are written on consecutive
lines:

//> using scala 3
//> using dep com.lihaoyi::os-lib:0.11.4

Lexical rules Copy Chapter

The lexer operates on the content of a single directive line (including the
//> prefix). Positions in tokens are relative to the original source file.

Bare identifiers and values Copy Section

A bare token is a maximal run of non-whitespace characters. It stops before:

• Whitespace
• A comma followed by whitespace or end-of-line (see comma rule below)
• A double quote " (whitespace is required before a quote; see errors below)

Bare tokens that are exactly using, true, or false are recognized as
special tokens. All other bare tokens become Ident values.

Values may contain ., :, =, and embedded commas (with no following
whitespace). Dotted keys like test.dep are stored as a single key string; the
lexer does not split dots in value position.

Double-quoted strings Copy Section

Double-quoted strings support these escape sequences:

An unterminated string produces a lexer error.

Backtick-quoted identifiers Copy Section

Backtick-quoted text (`native-gc`) is treated as a bare Ident with the
backticks stripped. Empty backtick identifiers ( ``) produce a lexer error.

Boolean literals Copy Section

The bare tokens true and false (case-sensitive) are parsed as boolean values
when they appear in value position.

Commas separating values (deprecated) Copy Section

A comma is a value separator only when immediately followed by whitespace or
end-of-line:

• a, b — two values (a and b); comma separator is deprecated and emits a warning
• a,b — one value (a,b)
• a ,b — two values (a and ,b); no comma separator
• --enable-url-protocols=http,https — one value (embedded comma)
• tabby:tabby:0.2.3,url=https://example.com/tabby.jar — one value (Coursier syntax)

Commas as separators are deprecated. Use whitespace separation instead.

Additional comma edge cases:

• A lone , as a value is accepted literally
• A trailing comma (a, b,) produces two values and two deprecation warnings
• A double comma (a,, b) produces values a, and b, with warnings about
  the value ending in a comma and about comma separators

Value model Copy Chapter

Each parsed value is a DirectiveValue:

Two accessors reconstruct the text:

• stringValue — content without surrounding quotes
• rawText — source form ("hello" for quoted strings, bare text otherwise)

Diagnostics Copy Chapter

Diagnostics are returned as UsingDirectiveDiagnostic(message, severity, position).

Positions are 0-based (line, column, offset in the original file).

On parse errors the parser skips to the next line and continues.

Examples Copy Chapter

Accepted Copy Section

//> using scala 3
//> using dep com.lihaoyi::os-lib:0.11.8
//> using dep com.lihaoyi::os-lib:0.11.8 com.lihaoyi::upickle:4.4.3
//> using test.dep munit::munit:1.3.3
//> using scalacOption "-Xfatal-warnings"
//> using publish.doc true
//> using toolkit
//> using dep tabby:tabby:0.2.3,url=https://example.com/tabby.jar
//> using dep com.lihaoyi::os-lib:0.11.8,exclude=com.lihaoyi%%geny
//> using packaging.graalvmArgs --enable-url-protocols=http,https
//> using `native-gc`

Warnings (still parsed where noted) Copy Section

//> using dep a, b                  // deprecated comma separator; both values parsed
//> using dep a,, b                 // value "a," ends with comma; comma separator
val x = 1
//> using scala 3                   // ignored: directive after code

package x
//> using scala 3                   // ignored: code (package) before directive

Errors Copy Section

//> using                           // missing key after `using`
//> using using foo                 // `using` cannot be a key
//> using true foo                  // boolean literal cannot be a key
//> using dep "unterminated         // unterminated string literal

Overview (`pkgs/README.md`) Copy Section

Configuration for Chocolatey

Official support for Chocolatey started by the release of Scala 3.6.0

[!IMPORTANT]
This folder contains the templates to generate the configuration for Chocolatey.
The scala.nuspec and chocolateyInstall.ps1 files needs to be rewritten by changing the following placeholders:

• @LAUNCHER_VERSION@ : Placeholder for the current scala version to deploy
• @LAUNCHER_URL@ : Placeholder for the URL to the windows zip released on GitHub
• @LAUNCHER_SHA256@ : Placeholder for the SHA256 of the msi file released on GitHub

Important information Copy Chapter

• How to create a Chocolatey package: https://docs.chocolatey.org/en-us/create/create-packages/
• Guidelines to follow for the package icon: https://docs.chocolatey.org/en-us/create/create-packages/#package-icon-guidelines
• .nuspec format specification: https://learn.microsoft.com/en-gb/nuget/reference/nuspec

Overview (`scaladoc/README.md`) Copy Section

Scaladoc

You can find the documentation to help better understand and contribute to
scaladoc here in the contributing guide.

Overview (`docs/_spec/README.md`) Copy Section

WIP Scala 3 Language Specification

This is still a work in progress. There are still Scala 3 features missing, as well as some areas that have not been updated since 2.13 yet.

First of all, the language specification is meant to be correct, precise and clear.

Second, editing, previewing and generating output for the markdown should be simple and easy.

Third, we'd like to support different output formats. An html page per chapter with MathJax seems like a good start, as it satisfies the second requirement, and enables the first one.

Editing Copy Chapter

We are using Jekyll to generate the html.

Check Gemfile for the current versions.

We aim to track the configuration GitHub Pages uses but differences may arise as GitHub Pages evolves.

Building Copy Chapter

To preview locally, run the following commands in the docs/_spec subfolder:

env UID="$(id -u)" GID="$(id -g)" docker-compose up

and open http://localhost:4000/files/archive/spec/3.4/ to view the spec. Jekyll will rebuild as you edit the markdown, but make sure to restart it when you change _config.yml.

General Advice for editors Copy Chapter

• All files must be saved as UTF-8: ensure your editors are configured appropriately.

• Use of the appropriate unicode characters instead of the latex modifiers for accents, etc. is necessary. For example, é instead of \'e.

• MathJAX errors will appear within the rendered DOM as span elements with class mtext and style attribute color: red applied. It is possible to search for this combination in the development tools of the browser of your choice. In chrome, CTRL+F / CMD+F within the inspect element panel allows you to do this.

• This document follows the "one sentence <=> one line" convention, with the following exceptions below.

  • A multiline code block is part of the sentence
  • An enumeration of links is long enough

• Whenever doing an enumeration of the kind "a, ..., z", follow the following conventions:

  • It should always be "separator whitespace period period period separator whitespace", for example , ..., or ,\n...,\n for multiline.
  • If in a code block, only the elements (a and z above) should be in math mode (between forward ticks)
  • If in a math expression, the whole thing should be in a single math mode
  • Look at the Tuple Types section for an example of the different cases above.

• Try to use "Note" blocks to point out logical conclusions that are not obvious, for examples, look at the Tuple Types section.

Macro replacements: Copy Section

• While MathJAX just support LaTeX style command definition, it is recommended to not use this as it will likely cause issues with preparing the document for PDF or ebook distribution.
• \SS (which I could not find defined within the latex source) seems to be closest to \mathscr{S}
• \TYPE is equivalent to `\boldsymbol{type}'
• As MathJAX has no support for slanted font (latex command \sl), so in all instances this should be replaced with \mathit{}
• The macro \U{ABCD} used for unicode character references can be replaced with \uABCD.
• The macro \URange{ABCD}{DCBA} used for unicode character ranges can be replaced with \uABCD-\uDBCA.
• The macro \commadots can be replaced with , … , (But should not, see above).
• There is no adequate replacement for \textsc{...} (small caps) in pandoc markdown. While unicode contains a number of small capital letters, it is notably missing Q and X as these glyphs are intended for phonetic spelling, therefore these cannot be reliably used. For now, the best option is to use underscore emphasis and capitalise the text manually, _LIKE THIS_.

Unicode Character replacements Copy Section

• The unicode left and right single quotation marks (‘ and ’ (U+2018 and U+2019, respectively)) have been used in place of ` and ', where the quotation marks are intended to be paired. These can be typed on a mac using Option+] for a left quote and Option+Shift+] for the right quote.
• Similarly for left and right double quotation marks (“ and ” (U+201C and U+201D, respectively)) in place of ". These can be typed on a mac using Option+[ and Option+Shift+].

Overview (`pkgs/chocolatey/README.md`) Copy Section

Configuration for Chocolatey

Official support for Chocolatey started by the release of Scala 3.6.0

[!IMPORTANT]
This folder contains the templates to generate the configuration for Chocolatey.
The scala.nuspec and chocolateyInstall.ps1 files needs to be rewritten by changing the following placeholders:

• @LAUNCHER_VERSION@ : Placeholder for the current scala version to deploy
• @LAUNCHER_URL@ : Placeholder for the URL to the windows zip released on GitHub
• @LAUNCHER_SHA256@ : Placeholder for the SHA256 of the msi file released on GitHub

Overview (`pkgs/msi/README.md`) Copy Section

Important information Copy Chapter

• We can only build msi packages with stable version number (no RCs, nor Nightlies).
  Example of the error message when building with an RC

error CNDL0108 : The Product/@Version attribute's value, '3.5.1-RC1', is not a valid version.  Legal version values should look like 'x.x.x.x' where x is an integer from 0 to 65534

Overview (`tests/cmdTest-sbt-tests/README.md`) Copy Section

Readme

Do not use this directory for testing sbt projects in general, add a test case to dotty/sbt-test

This directory is for sbt tests that can not be reproduced with sbt scripted tests.

Adding a test here will reduce the performance of running all tests.

Overview (`repl/src/fansi/README.md`) Copy Section

Vendored from lihaoyi/fansi commit c8d4e5b56c46f2b360a441ca6d35620819a1ee52

Changes:

• Added package dotty.vendored
• private[this] -> private
• protected[this] -> protected
• :_* -> *
• added using where necessary for implicit parameters
• added an unsafe cast for null since the original builds without explicit nulls

Overview (`repl/src/pprint/README.md`) Copy Section

Vendored from lihaoyi/pprint commit 66733cc563c1a4c8d694b3daba69ab643a50dd79

Changes:

• Added package dotty.vendored
• [_] -> [?]
• private[this] -> private
• :_* -> *
• added using where necessary for implicit parameters
• added an unsafe cast for null since the original builds without explicit nulls
• added a cast to String | Null for toString since the original builds without explicit nulls
• Commented out an unreachable match case in TPrintImpl (line 116)
• Added a REPL hook to honor user-defined Product.toString implementations

Overview (`repl/src/sourcecode/README.md`) Copy Section

Vendored from lihaoyi/sourcecode commit 7e738aa077e6634fc5346df5f6ccbac52be861ec

Changes:

• Added package dotty.vendored
• [_] -> [?]

Overview (`tests/explicit-nulls/unsafe-common/README.md`) Copy Section

Common tests for unsafe-nulls feature.

All the tests should be compiled with -language:unsafeNulls.

All the tests should produce errors at // error comment locations without -language:unsafeNulls.

Overview (`tests/neg-custom-args/i20491/README.md`) Copy Section

Test case for https://github.com/scala/scala3/issues/20491

Test setup Copy Chapter

The test simulates a missing class dependency:

• cp/testpkg/A.class + cp/testpkg/A.tasty - A Scala trait that references otherpkg.MissingDep
• cp/otherpkg/ - An empty directory (MissingDep.class is missing)

How to regenerate the test files Copy Chapter

otherpkg/MissingDep.java

package otherpkg;
public class MissingDep {}

A.scala

package testpkg
trait A:
  def getDep: otherpkg.MissingDep

scala-cli compile A.scala otherpkg/MissingDep.java -d out

Copy A.class and A.tasty to cp/testpkg/, and ensure cp/otherpkg/ directory
exists but is empty (do not include MissingDep.class).

Overview (`tests/neg-custom-args/missing-java-outer-dependency/README.md`) Copy Section

Missing Java outer class dependency tests

Regenerate the test files Copy Chapter

broken/Outer.java

package broken;
public class Outer {
  public static class Inner {}
}

broken/Child.java

package broken;
public class Child extends Outer.Inner {}

javac -d out broken/Outer.java broken/Child.java

Copy Child.class and Outer$Inner.class to cp/broken/, but do not copy
Outer.class.

suggestions/SearchRoot.java

package suggestions;

public class SearchRoot extends broken.Child {}

javac -classpath out -d search-root-out suggestions/SearchRoot.java

Copy SearchRoot.class to cp/suggestions/.

Overview (`bench-micro/src/main/scala/dotty/tools/benchmarks/specializedtraits/README.md`) Copy Section

Specialized Trait Benchmarks Copy Chapter

Run Copy Section

1. Publish the compiler first and check that the version in the benchmark file corresponds to the generated version,
2. Kill bloop server if republishing an existing version:
   scala-cli --power bloop exit
3. Run the benchmark with:

scala-cli --power --jmh bench-micro/src/main/scala/dotty/tools/benchmarks/specializedtraits/VectorDotProduct.scala

Troubleshooting Copy Section

• May have to run it again / delete .scala-build and rerun if you get a class not found error from scala-cli first time - the --jmh flag is still experimental.

.Ai INDEX (`docs/.ai/INDEX.md`) Copy Section

AI Contributor Guide

This directory is the canonical, tool-agnostic source for project-specific AI workflows in this repository.

Workflows Copy Chapter

• skills/add-error-code-docs.md: Canonical, single-source skill for error-code docs (workflow, template, commands, best-effort rules).

Docs Index (`docs/_docs/index.md`) Copy Section

layout: index redirectFrom: /docs/index.html Copy Chapter

This website contains the developer documentation of the Scala 3 compiler. It targets developers interested in contributing to the compiler, or learning its internals. If you want to learn how to use Scala, go here.

Spec Index (`docs/_spec/index.md`) Copy Section

title: Scala Language Specification layout: toc Copy Chapter

{% include table-of-contents.yml %}

Authors and Contributors

Martin Odersky, Philippe Altherr, Vincent Cremet, Sébastien Doeraene, Gilles Dubochet, Burak Emir, Philipp Haller, Stéphane Micheloud, Nikolay Mihaylov, Adriaan Moors, Lukas Rytz, Michel Schinz, Erik Stenman, Matthias Zenger

Markdown Conversion by Iain McGinniss.

Disclaimer: Work in Progress

This specification for Scala 3 is still a work in progress.
Some features added in Scala 3 are missing.
Here is a list of the most important missing aspects:

• extension methods
• given and using contextual abstractions
• type-class derivation with derives
• behavior of structural types based on Selectable
• meta-programming with inline defs and quotes
• match types (pending a Scala Improvement Proposal with a full specification)

For those features, the best reference so far remains the Scala 3 Reference.

Preface

Scala is a Java-like programming language which unifies
object-oriented and functional programming. It is a pure
object-oriented language in the sense that every value is an
object. Types and behavior of objects are described by
classes. Classes can be composed using mixin composition. Scala is
designed to work seamlessly with less pure but mainstream
object-oriented languages like Java.

Scala is a functional language in the sense that every function is a
value. Nesting of function definitions and higher-order functions are
naturally supported. Scala also supports a general notion of pattern
matching which can model the algebraic types used in many functional
languages.

Scala has been designed to interoperate seamlessly with Java.
Scala classes can call Java methods, create Java objects, inherit from Java
classes and implement Java interfaces. None of this requires interface
definitions or glue code.

Scala has been developed from 2001 in the programming methods laboratory at EPFL.
Version 1.0 was released in November 2003.
This document describes the third version of the language, which was released in May 2021.
It acts as a reference for the language definition and some core library modules.
It is not intended to teach Scala or its concepts; for this there are other documents.

Scala has been a collective effort of many people. The design and the
implementation of version 1.0 was completed by Philippe Altherr,
Vincent Cremet, Gilles Dubochet, Burak Emir, Stéphane Micheloud,
Nikolay Mihaylov, Michel Schinz, Erik Stenman, Matthias Zenger, and
the author. Iulian Dragos, Gilles Dubochet, Philipp Haller, Sean
McDirmid, Lex Spoon, and Geoffrey Washburn joined in the effort to
develop the second version of the language and tools. Gilad Bracha,
Craig Chambers, Erik Ernst, Matthias Felleisen, Shriram Krishnamurti,
Gary Leavens, Sebastian Maneth, Erik Meijer, Klaus Ostermann, Didier
Rémy, Mads Torgersen, and Philip Wadler have shaped the design of
the language through lively and inspiring discussions and comments on
previous versions of this document. The contributors to the Scala
mailing list have also given very useful feedback that helped us
improve the language and its tools.

Docs Contributing Getting Started (`docs/_docs/contributing/getting-started.md`) Copy Section

layout: doc-page title: Getting Started redirectFrom: /docs/contributing/workflow.html Copy Chapter

Scala CLA Copy Chapter

Sometime before submitting your pull request you'll want to make sure you have
signed the Scala CLA. You can read more about why we require a CLA
and what exactly is included in it here.

Making sure the team is aware Copy Chapter

Before digging into an issue or starting on a new feature it's a good idea to
make sure an issue or a discussion has been
created outlining what you plan to work on. This is both for your and the team's
benefit. It ensures you get the help you need, and also gives the compiler team
a heads-up that someone is working on an issue.

For some small changes like documentation, this isn't always necessary, but it's
never a bad idea to check.

Requirements Copy Chapter

• git is essential for managing the Scala 3 code, and contributing to GitHub,
  where the code is hosted.
• A Java Virtual Machine (JDK 8 or higher), required for running the build tool. Do note, however, that the continuous integration test suite is run on JDK 17.
  • There are multiple ways to get and manage different Java versions. Some
    popular options are:
    • SDKMAN!
    • Coursier
    • Or just download Java directly from Oracle Java 8, Oracle
      Java 11, or AdoptOpenJDK 8/11. Refer to JDK
      Compatibility for Scala/Java compatibility detail.
  • Verify that the JVM is installed by running the following command in a terminal: java -version.
• sbt, the build tool required to build the Scala 3 compiler and libraries.

Nice To Have Copy Chapter

An IDE, such as Metals will help you develop in Scala 3 with features such as
autocompletion, code navigation, debugging, and interactive worksheets.

Another popular options is IntelliJ IDEA for
Scala.

Compiling and Running Copy Chapter

Start by cloning the repository:

$ git clone https://github.com/scala/scala3.git
$ cd scala3

Dotty provides a standard sbt build: compiling, running and starting a repl can
all be done from within sbt:

$ sbt
> scalac tests/pos/HelloWorld.scala
> scala HelloWorld
hello world

There are also bash scripts that can be used in the same way. Assuming that you
have cloned the Dotty repo locally, append the following line on your
.bash_profile, or equivalent for your shell:

$ export PATH=<path to cloned dotty>/bin:$PATH

and you will be able to run the corresponding commands directly from your console:

# Compile code using Dotty
$ scalac tests/pos/HelloWorld.scala

# Run it with the proper classpath
$ scala HelloWorld

Note that the scalac and scala scripts have slow roundtrip times when working on the compiler codebase: whenever
any source file changes they invoke sbt dist/pack first.

As an alternative, run the buildQuick task in sbt. It builds the compiler and writes its classpath to the bin/.cp
file, which enables the scalacQ and scalaQ scripts in the bin/ folder.

Starting a REPL Copy Chapter

$ sbt
> repl
Welcome to Scala.next (pre-alpha)  (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_101).
Type in expressions to have them evaluated.
Type :help for more information.
scala>

or via bash:

$ scala

Publish to local repository Copy Chapter

To test our cloned compiler on local projects:

$ sbt publishLocal

Then in the build.sbt file of a test project:

ThisBuild / scalaVersion := "<dotty-version>-bin-SNAPSHOT"

where dotty-version can be found in the file project/Build.scala, like 3.0.0-M2

Generating Documentation Copy Chapter

To generate this page and other static page docs, run

$ sbt
> scaladoc/generateScalaDocumentation

For more information, see the scaladoc section.

Community Copy Chapter

The main development discussion channels are:

• github.com/scala/scala3/discussions
• contributors.scala-lang.org

Docs Contributing Index (`docs/_docs/contributing/index.md`) Copy Section

layout: index title: Contributing Copy Chapter

This guide is intended to give new contributors the knowledge they need to
become productive and fix issues or implement new features in Scala 3. It
also documents the inner workings of the Scala 3 compiler, dotc.

This is a living document Copy Section

Keep in mind that the code for dotc is continually changing, so the ideas
discussed in this guide may fall out of date. This is a living document, so
please consider contributing to it on
GitHub if
you notice anything out of date, or report any issues
here.

Get the most from This Guide Copy Section

dotc is built with Scala 3, fully utilising its new
features. It is
recommended that you first have some familiarity with Scala 3 to get the most
out of this guide. You can learn more in the language
reference.

Many code snippets in this guide make use of shell commands (a line beginning
with $), and in this case a bash compatible shell is assumed. You may have
to look up how to translate commands to your shell.

What is a Compiler? Copy Section

Let's start at the beginning and first look at the question of "what is a
compiler?". A compiler is a program that takes as input text, representing a
program in one language and produces as output the same program, written in
another programming language.

The Scala Compiler

As an example, dotc takes text input, verifies that it is a valid Scala program
and then produces as output the same program, but written in Java bytecode, and optionally
in SJSIR when producing Scala.js output.

Docs Reference Overview (`docs/_docs/reference/overview.md`) Copy Section

layout: doc-page title: "Reference" nightlyOf: https://docs.scala-lang.org/scala3/reference/overview.html redirectFrom: overview.html Copy Chapter

Scala 3 implements many language changes and improvements over Scala 2.
In this reference, we discuss design decisions and present important differences compared to Scala 2.

Goals Copy Chapter

The language redesign was guided by three main goals:

• Strengthen Scala's foundations.
  Make the full programming language compatible with the foundational work on the
  DOT calculus
  and apply the lessons learned from that work.
• Make Scala easier and safer to use.
  Tame powerful constructs such as implicits to provide a gentler learning curve. Remove warts and puzzlers.
• Further improve the consistency and expressiveness of Scala's language constructs.

Corresponding to these goals, the language changes fall into seven categories:
(1) Core constructs to strengthen foundations, (2) simplifications and (3) restrictions, to make the language easier and safer to use, (4) dropped constructs to make the language smaller and more regular, (5) changed constructs to remove warts, and increase consistency and usability, (6) new constructs to fill gaps and increase expressiveness, (7) a new, principled approach to metaprogramming that replaces Scala 2 experimental macros.

Essential Foundations Copy Chapter

These new constructs directly model core features of DOT, higher-kinded types, and the SI calculus for implicit resolution.

• Intersection types, replacing compound types,
• Union types,
• Type lambdas, replacing encodings using structural types and type projection.
• Context functions, offering abstraction over given parameters.

Simplifications Copy Chapter

These constructs replace existing constructs with the aim of making the language safer and simpler to use, and to promote uniformity in code style.

• Trait parameters
  replace early initializers with a more generally useful construct.
• Given instances
  replace implicit objects and defs, focussing on intent over mechanism.
• Using clauses
  replace implicit parameters, avoiding their ambiguities.
• Extension methods
  replace implicit classes with a clearer and simpler mechanism.
• Opaque type aliases
  replace most uses of value classes while guaranteeing the absence of boxing.
• Top-level definitions
  replace package objects, dropping syntactic boilerplate.
• Export clauses
  provide a simple and general way to express aggregation, which can replace
  the previous facade pattern of package objects inheriting from classes.
• Vararg splices
  now use the form xs* in function arguments and patterns instead of xs: _* and xs @ _*,
• Universal apply methods
  allow using simple function call syntax instead of new expressions. new expressions stay around
  as a fallback for the cases where creator applications cannot be used.

With the exception of early initializers and old-style vararg patterns, all superseded constructs continue to be available in Scala 3.0. The plan is to deprecate and phase them out later.

Value classes (superseded by opaque type aliases) are a special case. There are currently no deprecation plans for value classes, since we might bring them back in a more general form if they are supported natively by the JVM as is planned by project Valhalla.

Restrictions Copy Chapter

These constructs are restricted to make the language safer.

• Implicit Conversions:
  there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import.
• Given Imports:
  implicits now require a special form of import, to make the import clearly visible.
• Type Projection:
  only classes can be used as prefix C of a type projection C#A. Type projection on abstract types is no longer supported since it is unsound.
• Multiversal Equality:
  implement an "opt-in" scheme to rule out nonsensical comparisons with == and !=.
• infix:
  make method application syntax uniform across code bases.

Unrestricted implicit conversions continue to be available in Scala 3.0, but will be deprecated and removed later. Unrestricted versions of the other constructs in the list above are available only under -source 3.0-migration.

Dropped Constructs Copy Chapter

These constructs are proposed to be dropped without a new construct replacing them. The motivation for dropping these constructs is to simplify the language and its implementation.

• DelayedInit,
• Existential types,
• Procedure syntax,
• Class shadowing,
• XML literals,
• Symbol literals,
• Auto application,
• Weak conformance,
• Compound types (replaced by Intersection types),
• Auto tupling (implemented, but not merged).

The date when these constructs are dropped varies. The current status is:

• Not implemented at all:
  • DelayedInit, existential types, weak conformance.
• Supported under -source 3.0-migration:
  • procedure syntax, class shadowing, symbol literals, auto application, auto tupling in a restricted form.
• Supported in 3.0, to be deprecated and phased out later:
  • XML literals, compound types.

Changes Copy Chapter

These constructs have undergone changes to make them more regular and useful.

• Structural Types:
  They now allow pluggable implementations, which greatly increases their usefulness. Some usage patterns are restricted compared to the status quo.
• Name-based pattern matching:
  The existing undocumented Scala 2 implementation has been codified in a slightly simplified form.
• Automatic Eta expansion:
  Eta expansion is now performed universally also in the absence of an expected type. The postfix _ operator is thus made redundant. It will be deprecated and dropped after Scala 3.0.
• Implicit Resolution:
  The implicit resolution rules have been cleaned up to make them more useful and less surprising. Implicit scope is restricted to no longer include package prefixes.

Most aspects of old-style implicit resolution are still available under -source 3.0-migration. The other changes in this list are applied unconditionally.

New Constructs Copy Chapter

These are additions to the language that make it more powerful or pleasant to use.

• Enums provide concise syntax for enumerations and algebraic data types.
• Parameter untupling avoids having to use case for tupled parameter destructuring.
• Dependent function types generalize dependent methods to dependent function values and types.
• Polymorphic function types generalize polymorphic methods to polymorphic function values and types.
  Current status: There is a proposal and a merged prototype implementation, but the implementation has not been finalized (it is notably missing type inference support).
• Kind polymorphism allows the definition of operators working equally on types and type constructors.
• @targetName annotations make it easier to interoperate with code written in other languages and give more flexibility for avoiding name clashes.

Metaprogramming Copy Chapter

The following constructs together aim to put metaprogramming in Scala on a new basis. So far, metaprogramming was achieved by a combination of macros and libraries such as Shapeless that were in turn based on some key macros. Current Scala 2 macro mechanisms are a thin veneer on top of the current Scala 2 compiler, which makes them fragile and in many cases impossible to port to Scala 3.

It's worth noting that macros were never included in the Scala 2 language specification and were so far made available only under an -experimental flag. This has not prevented their widespread usage.

To enable porting most uses of macros, we are experimenting with the advanced language constructs listed below. These designs are more provisional than the rest of the proposed language constructs for Scala 3.0. There might still be some changes until the final release. Stabilizing the feature set needed for metaprogramming is our first priority.

• Match Types
  allow computation on types.
• Inline
  provides by itself a straightforward implementation of some simple macros and is at the same time an essential building block for the implementation of complex macros.
• Quotes and Splices
  provide a principled way to express macros and staging with a unified set of abstractions.
• Type class derivation
  provides an in-language implementation of the Gen macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro.
• By-name context parameters
  provide a more robust in-language implementation of the Lazy macro in Shapeless.

See Also Copy Chapter

A classification of proposed language features is
an expanded version of this page that adds the status (i.e. relative importance to be a part of Scala 3, and relative urgency when to decide this) and expected migration cost
of each language construct.

Spec TODOreference Overview (`docs/_spec/TODOreference/overview.md`) Copy Section

layout: doc-page title: "Reference" nightlyOf: https://docs.scala-lang.org/scala3/reference/overview.html redirectFrom: overview.html Copy Chapter

Scala 3 implements many language changes and improvements over Scala 2.
In this reference, we discuss design decisions and present important differences compared to Scala 2.

Goals Copy Chapter

The language redesign was guided by three main goals:

• Strengthen Scala's foundations.
  Make the full programming language compatible with the foundational work on the
  DOT calculus
  and apply the lessons learned from that work.
• Make Scala easier and safer to use.
  Tame powerful constructs such as implicits to provide a gentler learning curve. Remove warts and puzzlers.
• Further improve the consistency and expressiveness of Scala's language constructs.

Corresponding to these goals, the language changes fall into seven categories:
(1) Core constructs to strengthen foundations, (2) simplifications and (3) restrictions, to make the language easier and safer to use, (4) dropped constructs to make the language smaller and more regular, (5) changed constructs to remove warts, and increase consistency and usability, (6) new constructs to fill gaps and increase expressiveness, (7) a new, principled approach to metaprogramming that replaces Scala 2 experimental macros.

Essential Foundations Copy Chapter

These new constructs directly model core features of DOT, higher-kinded types, and the SI calculus for implicit resolution.

• Intersection types, replacing compound types,
• Union types,
• Type lambdas, replacing encodings using structural types and type projection.
• Context functions, offering abstraction over given parameters.

Simplifications Copy Chapter

These constructs replace existing constructs with the aim of making the language safer and simpler to use, and to promote uniformity in code style.

• Trait parameters
  replace early initializers with a more generally useful construct.
• Given instances
  replace implicit objects and defs, focussing on intent over mechanism.
• Using clauses
  replace implicit parameters, avoiding their ambiguities.
• Extension methods
  replace implicit classes with a clearer and simpler mechanism.
• Opaque type aliases
  replace most uses of value classes while guaranteeing the absence of boxing.
• Top-level definitions
  replace package objects, dropping syntactic boilerplate.
• Export clauses
  provide a simple and general way to express aggregation, which can replace
  the previous facade pattern of package objects inheriting from classes.
• Vararg splices
  now use the form xs* in function arguments and patterns instead of xs: _* and xs @ _*,
• Universal apply methods
  allow using simple function call syntax instead of new expressions. new expressions stay around
  as a fallback for the cases where creator applications cannot be used.

With the exception of early initializers and old-style vararg patterns, all superseded constructs continue to be available in Scala 3.0. The plan is to deprecate and phase them out later.

Value classes (superseded by opaque type aliases) are a special case. There are currently no deprecation plans for value classes, since we might bring them back in a more general form if they are supported natively by the JVM as is planned by project Valhalla.

Restrictions Copy Chapter

These constructs are restricted to make the language safer.

• Implicit Conversions:
  there is only one way to define implicit conversions instead of many, and potentially surprising implicit conversions require a language import.
• Given Imports:
  implicits now require a special form of import, to make the import clearly visible.
• Type Projection:
  only classes can be used as prefix C of a type projection C#A. Type projection on abstract types is no longer supported since it is unsound.
• Multiversal Equality:
  implement an "opt-in" scheme to rule out nonsensical comparisons with == and !=.
• infix:
  make method application syntax uniform across code bases.

Unrestricted implicit conversions continue to be available in Scala 3.0, but will be deprecated and removed later. Unrestricted versions of the other constructs in the list above are available only under -source 3.0-migration.

Dropped Constructs Copy Chapter

These constructs are proposed to be dropped without a new construct replacing them. The motivation for dropping these constructs is to simplify the language and its implementation.

• DelayedInit,
• Existential types,
• Procedure syntax,
• Class shadowing,
• XML literals,
• Symbol literals,
• Auto application,
• Weak conformance,
• Compound types (replaced by Intersection types),
• Auto tupling (implemented, but not merged).

The date when these constructs are dropped varies. The current status is:

• Not implemented at all:
  • DelayedInit, existential types, weak conformance.
• Supported under -source 3.0-migration:
  • procedure syntax, class shadowing, symbol literals, auto application, auto tupling in a restricted form.
• Supported in 3.0, to be deprecated and phased out later:
  • XML literals, compound types.

Changes Copy Chapter

These constructs have undergone changes to make them more regular and useful.

• Structural Types:
  They now allow pluggable implementations, which greatly increases their usefulness. Some usage patterns are restricted compared to the status quo.
• Name-based pattern matching:
  The existing undocumented Scala 2 implementation has been codified in a slightly simplified form.
• Automatic Eta expansion:
  Eta expansion is now performed universally also in the absence of an expected type. The postfix _ operator is thus made redundant. It will be deprecated and dropped after Scala 3.0.
• Implicit Resolution:
  The implicit resolution rules have been cleaned up to make them more useful and less surprising. Implicit scope is restricted to no longer include package prefixes.

Most aspects of old-style implicit resolution are still available under -source 3.0-migration. The other changes in this list are applied unconditionally.

New Constructs Copy Chapter

These are additions to the language that make it more powerful or pleasant to use.

• Enums provide concise syntax for enumerations and algebraic data types.
• Parameter untupling avoids having to use case for tupled parameter destructuring.
• Dependent function types generalize dependent methods to dependent function values and types.
• Polymorphic function types generalize polymorphic methods to polymorphic function values and types.
  Current status: There is a proposal and a merged prototype implementation, but the implementation has not been finalized (it is notably missing type inference support).
• Kind polymorphism allows the definition of operators working equally on types and type constructors.
• @targetName annotations make it easier to interoperate with code written in other languages and give more flexibility for avoiding name clashes.

Metaprogramming Copy Chapter

The following constructs together aim to put metaprogramming in Scala on a new basis. So far, metaprogramming was achieved by a combination of macros and libraries such as Shapeless that were in turn based on some key macros. Current Scala 2 macro mechanisms are a thin veneer on top of the current Scala 2 compiler, which makes them fragile and in many cases impossible to port to Scala 3.

It's worth noting that macros were never included in the Scala 2 language specification and were so far made available only under an -experimental flag. This has not prevented their widespread usage.

To enable porting most uses of macros, we are experimenting with the advanced language constructs listed below. These designs are more provisional than the rest of the proposed language constructs for Scala 3.0. There might still be some changes until the final release. Stabilizing the feature set needed for metaprogramming is our first priority.

• Match Types
  allow computation on types.
• Inline
  provides by itself a straightforward implementation of some simple macros and is at the same time an essential building block for the implementation of complex macros.
• Quotes and Splices
  provide a principled way to express macros and staging with a unified set of abstractions.
• Type class derivation
  provides an in-language implementation of the Gen macro in Shapeless and other foundational libraries. The new implementation is more robust, efficient and easier to use than the macro.
• By-name context parameters
  provide a more robust in-language implementation of the Lazy macro in Shapeless.

See Also Copy Chapter

A classification of proposed language features is
an expanded version of this page that adds the status (i.e. relative importance to be a part of Scala 3, and relative urgency when to decide this) and expected migration cost
of each language construct.

Scaladoc Testcases Docs Docs Index (`scaladoc-testcases/docs/_docs/index.md`) Copy Section

val someVariable: Int = 2

trait RenderingContext
class Renderer(using RenderingContext)
val renderer: Renderer = Renderer()

trait Ord:
    type Self

  trait SemiGroup:
    type Self
    extension (x: Self) def combine(y: Self): Self

def exampleShouldError(input: Option[String]): Unit = 
  input match
    case Some("foo") => ???

def exampleShouldWarn(input: Option[String]): Unit = 
  input match
    case Some("foo") => ???

Docs Contributing Architecture Index (`docs/_docs/contributing/architecture/index.md`) Copy Section

layout: index title: High Level Architecture Copy Chapter

This chapter of the guide describes the architecture and concepts of dotc,
the Scala 3 compiler, including answers to questions such as:

• "What are the transformations that happen to my code?"
• "How do I run a compiler programatically?"
• "What are symbols, denotations, names and types?"
• "What is a compiler phase?"
• "What is the compiler Context?"

and many more.

Docs Contributing Procedures Index (`docs/_docs/contributing/procedures/index.md`) Copy Section

layout: index title: Procedures Copy Chapter

This chapter of the guide describes:

• How to test the vulpix framework

Docs Reference Enums Enums Index (`docs/_docs/reference/enums/enums-index.md`) Copy Section

layout: index title: "Enums" movedTo: https://docs.scala-lang.org/scala3/reference/enums/index.html Copy Chapter

This chapter documents enums in Scala 3.

Docs Reference Experimental Overview (`docs/_docs/reference/experimental/overview.md`) Copy Section

layout: doc-page title: "Experimental" nightlyOf: https://docs.scala-lang.org/scala3/reference/experimental/overview.html redirectFrom: overview.html Copy Chapter

Experimental language features Copy Chapter

All experimental language features can be found under the scala.language.experimental package.
They are enabled by importing the feature or using the -language compiler flag.

• erasedDefinitions: Enable support for erased modifier.
• methodBlockEndMarkers: Enable support for end markers for method blocks.
• fewerBraces: Enable support for using indentation for arguments.
• genericNumberLiterals: Enable support for generic number literals.
• namedTypeArguments: Enable support for named type arguments
• saferExceptions: Enable support for checked exceptions.

Experimental language imports Copy Chapter

In general, experimental language features can be imported in an experimental scope (see experimental definitions).
They can be imported at the top-level if all top-level definitions are @experimental.

`-experimental` compiler flag Copy Section

This flag enables the use of any experimental language feature in the project.
It does this by adding an @experimental annotation to all top-level definitions.
Hence, dependent projects also have to be experimental.

Experimental language features supported by special compiler options Copy Chapter

Some experimental language features that are still in research and development can be enabled with special compiler options. These include

• -Yexplicit-nulls. Enable support for tracking null references in the type system.
• -Ycc. Enable support for capture checking.

Docs Reference Preview Overview (`docs/_docs/reference/preview/overview.md`) Copy Section

layout: doc-page title: "Preview" nightlyOf: https://docs.scala-lang.org/scala3/reference/preview/overview.html redirectFrom: overview.html Copy Chapter

Preview language features Copy Chapter

New Scala language features or standard library APIs are initially introduced as experimental, but once they become fully implemented and accepted by the SIP these can become a preview features.

Preview language features and APIs are guaranteed to be standardized in some next Scala minor release, but allow the compiler team to introduce small, possibly binary incompatible, changes based on the community feedback.
These can be used by early adopters who can accept the possibility of binary compatibility breakage. For instance, preview features could be used in some internal tool or application. On the other hand, preview features are discouraged in publicly available libraries.

More information about preview features can be found in preview definitions guide

`-preview` compiler flag Copy Section

This flag enables the use of all preview language feature in the project.

List of available preview features Copy Chapter

• Automatic Parameter Unrolling with @unroll (SIP-61)
• Reference-able Package Objects (SIP-68)
• Relaxed Lambda Syntax (SIP-75)

Spec APPLIEDreference Enums Enums Index (`docs/_spec/APPLIEDreference/enums/enums-index.md`) Copy Section

layout: index title: "Enums" nightlyOf: https://docs.scala-lang.org/scala3/reference/enums/index.html Copy Chapter

This chapter documents enums in Scala 3.

Spec TODOreference Experimental Overview (`docs/_spec/TODOreference/experimental/overview.md`) Copy Section

layout: doc-page title: "Experimental" nightlyOf: https://docs.scala-lang.org/scala3/reference/experimental/overview.html redirectFrom: overview.html Copy Chapter

Experimental language features Copy Chapter

All experimental language features can be found under the scala.language.experimental package.
They are enabled by importing the feature or using the -language compiler flag.

• erasedDefinitions: Enable support for erased modifier.
• fewerBraces: Enable support for using indentation for arguments.
• genericNumberLiterals: Enable support for generic number literals.
• namedTypeArguments: Enable support for named type arguments
• saferExceptions: Enable support for checked exceptions.

Experimental language imports Copy Chapter

In general, experimental language features can be imported in an experimental scope (see experimental definitions).
They can be imported at the top-level if all top-level definitions are @experimental.

Experimental language features supported by special compiler options Copy Chapter

Some experimental language features that are still in research and development can be enabled with special compiler options. These include

• -Yexplicit-nulls. Enable support for tracking null references in the type system.
• -Ycc. Enable support for capture checking.

Docs Reference Experimental Capture Checking Overview (`docs/_docs/reference/experimental/capture-checking/overview.md`) Copy Section

layout: doc-page title: "Tracked Capabilities Overview" nightlyOf: https://docs.scala-lang.org/scala3/reference/experimental/capture-checking/overview.html Copy Chapter

Introduction Copy Section

import language.experimental.captureChecking
import caps.*

import language.experimental.captureChecking
import caps.*

Tracked capabilities are the most important new feature of Scala. This page gives an overview of
the underlying concepts, focusing on what capabilities can express and what one can do with them.

For a more systematic description of all the details we refer you to the following pages:

• Capture Checking Basics: Getting started with capture checking.
• Capture Checking of Classes: Rules for capture checking classes and objects.
• Capability Polymorphism: Subtyping of capturing types and capture set variables.
• Scoping of Capabilities: Scoping of any and fresh capabilities.
• Capability Classifiers: Classifiers for capabilities and projection with the .only[...] and .except[...] operators.
• Checked Exceptions: CanThrow capabilities and throws clauses.
• Stateful Capabilities: Capabilities for mutable data structures.
• Separation Checking: More detailed checking for controlling aliasing and sharing of capabilities.
• How to Use the Capture Checker: Instructions how to enable and configure capture checking.
• Internals: Description of some of the internals of the capture checker for implementers.

Tracked capabilities are supported under Scala's capture checking extension, which can be enabled
by the language import

import language.experimental.captureChecking

Some more features of capture checking having to do with mutable data structures and alias control currently require a separate language import

import language.experimental.separationChecking

Both extensions are experimental, which means that details can still change. Capture checking is by now quite mature and we expect it to be stabilized soon. Separation checking is still a bit more fluid at present.

Capabilities Copy Section

Informally, a capability is a value "of interest". For instance, a file handle, an access permission token, or a mutable data structure all make sense as capabilities. But the pair ("hello", "world!") is just a value, not a capability. Often capabilities are associated with effects. For instance, a file handle gives access to the effect of reading or writing it.

One can designate a value as a capability by making the type of the value extend directly or indirectly a standard trait Capability. For instance, a File can be declared to be a capability like this:

class File(path: String) extends ExclusiveCapability
//{
extension (file: File)
  def close(): Unit = ()
  def println(message: String): Unit = ()
//}

Here, ExclusiveCapability is a subtrait of Capability that prevents concurrent accesses.

Capability Tracking Copy Section

Capabilities in Scala 3 are tracked. This means that we record in a type which capabilities can be accessed by values of that type. We write A^{c} for the type of values of type A that can access the capability c.

For instance we can define a class Logger for sending log messages to a file and instantiate it like this:

class Logger(file: File)
//{
extension (logger: Logger^)
  def log(message: String): Unit = ()
//}

val out: File^ = new File("~/some/bits")
val lg: Logger^{out} = new Logger(out)

Note the type Logger^{out} of lg above. It indicates not only that lg is of class Logger but also that it can access file out. We also say lg captures out and call Logger^{out} a capturing type.

Generally, the type A^{c₁, ..., cₙ} stands for instances that retain capabilities c₁, ..., cₙ.
If class A does not extend Capability, then the type A alone stands for instances
that retain no capabilities, i.e. A is equivalent to A^{}. We also say A is pure.
The opposite of pure A describes instances of A that can retain arbitrary capabilities.
This type is A^{any}, or, shorter, A^.

Values of capturing types are themselves considered capabilities. For instance lg above is treated as a capability even though its class Logger does not extend Capability.

Capability sets induce a subtyping relation, where smaller sets lead to smaller types.
Furthermore, if c is of a capturing type A^{c₁, ..., cₙ} then we also have {c} <: {c₁, ..., cₙ}.
We say in this case that c refines the underlying capture set {c₁, ..., cₙ}.

For instance, if out and lg are capabilities as defined above and f is some other capability, we have

A  <:  A^{lg}  <:  A^{out}  <:  A^{out, f}  <:  A^

Function Types Copy Section

Function types can also be equipped with capability sets.
The function type A -> B is considered to be pure, so it cannot
retain any capability. We then use the following shorthands.

A ->{c₁, ..., cₙ} B   =  (A -> B)^{c₁, ..., cₙ}
                A => B   =  A ->{any} B

A function captures any capabilities accessed by its body. For instance the function

val next: Int ->{lg} Int = (x: Int) =>
  lg.log(s"called with parameter $x")
  x + 1

has type Int ->{lg} Int, which is a subtype of Int => Int.

Scala systematically distinguishes methods, which are members of classes and objects, from functions, which are objects themselves. Methods don't have expressible types and consequently don't have capability sets that can be tracked. Instead, the capability set is associated with the enclosing object. For instance, in

val exec: Runnable^{lg} = new Runnable:
  def run(): Unit = lg.log("called")

the value exec has type Runnable^{lg} since lg is accessed by Runnable's method run.
Methods can be converted to functions by just naming the method without passing any parameters (this is called eta expansion). For instance the value exec.run would have type () ->{lg} Unit.

Lifetimes Copy Section

One consequence of tracking capabilities in types is that we can control their lifetimes.
For instance, here is a function that runs an operation op while providing a logger to a fresh
file. After the operation is finished, the file is closed and the result of the operation is returned.
The function is generic: the result type of the operation is the type parameter T, which can be instantiated as needed.

def logged[T](op: Logger^ => T): T =
  val f = new File("logfile")
  val l: Logger^{f} = new Logger(f)
  val result = op(l)
  f.close()
  result

A problematic use of the function would leak the logger l in the result of the operation. For instance like this:

val bad = logged { l =>
  () => l.log("too late!")
}

Here, the result of the operation passed to logged is the nested function () => l.log("too late!"). This is also the value of bad. Hence, the call bad() would invoke l.log, but at this point the file underlying the logger was already closed by logged. Fortunately, the definition of bad is rejected in Scala 3's type system. Essentially, the type parameter T in the definition of logged must be independent of the identity of the logger passed to op. In the bad usage scenario, this requirement is violated since the result type of op has type () ->{l} Unit, so it does depend on the logger parameter in its capture set.

The fine grained control of lifetimes is one of the properties that set tracked capabilities apart from traditional untracked ones.

Implicit Capability Passing Copy Section

Capabilities like out or lg are objects with which a program interacts as usual. This aspect of object capabilities is one of their strengths since it leads to ergonomic notation. Capabilities are also often used to establish some kind of context that establishes permissions to execute some effects.

For instance, in the Gears framework for concurrent systems we have Async capabilities that allow a computation to suspend while waiting for an external event (and possibly be cancelled in the process). This is modeled by having the Async class extend a capability trait:

class Async extends SharedCapability
class Data

// A suspendable method using an Async capability
def readDataEventually(file: File)(using async: Async): Data = new Data

One common issue with traditional capabilities is that passing many capabilities as parameters to all the places that need them can get tedious quickly. In Scala this is much less of a problem since capabilities can be passed as implicit parameters via using clauses. For instance, the following method calls readDataEventually without having to pass the parameter async explicitly.

def processData(using Async): Data =
  val file = new File("~/some/path")
  readDataEventually(file)

Since the parameter is not mentioned, we also don't need a name for it in its definition. So the method above is a convenient shorthand for the following more explicit definition.

def processData(using async: Async): Data =
  val file = new File("~/some/path")
  readDataEventually(file)(using async)

Mutation Copy Section

Mutable variables and mutable data structures are also considered capabilities.
For instance, consider a method that creates a pair of functions for incrementing and reading a counter:

def counterOps =
  var counter: Int = 0
  val incr = () => counter += 1
  val current = () => counter
  (incr, current)

The function incr has type () ->{counter} Unit, where counter is the local variable defined in counterOps. This records the fact that the counter is updated when calling the function.

We distinguish read and write accesses to mutable data. A read access to a mutable data structure m charges a "fractional" read-only capability m.rd whereas a write access charges the full capability m. Separation checking ensures that targets to write accesses cannot be obscured through aliasing. This is analogous to borrow checking in Rust, but uses a different mechanism based on capabilities instead of regions.

Mutable data structures extend trait Mutable, which is another subtrait of Capability.
Methods that write to such data are marked with an update modifier. For instance, here is
a class for append-buffers:

abstract class Buffer[T] extends Mutable {
  update def append(elem: T): Unit
  def apply(pos: Int): T
  def size: Int
}

The append method comes with an update modifier since it changes the contents of the Buffer.
By contrast, apply and size are regular methods that are guaranteed update-free.

Types are used to regulate calls to update methods. A reference of type Buffer only allows access to regular methods. If the reference has type Buffer^ it also allows access to update methods.

For instance, a copy method between buffers could be written like this:

def copy[T](from: Buffer[T], to: Buffer[T]^): Unit =
  for i <- 0 until from.size do
    to.append(from(i))

The type of the Buffer arguments makes it clear which buffer is modified and which buffer is read-only. Note that the distinction between C and C^ applies to all types C extending trait Mutable. For other capability types the two forms are equivalent.

Global Capabilities Copy Section

In traditional object capability systems, global capabilities are ruled out. Indeed, if we rely on controlling accesses simply by scoping rules, global capabilities don't make much sense since they allow unrestricted access everywhere.

But with tracked capabilities, we have another means to control access via tracked types. Consequently global capabilities can be allowed. For instance,
here is a Console object:

class File(path: String) extends SharedCapability
extension (file: File)
  def println(message: String): Unit = ()

object Console extends SharedCapability:
  val in: File = new File("stdin")
  val out: File = new File("stdout")

Here, in, and out are of type File, so Console.in, and Console.out are global capabilities. A function () => Console.out.println("hi") would have type
() ->{Console.out} Unit. It could not be passed into a context expecting a pure function. A global object that refers to Console needs to declare that dependency in a uses clause.

object SimpleLogger uses Console:
  def log(str: String): Unit = Console.out.println(str)

Allowing global capabilities like Console.out is quite useful since it means that we don't need to fundamentally change a system's architecture to make it capability-safe. In traditional capability systems all capabilities provided by the host system have to be passed as parameters into the main entry point and from there to all functions that need access. This usually requires a global refactoring of the code base and can lead to more complex code.

Summary Copy Section

Scala 3's capabilities are both more convenient and more expressive than traditional ones. They are more convenient since using clauses allow to pass capabilities implicitly down a call chain and global capabilities reduce the need for such call chains in the first place. And they are more expressive, since tracked capabilities allow to describe and constrain the effects of computations. Furthermore, one can distinguish read-only and update capabilities and one can ensure that updates are only to unshared references.

Sidebar.Nightly.Template.Yml (`docs/sidebar.nightly.template.yml`) Copy Section

index: index.md
subsection:

• title: Reference
  directory: docs/reference

  Embed sidebar.reference.yml, performed by `generateScalaDocumentation` sbt task

• title: Contributing
  directory: docs/contributing
  index: contributing/index.md
  subsection:
  • page: contributing/getting-started.md
  • page: contributing/setting-up-your-ide.md
  • index: contributing/issues/diagnosing-your-issue.md
    subsection:
    • page: contributing/issues/reproduce.md
    • page: contributing/issues/cause.md
    • page: contributing/issues/areas.md
  • index: contributing/debugging/debugging.md
    directory: debugging
    subsection:
    • page: contributing/debugging/ide-debugging.md
    • page: contributing/debugging/inspection.md
    • page: contributing/debugging/other-debugging.md
  • page: contributing/testing.md
  • page: contributing/scaladoc.md
  • page: contributing/community-build.md
  • page: contributing/sending-in-a-pr.md
  • page: contributing/cheatsheet.md
  • title: Procedures
    directory: procedures
    index: contributing/procedures/index.md
    subsection:
    • page: contributing/procedures/release.md
    • page: contributing/procedures/vulpix.md
    • page: contributing/procedures/contributing-to-stdlib.md
  • title: High Level Architecture
    directory: architecture
    index: contributing/architecture/index.md
    subsection:
    • page: contributing/architecture/lifecycle.md
    • page: contributing/architecture/context.md
    • page: contributing/architecture/phases.md
    • page: contributing/architecture/types.md
    • page: contributing/architecture/time.md
    • page: contributing/architecture/symbols.md
• title: Internals
  directory: docs/internals
  index: internals/index.md
  subsection:
  • page: internals/backend.md
  • page: internals/classpaths.md
  • page: internals/contexts.md
  • page: internals/dotc-scalac.md
  • page: internals/higher-kinded-v2.md
  • page: internals/overall-structure.md
  • page: internals/explicit-nulls.md
  • page: internals/periods.md
  • page: internals/syntax.md
  • page: internals/type-system.md
  • page: internals/dotty-internals-1-notes.md
  • page: internals/debug-macros.md
  • page: internals/gadts.md
  • page: internals/coverage.md
  • page: internals/best-effort-compilation.md
  • page: internals/syntax-3.1.md
• page: release-notes-0.1.2.md # Referenced from https://www.scala-lang.org/blog/2017/05/31/first-dotty-milestone-release.html
  hidden: true

Sidebar.Yml (`docs/sidebar.yml`) Copy Section

index: reference/overview.md
subsection:

• title: New Types
  index: reference/new-types/new-types.md
  subsection:
  • page: reference/new-types/intersection-types.md
  • page: reference/new-types/intersection-types-spec.md
    hidden: true
  • page: reference/new-types/union-types.md
  • page: reference/new-types/union-types-spec.md
    hidden: true
  • page: reference/new-types/type-lambdas.md
  • page: reference/new-types/type-lambdas-spec.md
    hidden: true
  • page: reference/new-types/match-types.md
  • page: reference/new-types/dependent-function-types.md
  • page: reference/new-types/dependent-function-types-spec.md
    hidden: true
  • page: reference/new-types/polymorphic-function-types.md
• title: Enums
  index: reference/enums/enums-index.md
  subsection:
  • page: reference/enums/enums.md
  • page: reference/enums/adts.md
  • page: reference/enums/desugarEnums.md
• title: Contextual Abstractions
  index: reference/contextual/contextual.md
  directory: contextual
  subsection:
  • page: reference/contextual/givens.md
  • page: reference/contextual/using-clauses.md
  • page: reference/contextual/context-bounds.md
  • page: reference/contextual/deferred-givens.md
  • page: reference/contextual/given-imports.md
  • page: reference/contextual/more-givens.md
  • page: reference/contextual/previous-givens.md
    hidden: true
  • page: reference/contextual/extension-methods.md
  • page: reference/contextual/right-associative-extension-methods.md
  • page: reference/contextual/type-classes.md
  • page: reference/contextual/derivation.md
  • page: reference/contextual/derivation-macro.md
  • page: reference/contextual/multiversal-equality.md
  • page: reference/contextual/context-functions.md
  • page: reference/contextual/context-functions-spec.md
    hidden: true
  • page: reference/contextual/conversions.md
  • page: reference/contextual/by-name-context-parameters.md
  • page: reference/contextual/relationship-implicits.md
• title: Metaprogramming
  index: reference/metaprogramming/metaprogramming.md
  subsection:
  • page: reference/metaprogramming/inline.md
  • page: reference/metaprogramming/compiletime-ops.md
  • page: reference/metaprogramming/macros.md
  • page: reference/metaprogramming/macros-spec.md
    hidden: true
  • page: reference/metaprogramming/simple-smp.md # description of a simplified metaprogramming language, this might not be the best place for it
  • page: reference/metaprogramming/staging.md
  • page: reference/metaprogramming/reflection.md
  • page: reference/metaprogramming/tasty-inspect.md
• title: Other New Features
  index: reference/other-new-features/other-new-features.md
  subsection:
  • page: reference/other-new-features/trait-parameters.md
  • page: reference/other-new-features/transparent-traits.md
  • page: reference/other-new-features/creator-applications.md
  • page: reference/other-new-features/export.md
  • page: reference/other-new-features/opaques.md
  • page: reference/other-new-features/opaques-details.md
  • page: reference/other-new-features/named-tuples.md
  • page: reference/other-new-features/open-classes.md
  • page: reference/other-new-features/parameter-untupling.md
  • page: reference/other-new-features/parameter-untupling-spec.md
    hidden: true
  • page: reference/other-new-features/generalized-method-syntax.md
  • page: reference/other-new-features/kind-polymorphism.md
  • page: reference/other-new-features/matchable.md
  • page: reference/other-new-features/threadUnsafe-annotation.md
  • page: reference/other-new-features/targetName.md
  • page: reference/other-new-features/control-syntax.md
  • page: reference/other-new-features/indentation.md
  • page: reference/other-new-features/safe-initialization.md
  • page: reference/other-new-features/type-test.md
  • page: reference/other-new-features/experimental-defs.md
  • page: reference/other-new-features/preview-defs.md
  • page: reference/other-new-features/binary-literals.md
  • page: reference/other-new-features/toplevel-definitions.md
  • page: reference/other-new-features/better-fors.md
  • page: reference/other-new-features/runtimeChecked.md
  • page: reference/other-new-features/into.md
• title: Other Changed Features
  directory: changed-features
  index: reference/changed-features/changed-features.md
  subsection:
  • page: reference/changed-features/numeric-literals.md
  • page: reference/changed-features/structural-types.md
  • page: reference/changed-features/structural-types-spec.md
    hidden: true
  • page: reference/changed-features/operators.md
  • page: reference/changed-features/wildcards.md
  • page: reference/changed-features/imports.md
  • page: reference/changed-features/type-inference.md
  • page: reference/changed-features/implicit-resolution.md
  • page: reference/changed-features/implicit-conversions.md
  • page: reference/changed-features/implicit-conversions-spec.md
    hidden: true
  • page: reference/changed-features/overload-resolution.md
  • page: reference/changed-features/match-syntax.md
  • page: reference/changed-features/vararg-splices.md
  • page: reference/changed-features/pattern-bindings.md
  • page: reference/changed-features/pattern-matching.md
  • page: reference/changed-features/eta-expansion.md
  • page: reference/changed-features/eta-expansion-spec.md
    hidden: true
  • page: reference/changed-features/compiler-plugins.md
  • page: reference/changed-features/lazy-vals-init.md
  • page: reference/changed-features/main-functions.md
  • page: reference/changed-features/interpolation-escapes.md
• title: Dropped Features
  index: reference/dropped-features/dropped-features.md
  subsection:
  • page: reference/dropped-features/delayed-init.md
  • page: reference/dropped-features/macros.md
  • page: reference/dropped-features/existential-types.md
  • page: reference/dropped-features/type-projection.md
  • page: reference/dropped-features/do-while.md
  • page: reference/dropped-features/procedure-syntax.md
  • page: reference/dropped-features/package-objects.md
  • page: reference/dropped-features/early-initializers.md
  • page: reference/dropped-features/class-shadowing.md
  • page: reference/dropped-features/class-shadowing-spec.md
    hidden: true
  • page: reference/dropped-features/limit22.md
  • page: reference/dropped-features/xml.md
  • page: reference/dropped-features/symlits.md
  • page: reference/dropped-features/auto-apply.md
  • page: reference/dropped-features/weak-conformance.md
  • page: reference/dropped-features/weak-conformance-spec.md
    hidden: true
  • page: reference/dropped-features/nonlocal-returns.md
  • page: reference/dropped-features/this-qualifier.md
  • page: reference/dropped-features/wildcard-init.md
• title: Preview Features
  directory: preview
  index: reference/preview/overview.md
  subsection:
  • page: reference/preview/unrolled-defs.md
  • page: reference/preview/relaxed-lambdas.md
  • page: reference/preview/package-object-values.md
• title: Experimental Features
  directory: experimental
  index: reference/experimental/overview.md
  subsection:
  • page: reference/experimental/better-fors.md
    hidden: true
  • page: reference/experimental/fewer-braces.md
    hidden: true
  • page: reference/experimental/generalized-method-syntax.md
    hidden: true
  • page: reference/experimental/named-tuples.md
    hidden: true
  • page: reference/experimental/canthrow.md
  • page: reference/experimental/erased-defs.md
  • page: reference/experimental/erased-defs-spec.md
    hidden: true
  • page: reference/experimental/named-typeargs.md
  • page: reference/experimental/named-typeargs-spec.md
    hidden: true
  • page: reference/experimental/numeric-literals.md
  • page: reference/experimental/explicit-nulls.md
  • page: reference/experimental/main-annotation.md
  • title: Capture Checking
    index: reference/experimental/capture-checking/cc.md
    subsection:
    • page: reference/experimental/capture-checking/overview.md
    • page: reference/experimental/capture-checking/basics.md
    • page: reference/experimental/capture-checking/classes.md
    • page: reference/experimental/capture-checking/polymorphism.md
    • page: reference/experimental/capture-checking/advanced.md
      hidden: true
    • page: reference/experimental/capture-checking/scoped-capabilities.md
    • page: reference/experimental/capture-checking/classifiers.md
    • page: reference/experimental/capture-checking/checked-exceptions.md
    • page: reference/experimental/capture-checking/mutability.md
    • page: reference/experimental/capture-checking/separation-checking.md
    • page: reference/experimental/capture-checking/safe.md
    • page: reference/experimental/capture-checking/how-to-use.md
    • page: reference/experimental/capture-checking/internals.md
  • page: reference/experimental/purefuns.md
  • page: reference/experimental/tupled-function.md
  • page: reference/experimental/modularity.md
  • page: reference/experimental/typeclasses.md
  • page: reference/experimental/runtimeChecked.md
    hidden: true
  • page: reference/experimental/quoted-patterns-with-polymorphic-functions.md
  • page: reference/experimental/sub-cases.md
  • page: reference/experimental/dedented-string-literals.md
  • page: reference/experimental/spec-strings.md
  • page: reference/experimental/inline-traits.md
  • page: reference/experimental/specialized-traits.md
  • page: reference/experimental/method-block-end-markers.md
• page: reference/syntax.md
• title: Language Versions
  index: reference/language-versions/language-versions.md
  subsection:
  • page: reference/language-versions/source-compatibility.md
  • page: reference/language-versions/binary-compatibility.md
• page: reference/soft-modifier.md
• page: reference/features-classification.md
• title: Error Codes
  index: reference/error-codes/error-codes.md
  subsection:
  • page: reference/error-codes/E001.md
  • page: reference/error-codes/E002.md
  • page: reference/error-codes/E003.md
  • page: reference/error-codes/E004.md
  • page: reference/error-codes/E005.md
  • page: reference/error-codes/E006.md
  • page: reference/error-codes/E007.md
  • page: reference/error-codes/E008.md
  • page: reference/error-codes/E009.md
  • page: reference/error-codes/E010.md
  • page: reference/error-codes/E011.md
  • page: reference/error-codes/E012.md
  • page: reference/error-codes/E013.md
  • page: reference/error-codes/E014.md
  • page: reference/error-codes/E015.md
  • page: reference/error-codes/E016.md
  • page: reference/error-codes/E017.md
  • page: reference/error-codes/E018.md
  • page: reference/error-codes/E019.md
  • page: reference/error-codes/E020.md
  • page: reference/error-codes/E021.md
  • page: reference/error-codes/E022.md
  • page: reference/error-codes/E023.md
  • page: reference/error-codes/E024.md
  • page: reference/error-codes/E025.md
  • page: reference/error-codes/E026.md
  • page: reference/error-codes/E027.md
  • page: reference/error-codes/E028.md
  • page: reference/error-codes/E029.md
  • page: reference/error-codes/E030.md
  • page: reference/error-codes/E031.md
  • page: reference/error-codes/E032.md
  • page: reference/error-codes/E033.md
  • page: reference/error-codes/E034.md
  • page: reference/error-codes/E035.md
  • page: reference/error-codes/E036.md
  • page: reference/error-codes/E037.md
  • page: reference/error-codes/E038.md
  • page: reference/error-codes/E039.md
  • page: reference/error-codes/E040.md
  • page: reference/error-codes/E041.md
  • page: reference/error-codes/E042.md
  • page: reference/error-codes/E043.md
  • page: reference/error-codes/E044.md
  • page: reference/error-codes/E045.md
  • page: reference/error-codes/E046.md
  • page: reference/error-codes/E047.md
  • page: reference/error-codes/E048.md
  • page: reference/error-codes/E049.md
  • page: reference/error-codes/E050.md
  • page: reference/error-codes/E051.md
  • page: reference/error-codes/E052.md
  • page: reference/error-codes/E053.md
  • page: reference/error-codes/E054.md
  • page: reference/error-codes/E055.md
  • page: reference/error-codes/E056.md
  • page: reference/error-codes/E057.md
  • page: reference/error-codes/E058.md
  • page: reference/error-codes/E059.md
  • page: reference/error-codes/E060.md
  • page: reference/error-codes/E061.md
  • page: reference/error-codes/E062.md
  • page: reference/error-codes/E063.md
  • page: reference/error-codes/E064.md
  • page: reference/error-codes/E065.md
  • page: reference/error-codes/E066.md
  • page: reference/error-codes/E067.md
  • page: reference/error-codes/E068.md
  • page: reference/error-codes/E069.md
  • page: reference/error-codes/E070.md
  • page: reference/error-codes/E071.md
  • page: reference/error-codes/E072.md
  • page: reference/error-codes/E073.md
  • page: reference/error-codes/E074.md
  • page: reference/error-codes/E075.md
  • page: reference/error-codes/E076.md
  • page: reference/error-codes/E077.md
  • page: reference/error-codes/E078.md
  • page: reference/error-codes/E079.md
  • page: reference/error-codes/E080.md
  • page: reference/error-codes/E081.md
  • page: reference/error-codes/E082.md
  • page: reference/error-codes/E083.md
  • page: reference/error-codes/E084.md
  • page: reference/error-codes/E085.md
  • page: reference/error-codes/E086.md
  • page: reference/error-codes/E087.md
  • page: reference/error-codes/E088.md
  • page: reference/error-codes/E089.md
  • page: reference/error-codes/E090.md
  • page: reference/error-codes/E091.md
  • page: reference/error-codes/E092.md
  • page: reference/error-codes/E093.md
  • page: reference/error-codes/E094.md
  • page: reference/error-codes/E095.md
  • page: reference/error-codes/E096.md
  • page: reference/error-codes/E097.md
  • page: reference/error-codes/E098.md
  • page: reference/error-codes/E099.md
  • page: reference/error-codes/E100.md
  • page: reference/error-codes/E101.md
  • page: reference/error-codes/E102.md
  • page: reference/error-codes/E103.md
  • page: reference/error-codes/E104.md
  • page: reference/error-codes/E105.md
  • page: reference/error-codes/E106.md
  • page: reference/error-codes/E107.md
  • page: reference/error-codes/E108.md
  • page: reference/error-codes/E109.md
  • page: reference/error-codes/E110.md
  • page: reference/error-codes/E111.md
  • page: reference/error-codes/E112.md
  • page: reference/error-codes/E113.md
  • page: reference/error-codes/E114.md
  • page: reference/error-codes/E115.md
  • page: reference/error-codes/E116.md
  • page: reference/error-codes/E117.md
  • page: reference/error-codes/E118.md
  • page: reference/error-codes/E119.md
  • page: reference/error-codes/E120.md
  • page: reference/error-codes/E121.md
  • page: reference/error-codes/E122.md
  • page: reference/error-codes/E123.md
  • page: reference/error-codes/E124.md
  • page: reference/error-codes/E125.md
  • page: reference/error-codes/E126.md
  • page: reference/error-codes/E127.md
  • page: reference/error-codes/E128.md
  • page: reference/error-codes/E129.md
  • page: reference/error-codes/E130.md
  • page: reference/error-codes/E131.md
  • page: reference/error-codes/E132.md
  • page: reference/error-codes/E133.md
  • page: reference/error-codes/E134.md
  • page: reference/error-codes/E135.md
  • page: reference/error-codes/E136.md
  • page: reference/error-codes/E137.md
  • page: reference/error-codes/E138.md
  • page: reference/error-codes/E139.md
  • page: reference/error-codes/E140.md
  • page: reference/error-codes/E141.md
  • page: reference/error-codes/E142.md
  • page: reference/error-codes/E143.md
  • page: reference/error-codes/E144.md
  • page: reference/error-codes/E145.md
  • page: reference/error-codes/E146.md
  • page: reference/error-codes/E147.md
  • page: reference/error-codes/E148.md
  • page: reference/error-codes/E149.md
  • page: reference/error-codes/E150.md
  • page: reference/error-codes/E151.md
  • page: reference/error-codes/E152.md
  • page: reference/error-codes/E153.md
  • page: reference/error-codes/E154.md
  • page: reference/error-codes/E155.md
  • page: reference/error-codes/E156.md
  • page: reference/error-codes/E157.md
  • page: reference/error-codes/E158.md
  • page: reference/error-codes/E159.md
  • page: reference/error-codes/E160.md
  • page: reference/error-codes/E161.md
  • page: reference/error-codes/E162.md
  • page: reference/error-codes/E163.md
  • page: reference/error-codes/E164.md
  • page: reference/error-codes/E165.md
  • page: reference/error-codes/E166.md
  • page: reference/error-codes/E167.md
  • page: reference/error-codes/E168.md
  • page: reference/error-codes/E169.md
  • page: reference/error-codes/E170.md
  • page: reference/error-codes/E171.md
  • page: reference/error-codes/E172.md
  • page: reference/error-codes/E173.md
  • page: reference/error-codes/E174.md
  • page: reference/error-codes/E175.md
  • page: reference/error-codes/E176.md
  • page: reference/error-codes/E177.md
  • page: reference/error-codes/E178.md
  • page: reference/error-codes/E179.md
  • page: reference/error-codes/E180.md
  • page: reference/error-codes/E181.md
  • page: reference/error-codes/E182.md
  • page: reference/error-codes/E183.md
  • page: reference/error-codes/E184.md
  • page: reference/error-codes/E185.md
  • page: reference/error-codes/E186.md
  • page: reference/error-codes/E187.md
  • page: reference/error-codes/E188.md
  • page: reference/error-codes/E189.md
  • page: reference/error-codes/E190.md
  • page: reference/error-codes/E191.md
  • page: reference/error-codes/E192.md
  • page: reference/error-codes/E193.md
  • page: reference/error-codes/E194.md
  • page: reference/error-codes/E195.md
  • page: reference/error-codes/E196.md
  • page: reference/error-codes/E197.md
  • page: reference/error-codes/E198.md
  • page: reference/error-codes/E199.md
  • page: reference/error-codes/E200.md
  • page: reference/error-codes/E201.md
  • page: reference/error-codes/E202.md
  • page: reference/error-codes/E203.md
  • page: reference/error-codes/E204.md
  • page: reference/error-codes/E205.md
  • page: reference/error-codes/E206.md
  • page: reference/error-codes/E207.md
  • page: reference/error-codes/E208.md
  • page: reference/error-codes/E209.md
  • page: reference/error-codes/E210.md
  • page: reference/error-codes/E211.md
  • page: reference/error-codes/E212.md
  • page: reference/error-codes/E213.md
  • page: reference/error-codes/E214.md
  • page: reference/error-codes/E215.md
  • page: reference/error-codes/E216.md
  • page: reference/error-codes/E217.md
  • page: reference/error-codes/E218.md
  • page: reference/error-codes/E219.md
  • page: reference/error-codes/E220.md
  • page: reference/error-codes/E221.md
  • page: reference/error-codes/E222.md
  • page: reference/error-codes/E223.md
  • page: reference/error-codes/E224.md
  • page: reference/error-codes/E225.md
  • page: reference/error-codes/E226.md
  • page: reference/error-codes/E227.md
  • page: reference/error-codes/E228.md
  • page: reference/error-codes/E229.md
  • page: reference/error-codes/E230.md
  • page: reference/error-codes/E231.md
  • page: reference/error-codes/E232.md
  • page: reference/error-codes/E233.md
  • page: reference/error-codes/E234.md
  • page: reference/error-codes/E235.md

Docs Release Notes 0.1.2 (`docs/_docs/release-notes-0.1.2.md`) Copy Section

layout: doc-page title: 0.1.2 release notes redirectFrom: /docs/release-notes/0.1.2.html Copy Chapter

0.1.2 will be the first public release of Dotty.
Being the first one, these notes are incomplete.
This document is a work in progress until 0.1.2-final is released.
These notes are up-to-date based on 0.1.2-RC1 and will be updated
with changes that happen during the RC stabilization cycle.

Required Java Version

Dotty 0.1.2 targets Java 8. We don't have plans to add support for earlier versions of Java.

IDE support for Dotty

Reporting Bugs / Known Issues

Please file any bugs you encounter. If you’re unsure whether something is a bug,
please ask on the Dotty gitter channel.

Dotty Doc

Dotty has added support for Dotty Doc.
Actually, the dotty documentation site https://nightly.scala-lang.org/docs/ is generated by it.
Looks nice, doesn’t it?

#Other implemented features:

This release ships with the following features:

• TASTY support by @odersky, @xeno-by and @darkdimius 1
• HK-types support by @odersky, @smarter and @darkdimius 2
• Intersection and Union Types by @odersky 3 4
• Enumerations by @odersky 4 5 6
• Implicit By-Name Parameters by @odersky 7
• Miniphases-based design by @darkdimius, @odersky and @olhotak 8
• @static methods support by [@darkdmius] 9
• Non-blocking lazy vals by @darkdimius 10
• JVM code emission by @magarciaEPFL and @darkdimius 11
• Efficient multi-dimensional array allocation by @darkdimius 12
• Default-method based trait composition @odersky and @darkdimius 13 14
• Trait parameters by @odersky 15
• Working contravariant implicits by @odersky 16
• Option-less pattern matching by @odersky, @darkdimius and @OlivierBlanvillain 17
• SAM-based anonymous functions by @magarciaEPFL, @darkdimius and @retronym 18
• Pattern matching support by @darkdimius 19
• Value classes support by @smarter and @darkdimius 20
• Pattern matching exhaustivity checks by @liufengyun 21
• Tailrec optimization by @darkdimius 22 23
• Language server protocol implementation by @smarter 24
• VS code plugin by @smarter 24
• Vulpix: new test-suite driver by @felixmulder that replaces partest by @vsalvis 25
• Java parser by @olhotak 26
• Local optimizations(-optimise) by @darkdimius and @OlivierBlanvillain 27
• sbt support by @smarter 28
• DottyDoc by @felixmulder 29
• Implicit Function Types by @odersky 30
• Phantom Types by @nicolasstucki 31
• Functions with more than 22 parameters by @odersky 32
• Inline keyword by @odersky 33

Contributors

The Dotty team and contributors have closed 750 issues and have merged a total of 1258 pull requests.

Concretely, according to

git ls-tree -r -z --name-only HEAD -- |egrep -z -Z -E '\.(scala)$'| xargs -0 -n1 git blame --line-porcelain |grep "^author "|sort|uniq -c|sort -nr

71 people contributed code, tests, and/or documentation to Dotty 0.1.2-RC1.
The following people have contributed to this release:

Spec 01 Lexical Syntax (`docs/_spec/01-lexical-syntax.md`) Copy Section

title: Lexical Syntax layout: default chapter: 1 Copy Chapter

Lexical Syntax

Scala source code consists of Unicode text.

The program text is tokenized as described in this chapter.
See the last section for special support for XML literals, which are parsed in XML mode.

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

1. Whitespace characters. \u0020 | \u0009 | \u000D | \u000A.
2. Letters, which include lower case letters (Ll), upper case letters (Lu), title case letters (Lt), other letters (Lo), modifier letters (Lm), letter numerals (Nl) and the two characters \u0024 ‘$’ and \u005F ‘_’.
3. Digits ‘0’ | ... | ‘9’.
4. Parentheses ‘(’ | ‘)’ | ‘[’ | ‘]’ | ‘{’ | ‘}’ .
5. Delimiter characters ‘`’ | ‘'’ | ‘"’ | ‘.’ | ‘;’ | ‘,’ .
6. Operator characters. These consist of all printable ASCII characters (\u0020 - \u007E) that are in none of the sets above, mathematical symbols (Sm) and other symbols (So).

Optional Braces Copy Chapter

The principle of optional braces is that any keyword that can be followed by { can also be followed by an indented block, without needing an intervening :.
(Allowing an optional : would be counterproductive since it would introduce several ways to do the same thing.)

The lexical analyzer inserts indent and outdent tokens that represent regions of indented code at certain points.

In the context-free productions below we use the notation <<< ts >>> 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 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 a colon token.

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 is an alphanumeric identifier, a backticked identifier, or one of the tokens this, super, new, ")", and "]".

colon         ::=  ':'    -- with side conditions explained above
 <<< ts >>>   ::=  ‘{’ ts ‘}’
                |  indent ts outdent
:<<< ts >>>   ::=  [nl] ‘{’ ts ‘}’
                |  colon indent ts outdent

Identifiers Copy Chapter

op            ::=  opchar {opchar}
varid         ::=  lower idrest
boundvarid    ::=  varid
                | ‘`’ varid ‘`’
alphaid       ::=  upper idrest
                |  varid
plainid       ::=  alphaid
                |  op
id            ::=  plainid
                |  ‘`’ { charNoBackQuoteOrNewline | escapeSeq } ‘`’
idrest        ::=  {letter | digit} [‘_’ op]
escapeSeq     ::= UnicodeEscape | charEscapeSeq
UnicodeEscape ::= ‘\’ ‘u’ {‘u’} hexDigit hexDigit hexDigit hexDigit
hexDigit      ::= ‘0’ | ... | ‘9’ | ‘A’ | ... | ‘F’ | ‘a’ | ... | ‘f’

There are three ways to form an identifier.
First, an identifier can start with a letter, followed by an arbitrary sequence of letters and digits.
This may be followed by underscore ‘_‘ characters and another string composed of either letters and digits or of operator characters.
Second, an identifier can start with an operator character followed by an arbitrary sequence of operator characters.
The preceding two forms are called plain identifiers.
Finally, an identifier may also be formed by an arbitrary string between backquotes (host systems may impose some restrictions on which strings are legal for identifiers).
The identifier then is composed of all characters excluding the backquotes themselves.

As usual, the longest match rule applies.
For instance, the string

big_bob++=`def`

decomposes into the three identifiers big_bob, ++=, and
def.

The rules for pattern matching further distinguish between variable identifiers, which start with a lower case letter or _, and constant identifiers, which do not.

For this purpose, lower case letters include not only a-z, but also all characters in Unicode category Ll (lowercase letter), as well as all letters that have contributory property Other_Lowercase, except characters in category Nl (letter numerals), which are never taken as lower case.

The following are examples of variable identifiers:

text Copy

x         maxIndex   p2p   empty_?
    `yield`   αρετη      _y    dot_product_*
    __system  _MAX_LEN_
    ªpple     ʰelper

Some examples of constant identifiers are

text Copy

+    Object  $reserved  Džul    ǂnûm
    ⅰ_ⅲ  Ⅰ_Ⅲ     ↁelerious  ǃqhàà  ʹthatsaletter

The ‘$’ character is reserved for compiler-synthesized identifiers.
User programs should not define identifiers that contain ‘$’ characters.

Regular keywords Copy Section

The following names are reserved words instead of being members of the syntactic class id of lexical identifiers.

abstract  case      catch     class     def       do        else
enum      export    extends   false     final     finally   for
given     if        implicit  import    lazy      match     new
null      object    override  package   private   protected return
sealed    super     then      throw     trait     true      try
type      val       var       while     with      yield
:         =         <-        =>        <:        >:        #
@         =>>       ?=>

Soft keywords Copy Section

Additionally, the following soft keywords are reserved only in some situations.

as      derives      end      extension   infix   inline   opaque
open    transparent  using
|       *            +        -

A soft modifier is one of the identifiers infix, inline, opaque, open and transparent.

A soft keyword is a soft modifier, or one of as, derives, end, extension, using, |, +, -, *.

A soft modifier is treated as an actual modifier of a definition if it is followed by a hard modifier or a keyword combination starting a definition (def, val, var, type, given, class, trait, object, enum, case class, case object).
Between the two words, there may be a sequence of newline tokens and/or other soft modifiers.

Otherwise, soft keywords are treated as actual keywords in the following situations:

• as, if it appears in a renaming import clause.
• derives, if it appears after an extension clause or after the name and possibly parameters of a class, trait, object, or enum definition.
• end, if it appears at the start of a line following a statement (i.e. definition or toplevel expression) and is followed on the same line by a single non-comment token that is:
  • one of the keywords for, given, if, match, new, this, throw, try, val, while, extension or
  • an identifier.
• extension, if it appears at the start of a statement and is followed by ( or [.
• inline, if it is followed by any token that can start an expression.
• using, if it appears at the start of a parameter or argument list.
• |, if it separates two patterns in an alternative.
• +, -, if they appear in front of a type parameter.
• *, if it appears in a wildcard import, or if it follows the type of a parameter, or if it appears in a vararg splice x*.

Everywhere else, a soft keyword is treated as a normal identifier.

When one needs to access Java identifiers that are reserved words in Scala, use backquote-enclosed strings.
For instance, the statement Thread.yield() is illegal, since yield is a reserved word in Scala.
However, here's a work-around: Thread.`yield`()

Newline Characters Copy Chapter

semi ::= ‘;’ |  nl {nl}

Scala is a line-oriented language where statements may be terminated by semi-colons or newlines.
A newline in a Scala source text is treated as the special token “nl” if the three following criteria are satisfied:

1. The token immediately preceding the newline can terminate a statement.
2. The token immediately following the newline can begin a statement and is not a leading infix operator.
3. The token appears in a region where newlines are enabled.

The tokens that can terminate a statement are: literals, identifiers and the following delimiters and reserved words:

this    null    true    false    return    type    given    <xml-start>
_       )       ]       }        outdent

The tokens that can begin a statement are all Scala tokens except the following delimiters and reserved words:

catch    do      else    extends    finally    forSome    macro
match    then    with    yield
,    .    ;    :    =    =>    <-    <:    <%    >:    #    =>>    ?=>
)    ]    }    outdent

A leading infix operator is a symbolic identifier such as +, or approx_==, or an identifier in backticks that:

• starts a new line, and
• is not following a blank line, and
• is followed by at least one whitespace character (including new lines) and a token that can start an expression.

Furthermore, if the operator appears on its own line, the next line must have at least the same indentation width as the operator.

Newlines are enabled in:

1. all of a Scala source file, except for nested regions where newlines are disabled, and
2. the interval between matching { and } brace tokens, except for nested regions where newlines are disabled.

Newlines are disabled in:

1. the interval between matching ( and ) parenthesis tokens, except for nested regions where newlines are enabled, and
2. the interval between matching [ and ] bracket tokens, except for nested regions where newlines are enabled.
3. The interval between a case token and its matching => token, except for nested regions where newlines are enabled.
4. Any regions analyzed in XML mode.

Note that the brace characters of {...} escapes in XML and string literals are not tokens, and therefore do not enclose a region where newlines are enabled.

Normally, only a single nl token is inserted between two consecutive non-newline tokens which are on different lines, even if there are multiple lines between the two tokens.
However, if two tokens are separated by at least one completely blank line (i.e a line which contains no printable characters), then two nl tokens are inserted.

The Scala grammar (given in full here) contains productions where optional nl tokens, but not semicolons, are accepted.
This has the effect that a new line in one of these positions does not terminate an expression or statement.
These positions can be summarized as follows:

Multiple newline tokens are accepted in the following places (note that a semicolon in place of the newline would be illegal in every one of these cases):

• between the condition of a conditional expression or while loop and the next following expression,
• between the enumerators of a for-comprehension and the next following expression, and
• after the initial type keyword in a type definition.

A single new line token is accepted

• in front of an opening brace ‘{’, if that brace is a legal continuation of the current statement or expression,
• after an infix operator, if the first token on the next line can start an expression,
• in front of a parameter clause, and
• after an annotation.

The newline tokens between the two lines are not treated as statement separators.

scala Copy

if (x > 0)
  x = x - 1

while (x > 0)
  x = x / 2

for (x <- 1 to 10)
  println(x)

type
  IntList = List[Int]

scala Copy

new Iterator[Int]
{
  private var x = 0
  def hasNext = true
  def next = { x += 1; x }
}

With an additional newline character, the same code is interpreted as an object creation followed by a local block:

scala Copy

new Iterator[Int]

{
  private var x = 0
  def hasNext = true
  def next = { x += 1; x }
}

scala Copy

x < 0 ||
  x > 10

With an additional newline character, the same code is interpreted as two expressions:

scala Copy

x < 0 ||

  x > 10

scala Copy

def func(x: Int)
        (y: Int) = x + y

With an additional newline character, the same code is interpreted as an abstract method definition and a syntactically illegal statement:

scala Copy

def func(x: Int)

        (y: Int) = x + y

scala Copy

@serializable
protected class Data { ... }

With an additional newline character, the same code is interpreted as an attribute and a separate statement (which is syntactically illegal).

scala Copy

@serializable

protected class Data { ... }

Literals Copy Chapter

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

Literal  ::=  [‘-’] integerLiteral
           |  [‘-’] floatingPointLiteral
           |  booleanLiteral
           |  characterLiteral
           |  stringLiteral
           |  interpolatedString
           |  ‘null’

Integer Literals Copy Section

integerLiteral   ::=  (decimalNumeral | hexNumeral | binaryNumeral) [‘L’ | ‘l’]
decimalNumeral   ::=  ‘0’ | digit [{digit | ‘_’} digit]
hexNumeral       ::=  ‘0’ (‘x’ | ‘X’) hexDigit [{hexDigit | ‘_’} hexDigit]
binaryNumeral    ::=  ‘0’ (‘b’ | ‘B’) binaryDigit [{binaryDigit | ‘_’} binaryDigit]

Values of type Int are all integer numbers between $-2^{31}$ and $2^{31}-1$, inclusive.
Values of type Long are all integer numbers between $-2^{63}$ and
$2^{63}-1$, inclusive.
A compile-time error occurs if an integer literal denotes a number outside these ranges.

Integer literals are usually of type Int, or of type Long when followed by a L or l suffix.
(Lowercase l is deprecated for reasons of legibility.)

However, if the expected type pt of a literal in an expression is either Byte, Short, or Char and the integer number fits in the numeric range defined by the type, then the number is converted to type pt and the literal's type is pt.
The numeric ranges given by these types are:

The digits of a numeric literal may be separated by arbitrarily many underscores for purposes of legibility.

scala Copy

0           21_000      0x7F        -42L        0xFFFF_FFFF        0b0100_0010

Floating Point Literals Copy Section

floatingPointLiteral  ::=  [decimalNumeral] ‘.’ digit [{digit | ‘_’} digit] [exponentPart] [floatType]
                        |  decimalNumeral exponentPart [floatType]
                        |  decimalNumeral floatType
exponentPart          ::=  (‘E’ | ‘e’) [‘+’ | ‘-’] digit [{digit | ‘_’} digit]

Floating point literals are of type Float when followed by a floating point type suffix F or f, and are of type Double otherwise.
The type Float consists of all IEEE 754 32-bit single-precision binary floating point values, whereas the type Double consists of all IEEE 754 64-bit double-precision binary floating point values.

If a floating point literal in a program is followed by a token starting with a letter, there must be at least one intervening whitespace character between the two tokens.

scala Copy

0.0        1e30f      3.14159f      1.0e-100      .1

The phrase 1.toString parses as three different tokens: the integer literal 1, a ., and the identifier toString.

1. is not a valid floating point literal because the mandatory digit after the . is missing.

Boolean Literals Copy Section

booleanLiteral  ::=  ‘true’ | ‘false’

The boolean literals true and false are members of type Boolean.

Character Literals Copy Section

characterLiteral  ::=  ‘'’ (charNoQuoteOrNewline | escapeSeq) ‘'’

A character literal is a single character enclosed in quotes.
The character can be any Unicode character except the single quote delimiter or \u000A (LF) or \u000D (CR); or any Unicode character represented by an
escape sequence.

scala Copy

'a'    '\u0041'    '\n'    '\t'

String Literals Copy Section

stringLiteral  ::=  ‘"’ {stringElement} ‘"’
stringElement  ::=  charNoDoubleQuoteOrNewline | escapeSeq

A string literal is a sequence of characters in double quotes.
The characters can be any Unicode character except the double quote delimiter or \u000A (LF) or \u000D (CR); or any Unicode character represented by an escape sequence.

If the string literal contains a double quote character, it must be escaped using
"\"".

The value of a string literal is an instance of class String.

scala Copy

"Hello, world!\n"
"\"Hello,\" replied the world."

Multi-Line String Literals

stringLiteral   ::=  ‘"""’ multiLineChars ‘"""’
multiLineChars  ::=  {[‘"’] [‘"’] charNoDoubleQuote} {‘"’}

A multi-line string literal is a sequence of characters enclosed in triple quotes """ ... """.
The sequence of characters is arbitrary, except that it may contain three or more consecutive quote characters only at the very end.
Characters must not necessarily be printable; newlines or other control characters are also permitted.
Escape sequences are not processed, except for Unicode escapes (this is deprecated since 2.13.2).

scala Copy

"""the present string
     spans three
     lines."""

This would produce the string:

text Copy

the present string
     spans three
     lines.

The Scala library contains a utility method stripMargin which can be used to strip leading whitespace from multi-line strings.
The expression

scala Copy

"""the present string
   |spans three
   |lines.""".stripMargin

evaluates to

text Copy

the present string
spans three
lines.

Method stripMargin is defined in class
scala.collection.StringOps.

Interpolated string

interpolatedString     ::= alphaid ‘"’ {[‘\’] interpolatedStringPart | ‘\\’ | ‘\"’} ‘"’
                         | alphaid ‘"""’ {[‘"’] [‘"’] char \ (‘"’ | ‘$’) | escape} {‘"’} ‘"""’
interpolatedStringPart ::= printableChar \ (‘"’ | ‘$’ | ‘\’) | escape
escape                 ::= ‘$$’
                         | ‘$"’
                         | ‘$’ alphaid
                         | ‘$’ BlockExpr
alphaid                ::= upper idrest
                         |  varid

An interpolated string consists of an identifier starting with a letter immediately followed by a string literal.
There may be no whitespace characters or comments between the leading identifier and the opening quote " of the string.
The string literal in an interpolated string can be standard (single quote) or multi-line (triple quote).

Inside an interpolated string none of the usual escape characters are interpreted no matter whether the string literal is normal (enclosed in single quotes) or multi-line (enclosed in triple quotes).
Note that the sequence \" does not close a normal string literal (enclosed in single quotes).

There are three forms of dollar sign escape.
The most general form encloses an expression in ${ and }, i.e. ${expr}.
The expression enclosed in the braces that follow the leading $ character is of syntactical category BlockExpr.
Hence, it can contain multiple statements, and newlines are significant.
Single ‘$’-signs are not permitted in isolation in an interpolated string.
A single ‘$’-sign can still be obtained by doubling the ‘$’ character: ‘$$’.
A single ‘"’-sign can be obtained by the sequence ‘$"’.

The simpler form consists of a ‘$’-sign followed by an identifier starting with a letter and followed only by letters, digits, and underscore characters, e.g., $id.
The simpler form is expanded by putting braces around the identifier, e.g., $id is equivalent to ${id}.
In the following, unless we explicitly state otherwise, we assume that this expansion has already been performed.

The expanded expression is type checked normally.
Usually, StringContext will resolve to the default implementation in the scala package, but it could also be user-defined.
Note that new interpolators can also be added through implicit conversion of the built-in scala.StringContext.

One could write an extension

implicit class StringInterpolation(s: StringContext) {
  def id(args: Any*) = ???
}

Escape Sequences Copy Section

The following character escape sequences are recognized in character and string literals.

In addition, Unicode escape sequences of the form \uxxxx, where each x is a hex digit are recognized in character and string literals.

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

Whitespace and Comments Copy Chapter

Tokens may be separated by whitespace characters and/or comments.
Comments come in two forms:

A single-line comment is a sequence of characters which starts with // and extends to the end of the line.

A multi-line comment is a sequence of characters between /* and */.
Multi-line comments may be nested, but are required to be properly nested.
Therefore, a comment like /* /* */ will be rejected as having an unterminated comment.

Trailing Commas in Multi-line Expressions Copy Chapter

If a comma (,) is followed immediately, ignoring whitespace, by a newline and a closing parenthesis ()), bracket (]), or brace (}), then the comma is treated as a "trailing comma" and is ignored.
For example:

foo(
  23,
  "bar",
  true,
)

XML mode Copy Chapter

In order to allow literal inclusion of XML fragments, lexical analysis switches from Scala mode to XML mode when encountering an opening angle bracket ‘<’ in the following circumstance:
The ‘<’ must be preceded either by whitespace, an opening parenthesis or an opening brace and immediately followed by a character starting an XML name.

( whitespace | ‘(’ | ‘{’ ) ‘<’ (XNameStart | ‘!’ | ‘?’)

  XNameStart ::= ‘_’ | BaseChar | Ideographic // as in W3C XML, but without ‘:’

The scanner switches from XML mode to Scala mode if either

• the XML expression or the XML pattern started by the initial ‘<’ has been successfully parsed, or if
• the parser encounters an embedded Scala expression or pattern and forces the Scanner back to normal mode, until the Scala expression or pattern is successfully parsed.
  In this case, since code and XML fragments can be nested, the parser has to maintain a stack that reflects the nesting of XML and Scala expressions adequately.

Note that no Scala tokens are constructed in XML mode, and that comments are interpreted as text.

The following value definition uses an XML literal with two embedded Scala expressions:

scala Copy

val b = <book>
          <title>The Scala Language Specification</title>
          <version>{scalaBook.version}</version>
          <authors>{scalaBook.authors.mkList("", ", ", "")}</authors>
        </book>

Spec 02 Identifiers Names And Scopes (`docs/_spec/02-identifiers-names-and-scopes.md`) Copy Section

title: Identifiers, Names & Scopes layout: default chapter: 2 Copy Chapter

Identifiers, Names and Scopes

Names in Scala identify types, values, methods, and classes which are collectively called entities.
Names are introduced by local
definitions,
inheritance,
import clauses, or
package clauses
which are collectively called bindings.

Bindings of different kinds have precedence defined on them:

1. Definitions that are local, inherited, or made available by a package clause and also defined in the same compilation unit as the reference to them, have the highest precedence.
2. Explicit imports have the next highest precedence.
3. Wildcard imports have the next highest precedence.
4. Definitions made available by a package clause, but not also defined in the same compilation unit as the reference to them, as well as imports which are supplied by the compiler but not explicitly written in source code, have the lowest precedence.

There are two different name spaces, one for types and one for terms.
The same name may designate a type and a term, depending on the context where the name is used.

A binding has a scope in which the entity defined by a single
name can be accessed using a simple name.
Scopes are nested.
A binding in some inner scope shadows bindings of lower precedence in the same scope as well as bindings of the same or lower precedence in outer scopes.

Note that shadowing is only a partial order.
In the following example, neither binding of x shadows the other.
Consequently, the reference to x in the last line of the block is ambiguous.

val x = 1
locally {
  import p.X.x
  x
}

A reference to an unqualified (type- or term-) identifier ´x´ is bound by the unique binding, which

• defines an entity with name ´x´ in the same namespace as the identifier, and
• shadows all other bindings that define entities with name ´x´ in that namespace.

It is an error if no such binding exists.
If ´x´ is bound by an import clause, then the simple name ´x´ is taken to be equivalent to the qualified name to which ´x´ is mapped by the import clause.
If ´x´ is bound by a definition, then ´x´ refers to the entity introduced by that binding.
In that case, the type of ´x´ is the type of the referenced entity.

A reference to a qualified (type- or term-) identifier ´e.x´ refers to the member of the type ´T´ of ´e´ which has the name ´x´ in the same namespace as the identifier.
It is an error if ´T´ is not a value type.
The type of ´e.x´ is specified as a type designator.

Binding precedence implies that the way source is bundled in files affects name resolution.
In particular, imported names have higher precedence than names, defined in other files, that might otherwise be visible because they are defined in either the current package or an enclosing package.

Note that a package definition is taken as lowest precedence, since packages are open and can be defined across arbitrary compilation units.

package util {
  import scala.util
  class Random
  object Test extends App {
    println(new util.Random)  // scala.util.Random
  }
}

The compiler supplies imports in a preamble to every source file.
This preamble conceptually has the following form, where braces indicate nested scopes:

import java.lang.*
{
  import scala.*
  {
    import Predef.*
    { /* source */ }
  }
}

These imports are taken as lowest precedence, so that they are always shadowed by user code, which may contain competing imports and definitions.
They also increase the nesting depth as shown, so that later imports shadow earlier ones.

As a convenience, multiple bindings of a type identifier to the same underlying type is permitted.
This is possible when import clauses introduce a binding of a member type alias with the same binding precedence, typically through wildcard imports.
This allows redundant type aliases to be imported without introducing an ambiguity.

object X { type T = annotation.tailrec }
object Y { type T = annotation.tailrec }
object Z {
  import X.*, Y.*, annotation.tailrec as T  // OK, all T mean tailrec
  @T def f: Int = { f ; 42 }                // error, f is not tail recursive
}

Similarly, imported aliases of names introduced by package statements are allowed, even though the names are strictly ambiguous:

// c.scala
package p { class C }

// xy.scala
import p.*
package p { class X extends C }
package q { class Y extends C }

The reference to C in the definition of X is strictly ambiguous because C is available by virtue of the package clause in a different file, and can't shadow the imported name.
But because the references are the same, the definition is taken as though it did shadow the import.

Example

Assume the following two definitions of objects named X in packages p and q in separate compilation units.

package p {
  object X { val x = 1; val y = 2 }
}

package q {
  object X { val x = true; val y = false }
}

The following program illustrates different kinds of bindings and precedences between them.

package p {                     // `X' bound by package clause
  import Console.*              // `println' bound by wildcard import
  object Y {
    println(s"L4: $X")          // `X' refers to `p.X' here
    locally {
      import q.*                // `X' bound by wildcard import
      println(s"L7: $X")        // `X' refers to `q.X' here
      import X.*                // `x' and `y' bound by wildcard import
      println(s"L9: $x")        // `x' refers to `q.X.x' here
      locally {
        val x = 3               // `x' bound by local definition
        println(s"L12: $x")     // `x' refers to constant `3' here
        locally {
          import q.X.*          // `x' and `y' bound by wildcard import
//        println(s"L15: $x")   // reference to `x' is ambiguous here
          import X.y            // `y' bound by explicit import
          println(s"L17: $y")   // `y' refers to `q.X.y' here
          locally {
            val x = "abc"       // `x' bound by local definition
            import p.X.*        // `x' and `y' bound by wildcard import
//          println(s"L21: $y") // reference to `y' is ambiguous here
            println(s"L22: $x") // `x' refers to string "abc" here
          }
        }
      }
    }
  }
}

Spec 03 Types (`docs/_spec/03-types.md`) Copy Section

title: Types layout: default chapter: 3 Copy Chapter

Types

/* Detailed source-code truncated for AI context efficiency. */

The above grammer describes the concrete syntax of types that can be written in user code.
Semantic operations on types in the Scala type system are better defined in terms of internal types, which are desugared from the concrete type syntax.

Internal Types Copy Chapter

The following abstract grammar defines the shape of internal types.
In this specification, unless otherwise noted, "types" refer to internal types.
Internal types abstract away irrelevant details such as precedence and grouping, and contain shapes of types that cannot be directly expressed using the concrete syntax.
They also contain simplified, decomposed shapes for complex concrete syntax types, such as refined types.

/* Detailed source-code truncated for AI context efficiency. */

Translation of Concrete Types into Internal Types Copy Section

Concrete types are recursively translated, or desugared, into internal types.
Most shapes of concrete types have a one-to-one translation to shapes of internal types.
We elaborate hereafter on the translation of the other ones.

Infix Types Copy Section

InfixType     ::=  CompoundType {id [nl] CompoundType}

A concrete infix type ´T_1´ op ´T_2´ consists of an infix operator op which gets applied to two type operands ´T_1´ and ´T_2´.
The type is translated to the internal type application op´[T_1, T_2]´.
The infix operator op may be an arbitrary identifier.

Type operators follow the same precedence and associativity as term operators.
For example, A + B * C parses as A + (B * C) and A | B & C parses as A | (B & C).
Type operators ending in a colon ‘:’ are right-associative; all other operators are left-associative.

In a sequence of consecutive type infix operations ´t_0 , \mathit{op} , t_1 , \mathit{op_2} , ... , \mathit{op_n} , t_n´, all operators ´\mathit{op}_1, ..., \mathit{op}_n´ must have the same associativity.
If they are all left-associative, the sequence is interpreted as ´(... (t_0 \mathit{op_1} t_1) \mathit{op_2} ...) \mathit{op_n} t_n´, otherwise it is interpreted as ´t_0 \mathit{op_1} (t_1 \mathit{op_2} ( ... \mathit{op_n} t_n) ...)´.

Under -source:future, if the type name is alphanumeric and the target type is not marked infix, a deprecation warning is emitted.

The type operators | and & are not really special.
Nevertheless, unless shadowed, they resolve to the fundamental type aliases scala.| and scala.&, which represent union and intersection types, respectively.

Function Types Copy Section

Type              ::=  FunTypeArgs ‘=>’ Type
FunTypeArgs       ::=  InfixType
                    |  ‘(’ [ FunArgTypes ] ‘)’
                    |  FunParamClause
FunArgTypes       ::=  FunArgType { ‘,’ FunArgType }
FunArgType        ::=  Type
                    |  ‘=>’ Type
FunParamClause    ::=  ‘(’ TypedFunParam {‘,’ TypedFunParam } ‘)’
TypedFunParam     ::=  id ‘:’ Type

The concrete function type ´(T_1, ..., T_n) \Rightarrow R´ represents the set of function values that take arguments of types ´T_1, ..., Tn´ and yield results of type ´R´.
The case of exactly one argument type ´T \Rightarrow R´ is a shorthand for ´(T) \Rightarrow R´.
An argument type of the form ´\Rightarrow T´ represents a call-by-name parameter of type ´T´.

Function types associate to the right, e.g. ´S \Rightarrow T \Rightarrow R´ is the same as ´S \Rightarrow (T \Rightarrow R)´.

Function types are covariant in their result type and contravariant in their argument types.

Function types translate into internal class types that define an apply method.
Specifically, the ´n´-ary function type ´(T_1, ..., T_n) \Rightarrow R´ translates to the internal class type scala.Function´_n´[´T_1´, ..., ´T_n´, ´R´].
In particular ´() \Rightarrow R´ is a shorthand for class type scala.Function´_0´[´R´].

Such class types behave as if they were instances of the following trait:

trait Function´_n´[-´T_1´, ..., -´T_n´, +´R´]:
  def apply(´x_1´: ´T_1´, ..., ´x_n´: ´T_n´): ´R´

Their exact supertype and implementation can be consulted in the function classes section of the standard library page in this document.

Dependent function types are function types whose parameters are named and can referred to in result types.
In the concrete type ´(x_1: T_1, ..., x_n: T_n) \Rightarrow R´, ´R´ can refer to the parameters ´x_i´, notably to form path-dependent types.
It translates to the internal refined type

scala.Function´_n´[´T_1´, ..., ´T_n´, ´S´] {
  def apply(´x_1´: ´T_1´, ..., ´x_n´: ´T_n´): ´R´
}

where ´S´ is the least super type of ´R´ that does not mention any of the ´x_i´.

Polymorphic function types are function types that take type arguments.
Their result type must be a function type.
In the concrete type ´[a_1 >: L_1 <: H_1, ..., a_n >: L_1 <: H_1] => (T_1, ..., T_m) => R´, the types ´T_j´ and ´R´ can refer to the type parameters ´a_i´.
It translates to the internal refined type

scala.PolyFunction {
  def apply[´a_1 >: L_1 <: H_1, ..., a_n >: L_1 <: H_1´](´x_1´: ´T_1´, ..., ´x_n´: ´T_n´): ´R´
}

Tuple Types Copy Section

SimpleType1           ::=  ...
                        |  ‘(’ TypesOrWildcards ‘)’

A tuple type ´(T_1, ..., T_n)´ where ´n \geq 2´ is sugar for the type ´T_1´ *: ... *: ´T_n´ *: scala.EmptyTuple, which is itself a series of nested infix types which are sugar for *:[´T_1´, *:[´T_2´, ... *:[´T_n´, scala.EmptyTuple]]].
The ´T_i´ can be wildcard type arguments.

Notes:

• (´T_1´) is the type ´T_1´, and not ´T_1´ *: scala.EmptyTuple (´T_1´ cannot be a wildcard type argument in that case).
• () is not a valid type (i.e. it is not desugared to scala.EmptyTuple).

Concrete Refined Types Copy Section

RefinedType           ::=  AnnotType {[nl] Refinement}
SimpleType1           ::=  ...
                        |  Refinement
Refinement            ::=  :<<< [RefineDef] {semi [RefineDef]} >>>

RefineDef             ::=  ‘val’ ValDef
                        |  ‘def’ DefDef
                        |  ‘type’ {nl} TypeDef

In the concrete syntax of types, refinements can contain several refined definitions.
They must all be abstract.
Moreover, the refined definitions can refer to each other as well as to members of the parent type, i.e., they have access to this.

In the internal types, each refinement defines exactly one refined definition, and references to this must be made explicit in a recursive type.

The conversion from the concrete syntax to the abstract syntax works as follows:

1. Create a fresh recursive this name ´\alpha´.
2. Replace every implicit or explicit reference to this in the refinement definitions by ´\alpha´.
3. Create nested refined types, one for every refined definition.
4. Unless ´\alpha´ was never actually used, wrap the result in a recursive type { ´\alpha´ => ´...´ }.

Concrete Match Types Copy Section

MatchType             ::=  InfixType ‘match’ <<< TypeCaseClauses >>>
TypeCaseClauses       ::=  TypeCaseClause { TypeCaseClause }
TypeCaseClause        ::=  ‘case’ (InfixType | ‘_’) ‘=>’ Type [semi]

In the concrete syntax of match types, patterns are arbitrary InfixTypes, and there is no explicit notion of type capture.
In the abstract syntax, however, captures are made explicit and can only appear as arguments to TypeCaseAppliedPatterns.

If the concrete pattern is _, its conversion is the internal type scala.Any.
If it is a concrete InfixType, it is first converted to an internal type ´P´.
If ´P´ is not a ParameterizedType, then use ´P´ as the internal pattern.
Otherwise, ´P´ is recursively converted into a TypeCasePattern as follows:

1. If ´P´ is a WildcardTypeArg of the form ? >: ´L´ <: ´H´, return a TypeCapture of the form _ >: ´L´ <: ´H´.
2. If ´P´ is a direct type designator ´t´ whose name starts with a lowercase and was not written using backticks, return a TypeCapture ´t´ >: ´L´ <: ´H´ where >: ´L´ <: ´H´ is the declared type definition of ´t´.
3. If ´P´ is a ParameterizedType of the form ´T´[´T_1´, ..., ´T_n´]:
4. Recursively convert each ´T_i´ into a pattern ´P_i´.
5. If ´P_i´ is a Type for all ´i´, return ´P´.
6. Otherwise, return the TypeCaseAppliedPattern ´T´[´P_1´, ..., ´P_n´].
7. Otherwise, return ´P´.

This conversion ensures that every TypeCaseAppliedPattern recursively contains at least one TypeCapture.
Moreover, at the top level, the pattern is never a TypeCapture: all TypeCaptures are nested within a TypeCaseAppliedPattern.

The bound of the internal MatchType is always <: scala.Any by default.
It can be overridden in a type member definition.

Concrete Type Lambdas Copy Section

TypeLambda            ::= TypeLambdaParams ‘=>>’ Type
TypeLambdaParams      ::=  ‘[’ TypeLambdaParam {‘,’ TypeLambdaParam} ‘]’
TypeLambdaParam       ::=  {Annotation} (id | ‘_’) [TypeParamClause] TypeBounds
TypeParamClause       ::=  ‘[’ VariantTypeParam {‘,’ VariantTypeParam} ‘]’
VariantTypeParam      ::=  {Annotation} [‘+’ | ‘-’] (id | ‘_’) [TypeParamClause] TypeBounds

At the top level of concrete type lambda parameters, variance annotations are not allowed.
However, in internal types, all type lambda parameters have explicit variance annotations.

When translating a concrete type lambda into an internal one, the variance of each type parameter is inferred from its usages in the body of the type lambda.

Definitions Copy Chapter

From here onwards, we refer to internal types by default.

Kinds Copy Section

The Scala type system is fundamentally higher-kinded.
Types are either proper types, type constructors or poly-kinded types.

• Proper types are the types of terms.
• Type constructors are type-level functions from types to types.
• Poly-kinded types can take various kinds.

All types live in a single lattice with respect to a conformance relationship ´<:´.
The top type is AnyKind and the bottom type is Nothing: all types conform to AnyKind, and Nothing conforms to all types.
They can be referred to with the fundamental type aliases scala.AnyKind and scala.Nothing, respectively.

Types can be concrete or abstract.
An abstract type ´T´ always has lower and upper bounds ´L´ and ´H´ such that ´L >: T´ and ´T <: H´.
A concrete type ´T´ is considered to have itself as both lower and upper bound.

The kind of a type is indicated by its (transitive) upper bound:

• A type ´T <:´ scala.Any is a proper type.
• A type ´T <: K´ where ´K´ is a type lambda (of the form [´\pm a_1 >: L_1 <: H_1´, ..., ´\pm a_n >: L_n <: H_n´] =>> ´U´) is a type constructor.
• Other types are poly-kinded; they are neither proper types nor type constructors.

As a consequece, AnyKind itself is poly-kinded.
Nothing is universally-kinded: it has all kinds at the same time, since it conforms to all types.

With this representation, it is rarely necessary to explicitly talk about the kinds of types.
Usually, the kinds of types are implicit through their bounds.

Another way to look at it is that type bounds are kinds.
They represent sets of types: ´>: L <: H´ denotes the set of types ´T´ such that ´L <: T´ and ´T <: H´.
A set of types can be seen as a type of types, i.e., as a kind.

Conventions

Type bounds are formally always of the form ´>: L <: H´.
By convention, we can omit either of both bounds in writing.

• When omitted, the lower bound ´L´ is Nothing.
• When omitted, the higher bound ´H´ is Any (not AnyKind).

These conventions correspond to the defaults in the concrete syntax.

Proper Types Copy Section

Proper types are also called value types, as they represent sets of values.

Stable types are value types that contain exactly one non-null value.
Stable types can be used as prefixes in named designator types.
The stable types are

• designator types referencing a stable term,
• this types,
• super types,
• literal types,
• recursive this types, and
• skolem types.

Every stable type ´T´ is concrete and has an underlying type ´U´ such that ´T <: U´.

Type Constructors Copy Section

To each type constructor corresponds an inferred type parameter clause which is computed as follows:

• For a type lambda, its type parameter clause (including variance annotations).
• For a polymorphic class type, the type parameter clause of the referenced class definition.
• For a non-class type designator, the inferred clause of its upper bound.

Type Definitions Copy Section

A type definition ´D´ represents the right-hand-side of a type member definition or the bounds of a type parameter.
It is either:

• a type alias of the form ´= U´, or
• an abstract type definition with bounds ´>: L <: H´.

All type definitions have a lower bound ´L´ and an upper bound ´H´, which are types.
For type aliases, ´L = H = U´.

The type definition of a type parameter is never a type alias.

Types Copy Chapter

Type Lambdas Copy Section

TypeLambda     ::=  ‘[‘ TypeParams ‘]‘ ‘=>>‘ Type
TypeParams     ::=  TypeParam {‘,‘ TypeParam}
TypeParam      ::=  ParamVariance id TypeBounds
ParamVariance  ::=  ε | ‘+‘ | ‘-‘

A type lambda of the form [´\pm a_1 >: L_1 <: H_1´, ..., ´\pm a_n >: L_n <: H_n´] =>> ´U´ is a direct representation of a type constructor with ´n´ type parameters.
When applied to ´n´ type arguments that conform to the specified bounds, it produces another type ´U´.
Type lambdas are always concrete types.

The scope of a type parameter extends over the result type ´U´ as well as the bounds of the type parameters themselves.

All type constructors conform to some type lambda.

The type bounds of the parameters of a type lambda are in contravariant position, while its result type is in covariant position.
If some type constructor ´T <:´ [´\pm a_1 >: L_1 <: H_1´, ..., ´\pm a_n >: L_n <: H_n´] =>> ´U´, then ´T´'s ´i´th type parameter bounds contain the bounds ´>: L_i <: H_i´, and its result type conforms to ´U´.

Note: the concrete syntax of type lambdas does not allow to specify variances for type parameters.
Instead, variances are inferred from the body of the lambda to be as general as possible.

Example

type Lst = [T] =>> List[T] // T is inferred to be covariant with bounds >: Nothing <: Any
type Fn = [A <: Seq[?], B] =>> (A => B) // A is inferred to be contravariant, B covariant

val x: Lst[Int] = List(1) // ok, Lst[Int] expands to List[Int]
val f: Fn[List[Int], Int] = (x: List[Int]) => x.head // ok

val g: Fn[Int, Int] = (x: Int) => x // error: Int does not conform to the bound Seq[?]

def liftPair[F <: [T] =>> Any](f: F[Int]): Any = f
liftPair[Lst](List(1)) // ok, Lst <: ([T] =>> Any)

Designator Types Copy Section

DesignatorType    ::=  Prefix ‘.‘ id
Prefix            ::=  Type
                    |  PackageRef
                    |  ε
PackageRef        ::=  id {‘.‘ id}

A designator type (or designator for short) is a reference to a definition.
Term designators refer to term definitions, while type designators refer to type definitions.

In the abstract syntax, the id retains whether it is a term or type.
In the concrete syntax, an id refers to a type designator, while id.type refers to a term designator.
In that context, term designators are often called singleton types.

Designators with an empty prefix ´\epsilon´ are called direct designators.
They refer to local definitions available in the scope:

• Local type, object, val, lazy val, var or def definitions
• Term or type parameters

The ids of direct designators are protected from accidental shadowing in the abstract syntax.
They retain the identity of the exact definition they refer to, rather than relying on scope-based name resolution. [^debruijnoralpha]

[^debruijnoralpha]: In the literature, this is often achieved through De Bruijn indices or through alpha-renaming when needed. In a concrete implementation, this is often achieved through retaining symbolic references in a symbol table.

The ´\epsilon´ prefix cannot be written in the concrete syntax.
A bare id is used instead and resolved based on scopes.

Named designators refer to member definitions of a non-empty prefix:

• Top-level definitions, including top-level classes, have a package ref prefix
• Class member definitions and refinements have a type prefix

Term Designators

A term designator ´p.x´ referring to a term definition t has an underlying type ´U´.
If ´p = \epsilon´ or ´p´ is a package ref, the underlying type ´U´ is the declared type of t and ´p.x´ is a stable type if an only if t is a val or object definition.
Otherwise, the underlying type ´U´ and whether ´p.x´ is a stable type are determined by memberType(´p´, ´x´).

All term designators are concrete types.
If scala.Null ´<: U´, the term designator denotes the set of values consisting of null and the value denoted by ´t´, i.e., the value ´v´ for which t eq v.
Otherwise, the designator denotes the singleton set only containing ´v´.

Type Designators

A type designator ´p.C´ referring to a class definition (including traits and hidden object classes) is a class type.
If the class is monomorphic, the type designator is a value type denoting the set of instances of ´C´ or any of its subclasses.
Otherwise it is a type constructor with the same type parameters as the class definition.
All class types are concrete, non-stable types.

If a type designator ´p.T´ is not a class type, it refers to a type definition T (a type parameter or a type member definition) and has an underlying type definition.
If ´p = \epsilon´ or ´p´ is a package ref, the underlying type definition is the declared type definition of T.
Otherwise, it is determined by memberType(´p´, ´T´).
A non-class type designator is concrete (resp. stable) if and only if its underlying type definition is an alias ´U´ and ´U´ is itself concrete (resp. stable).

Parameterized Types Copy Section

ParameterizedType ::=  Type ‘[‘ TypeArgs ‘]‘
TypeArgs          ::=  TypeArg {‘,‘ TypeArg}
TypeArg           ::=  Type
                    |  WilcardTypeArg
WildcardTypeArg   ::=  ‘?‘ TypeBounds

A parameterized type ´T[T_1, ..., T_n]´ consists of a type constructor ´T´ and type arguments ´T_1, ..., T_n´ where ´n \geq 1´.
The parameterized type is well-formed if

• ´T´ is a type constructor which takes ´n´ type parameters ´a_1, ..., a_n´, i.e., it must conform to a type lambda of the form ´[\pm a_1 >: L_1 <: H_1, ..., \pm a_n >: L_n <: H_n] => U´, and
• if ´T´ is an abstract type constructor, none of the type arguments is a wildcard type argument, and
• each type argument conforms to its bounds, i.e., given ´\sigma´ the substitution ´[a_1 := T_1, ..., a_n := T_n]´, for each type ´i´:
  • if ´T_i´ is a type and ´\sigma L_i <: T_i <: \sigma H_i´, or
  • ´T_i´ is a wildcard type argument ´? >: L_{Ti} <: H_{Ti}´ and ´\sigma L_i <: L_{Ti}´ and ´H_{Ti} <: \sigma H_i´.

´T[T_1, ..., T_n]´ is a parameterized class type if and only if ´T´ is a class type.
All parameterized class types are value types.

In the concrete syntax of wildcard type arguments, if both bounds are omitted, the real bounds are inferred from the bounds of the corresponding type parameter in the target type constructor (which must be concrete).
If only one bound is omitted, Nothing or Any is used, as usual.

Also in the concrete syntax, _ can be used instead of ? for compatibility reasons, with the same meaning.
This alternative will be deprecated in the future, and is already deprecated under -source:future.

Simplification Rules

Wildcard type arguments used in covariant or contravariant positions can always be simplified to regular types.

Let ´T[T_1, ..., T_n]´ be a parameterized type for a concrete type constructor.
Then, applying a wildcard type argument ´? >: L <: H´ at the ´i´'th position obeys the following equivalences:

• If the type parameter ´T_i´ is declared covariant, then ´T[..., ? >: L <: H, ...] =:= T[..., H, ...]´.
• If the type parameter ´T_i´ is declared contravariant, then ´T[..., ? >: L <: H, ...] =:= T[..., L, ...]´.

Example Parameterized Types

Given the partial type definitions:

class TreeMap[A <: Comparable[A], B] { ... }
class List[+A] { ... }
class I extends Comparable[I] { ... }

class F[M[A], X] { ... } // M[A] desugars to M <: [A] =>> Any
class S[K <: String] { ... }
class G[M[Z <: I], I] { ... } // M[Z <: I] desugars to M <: [Z <: I] =>> Any

the following parameterized types are well-formed:

TreeMap[I, String]
List[I]
List[List[Boolean]]

F[List, Int]
F[[X] =>> List[X], Int]
G[S, String]

List[?] // ? inferred as List[_ >: Nothing <: Any], equivalent to List[Any]
List[? <: String] // equivalent to List[String]
S[? <: String]
F[?, Boolean] // ? inferred as ? >: Nothing <: [A] =>> Any

and the following types are ill-formed:

TreeMap[I]            // illegal: wrong number of parameters
TreeMap[List[I], Int] // illegal: type parameter not within bound
List[[X] => List[X]]

F[Int, Boolean]       // illegal: Int is not a type constructor
F[TreeMap, Int]       // illegal: TreeMap takes two parameters,
                      //   F expects a constructor taking one
F[[X, Y] => (X, Y)]
G[S, Int]             // illegal: S constrains its parameter to
                      //   conform to String,
                      // G expects type constructor with a parameter
                      //   that conforms to Int

The following code also contains an ill-formed type:

trait H[F[A]]:  // F[A] desugars to F <: [A] =>> Any, which is abstract
  def f: F[_]   // illegal : an abstract type constructor
                // cannot be applied to wildcard arguments.

This Types Copy Section

ThisType  ::=  classid ‘.‘ ‘this‘

A this type ´C´.this denotes the this value of class ´C´ within ´C´.

This types often appear implicitly as the prefix of designator types referring to members of ´C´.
They play a particular role in the type system, since they are affected by the as seen from operation on types.

This types are stable types.
The underlying type of ´C´.this is the self type of ´C´.

Super Types Copy Section

SuperType  ::=  classid ‘.‘ ‘super‘ ‘[‘ classid ‘]‘

A super type ´C´.super[´D´] denotes the this value of class C within C, but "widened" to only see members coming from a parent class or trait ´D´.

Super types exist for compatibility with Scala 2, which allows shadowing of inner classes.
In a Scala 3-only context, a super type can always be replaced by the corresponding this type.
Therefore, we omit further discussion of super types in this specification.

Literal Types Copy Section

LiteralType  ::=  SimpleLiteral

A literal type lit denotes the single literal value lit.
Thus, the type ascription 1: 1 gives the most precise type to the literal value 1: the literal type 1.

At run time, an expression e is considered to have literal type lit if e == lit.
Concretely, the result of e.isInstanceOf[lit] and e match { case _ : lit => } is determined by evaluating e == lit.

Literal types are available for all primitive types, as well as for String.
However, only literal types for Int, Long, Float, Double, Boolean, Char and String can be expressed in the concrete syntax.

Literal types are stable types.
Their underlying type is the primitive type containing their value.

Example

val x: 1 = 1
val y: false = false
val z: false = y
val int: Int = x

val badX: 1 = int       // error: Int is not a subtype of 1
val badY: false = true  // error: true is not a subtype of false

By-Name Types Copy Section

ByNameType  ::=  ‘=>‘ Type

A by-name type ´=> T´ denotes the declared type of a by-name term parameter.
By-name types can only appear as the types of parameters in method types, and as type arguments in parameterized types.

Annotated Types Copy Section

AnnotatedType  ::=  Type Annotation

An annotated type ´T a´ attaches the annotation ´a´ to the type ´T´.

Example

The following type adds the @suspendable annotation to the type String:

String @suspendable

Refined Types Copy Section

RefinedType  ::=  Type ‘{‘ Refinement ‘}‘
Refinement   ::=  ‘type‘ id TypeAliasOrBounds
               |  ‘def‘ id ‘:‘ TypeOrMethodic
               |  ‘val‘ id ‘:‘ Type

A refined type ´T { R }´ denotes the set of values that belong to ´T´ and also have a member conforming to the refinement ´R´.

The refined type ´T { R }´ is well-formed if:

• ´T´ is a proper type, and
• if ´R´ is a term (def or val) refinement, the refined type is a proper type, and
• if ´R´ overrides a member of ´T´, the usual rules for overriding apply, and
• if ´R´ is a def refinement with a polymorphic method type, then ´R´ overrides a member definition of ´T´.

As an exception to the last rule, a polymorphic method type refinement is allowed if ´T <:´ scala.PolyFunction and ´id´ is the name apply.

If the refinement ´R´ overrides no member of ´T´ and is not an occurrence of the scala.PolyFunction exception, the refinement is said to be “structural” [^2].

[^2]: A reference to a structurally defined member (method call or access to a value or variable) may generate binary code that is significantly slower than an equivalent code to a non-structural member.

Note: since a refinement does not define a class, it is not possible to use a this type to reference term and type members of the parent type ´T´ within the refinement.
When the surface syntax of refined types makes such references, a recursive type wraps the refined type, given access to members of self through a recursive-this type.

Example

Given the following class definitions:

trait T:
  type X <: Option[Any]
  def foo: Any
  def fooPoly[A](x: A): Any

trait U extends T:
  override def foo: Int
  override def fooPoly[A](x: A): A

trait V extends T
  type X = Some[Int]
  def bar: Int
  def barPoly[A](x: A): A

We get the following conformance relationships:

• U <: T { def foo: Int }
• U <: T { def fooPoly[A](x: A): A }
• U <: (T { def foo: Int }) { def fooPoly[A](x: A): A } (we can chain refined types to refine multiple members)
• V <: T { type X <: Some[Any] }
• V <: T { type X >: Some[Nothing] }
• V <: T { type X = Some[Int] }
• V <: T { def bar: Any } (a structural refinement)

The following refined types are not well-formed:

• T { def barPoly[A](x: A): A } (structural refinement for a polymorphic method type)
• T { type X <: List[Any] } (does not satisfy overriding rules)
• List { def head: Int } (the parent type List is not a proper type)
• T { def foo: List } (the refined type List is not a proper type)
• T { def foo: T.this.X } (T.this is not allowed outside the body of T)

Recursive Types Copy Section

RecursiveType  ::=  ‘{‘ recid ‘=>‘ Type ‘}‘
RecursiveThis  ::=  recid ‘.‘ ‘this‘

A recursive type of the form { ´\alpha´ => ´T´ } represents the same values as ´T´, while offering ´T´ access to its recursive this type ´\alpha´.

Recursive types cannot directly be expressed in the concrete syntax.
They are created as needed when a refined type in the concrete syntax contains a refinement that needs access to the this value.
Each recursive type defines a unique self-reference ´\alpha´, distinct from any other recursive type in the system.

Recursive types can be unfolded during subtyping as needed, replacing references to its ´\alpha´ by a stable reference to the other side of the conformance relationship.

Example

Given the class definitions in the refined types section, we can write the following refined type in the source syntax:

T { def foo: X }
// equivalent to
T { def foo: this.X }

This type is not directly expressible as a refined type alone, as the refinement cannot access the this value.
Instead, in the abstract syntax of types, it is translated to { ´\alpha´ => ´T´ { def foo: ´\alpha´.X } }.

Given the following definitions:

trait Z extends T:
  type X = Option[Int]
  def foo: Option[Int] = Some(5)

val z: Z

we can check that z ´<:´ { ´\alpha´ => ´T´ { def foo: ´\alpha´.X } }.
We first unfold the recursive type, substituting ´z´ for ´\alpha´, resulting in z ´<:´ T { def foo: z.X }.
Since the underlying type of ´z´ is ´Z´, we can resolve z.X to mean Option[Int], and then validate that z ´<:´ T and that z has a member def foo: Option[Int].

Union and Intersection Types Copy Section

UnionType         ::=  Type ‘｜‘ Type
IntersectionType  ::=  Type ‘＆‘ Type

Syntactically, the types S | T and S & T are infix types, where the infix operators are | and &, respectively (see infix types).

However, in this specification, ´S ｜ T´ and ´S ＆ T´ refer to the underlying core concepts of union and intersection types, respectively.

• The type ´S ｜ T´ represents the set of values that are represented by either ´S´ or ´T´.
• The type ´S ＆ T´ represents the set of values that are represented by both ´S´ and ´T´.

From the conformance rules rules on union and intersection types, we can show that ´＆´ and ´｜´ are commutative and associative.
Moreover, ＆ is distributive over ｜.
For any type ´A´, ´B´ and ´C´, all of the following relationships hold:

• ´A ＆ B =:= B ＆ A´,
• ´A ｜ B =:= B ｜ A´,
• ´(A ＆ B) ＆ C =:= A ＆ (B ＆ C)´,
• ´(A ｜ B) ｜ C =:= A ｜ (B ｜ C)´, and
• ´A ＆ (B ｜ C) =:= (A ＆ B) ｜ (A ＆ C)´.

If ´C´ is a co- or contravariant type constructor, ´C[A] ＆ C[B]´ can be simplified using the following rules:

• If ´C´ is covariant, ´C[A] ＆ C[B] =:= C[A ＆ B]´
• If ´C´ is contravariant, ´C[A] ＆ C[B] =:= C[A | B]´

The right-to-left validity of the above two rules can be derived from the definition of covariance and contravariance and the conformance rules of union and intersection types:

• When ´C´ is covariant, we can derive ´C[A ＆ B] <: C[A] ＆ C[B]´.
• When ´C´ is contravariant, we can derive ´C[A ｜ B] <: C[A] ＆ C[B]´.

Join of a union type

In some situations, a union type might need to be widened to a non-union type.
For this purpose, we define the join of a union type ´T_1 ｜ ... ｜ T_n´ as the smallest intersection type of base class instances of ´T_1, ..., T_n´.
Note that union types might still appear as type arguments in the resulting type, this guarantees that the join is always finite.

For example, given

trait C[+T]
trait D
trait E
class A extends C[A] with D
class B extends C[B] with D with E

The join of ´A ｜ B´ is ´C[A ｜ B] ＆ D´

Match Types Copy Section

MatchType               ::=  Type ‘match‘ ‘<:‘ Type ‘{‘ {TypeCaseClause} ‘}‘
TypeCaseClause          ::=  ‘case‘ TypeCasePattern ‘=>‘ Type
TypeCasePattern         ::=  TypeCapture
                          |  TypeCaseAppliedPattern
                          |  Type
TypeCaseAppliedPattern  ::=  Type ‘[‘ TypeCasePattern { ‘,‘ TypeCasePattern } ‘]‘
TypeCapture             ::=  (id | ‘_‘) TypeBounds

A match type contains a scrutinee, a list of case clauses, and an upper bound.
The scrutinee and the upper bound must both be proper types.
A match type can be reduced to the body of a case clause if the scrutinee matches its pattern, and if it is provably disjoint from every earlier pattern.

Legal patterns

A TypeCasePattern is a legal pattern if and only if one of the following is true:

• It is a Type, or
• It is a TypeCaseAppliedPattern of the form ´P´[´P_1´, ..., ´P_n´] where ´P´ is a "pattern-legal type constructor" and for each ´i´, either:
  • ´P_i´ is a TypeCapture, or
  • ´P_i´ is a Type, or
  • ´P_i´ is a TypeCaseAppliedPattern, the type constructor ´P´ is covariant in its ´i´th type parameter, and ´P_i´ is recursively a legal pattern.

A type ´P´ is a "pattern-legal type constructor" if one of the following is true:

• It is a class type constructor, or
• It is the scala.compiletime.ops.int.S type constructor, or
• It is an abstract type constructor, or
• It is a type lambda with a refined result type of the form [´a´ >: ´L´ <: ´H´] =>> ´B´ { type ´T´ = ´a´ } where:
  • ´B´ contains no occurrence of ´a´,
  • there exists a type member ´T´ in ´B´, and
  • the bounds >: ´L´ <: ´H´ are not any more restrictive than those of ´T´ in ´B´, i.e., ´L´ <: ´(∃ \alpha : B).T´ <: ´H´.
• It is a type lambda of the form [´\pm a_1 >: L_1 <: H_1´, ..., ´\pm a_n >: L_n <: H_n´] =>> ´U´ such that:
  • Its bounds contain all possible values of its arguments, and
  • When applied to the type arguments, it beta-reduces to a new legal MatchTypeAppliedPattern that contains exactly one instance of every type capture present in the type arguments.
• It is a concrete type designator with underlying type definition = ´U´ and ´U´ is recursively a "pattern-legal type constructor".

Examples of legal patterns

Given the following definitions:

class Inv[A]
class Cov[+A]
class Contra[-A]

class Base {
  type Y
}

type YExtractor[t] = Base { type Y = t }
type ZExtractor[t] = Base { type Z = t }

type IsSeq[t <: Seq[Any]] = t

Here are examples of legal patterns:

// TypeWithoutCapture's
case Any => // also the desugaring of `case _ =>` when the _ is at the top-level
case Int =>
case List[Int] =>
case Array[String] =>

// Class type constructors with direct captures
case scala.collection.immutable.List[t] => // not Predef.List; it is a type alias
case Array[t] =>
case Contra[t] =>
case Either[s, t] =>
case Either[s, Contra[Int]] =>
case h *: t =>
case Int *: t =>

// The S type constructor
case S[n] =>

// An abstract type constructor
// given a [F[_]] or `type F[_] >: L <: H` in scope
case F[t] =>

// Nested captures in covariant position
case Cov[Inv[t]] =>
case Cov[Cov[t]] =>
case Cov[Contra[t]] =>
case Array[h] *: t => // sugar for *:[Array[h], t]
case g *: h *: EmptyTuple =>

// Type aliases
case List[t] => // which is Predef.List, itself defined as `type List[+A] = scala.collection.immutable.List[A]`

// Refinements (through a type alias)
case YExtractor[t] =>

The following patterns are not legal:

// Type capture nested two levels below a non-covariant type constructor
case Inv[Cov[t]] =>
case Inv[Inv[t]] =>
case Contra[Cov[t]] =>

// Type constructor with bounds that do not contain all possible instantiations
case IsSeq[t] =>

// Type refinement where the refined type member is not a member of the parent
case ZExtractor[t] =>

Matching

Given a scrutinee X and a match type case case P => R with type captures ts, matching proceeds in three steps:

1. Compute instantiations for the type captures ts', and check that they are specific enough.
2. If successful, check that X <:< [ts := ts']P.
3. If successful, reduce to [ts := ts']R.

The instantiations are computed by the recursive function matchPattern(X, P, variance, scrutIsWidenedAbstract).
At the top level, variance = 1 and scrutIsWidenedAbstract = false.

matchPattern behaves according to what kind is P:

• If P is a TypeWithoutCapture:
  • Do nothing (always succeed).
• If P is a WildcardCapture ti = _:
  • If X is of the form _ >: L <: H, instantiate ti := H (anything between L and H would work here),
  • Otherwise, instantiate ti := X.
• If P is a TypeCapture ti:
  • If X is of the form _ >: L <: H,
    • If scrutIsWidenedAbstract is true, fail as not specific.
    • Otherwise, if variance = 1, instantiate ti := H.
    • Otherwise, if variance = -1, instantiate ti := L.
    • Otherwise, fail as not specific.
  • Otherwise, if variance = 0 or scrutIsWidenedAbstract is false, instantiate ti := X.
  • Otherwise, fail as not specific.
• If P is a MatchTypeAppliedPattern of the form T[Qs]:
  • Assert: variance = 1 (from the definition of legal patterns).
  • If T is a class type constructor of the form p.C:
    • If baseType(X, C) is not defined, fail as not matching.
    • Otherwise, it is of the form q.C[Us].
    • If p =:= q is false, fail as not matching.
    • Let innerScrutIsWidenedAbstract be true if either scrutIsWidenedAbstract or X is not a concrete type.
    • For each pair of (Ui, Qi), compute matchPattern(Ui, Qi, vi, innerScrutIsWidenedAbstract) where vi is the variance of the ith type parameter of T.
  • If T is scala.compiletime.ops.int.S:
    • If n = natValue(X) is undefined or n <= 0, fail as not matching.
    • Otherwise, compute matchPattern(n - 1, Q1, 1, scrutIsWidenedAbstract).
  • If T is an abstract type constructor:
    • If X is not of the form F[Us] or F =:= T is false, fail as not matching.
    • Otherwise, for each pair of (Ui, Qi), compute matchPattern(Ui, Qi, vi, scrutIsWidenedAbstract) where vi is the variance of the ith type parameter of T.
  • If T is a refined type of the form Base { type Y = ti }:
    • Let q be X if X is a stable type, or the skolem type ∃α:X otherwise.
    • If q does not have a type member Y, fail as not matching (that implies that X <:< Base is false, because Base must have a type member Y for the pattern to be legal).
    • If q is not a skolem type:
      • Compute matchPattern(ti, q.Y, 0, scrutIsWidenedAbstract).
    • Otherwise, if q.Y is a type alias with underlying type definition = U:
      • Let U' be the result of perform type avoidance on U to remove references to q.
      • If successful, compute matchPattern(ti, U', 0, scrutIsWidenedAbstract).
      • Otherwise, fail as not specific.
  • If T is a concrete type alias to a type lambda:
    • Let P' be the beta-reduction of P.
    • Compute matchPattern(P', X, variance, scrutIsWidenedAbstract).

Disjointness

A scrutinee ´X´ is provably disjoint from a pattern ´P´ iff it is provably disjoint from the type ´P'´ obtained by replacing every type capture in ´P´ by a wildcard type argument with the same bounds.

We note ´X ⋔ Y´ to say that ´X´ and ´Y´ are provably disjoint.
Intuitively, that notion is based on the following properties of the Scala language:

• Single inheritance of classes
• Final classes cannot be extended
• Sealed traits have a known set of direct children
• Constant types with distinct values are nonintersecting
• Singleton paths to distinct enum case values are nonintersecting

However, a precise definition of provably-disjoint is complicated and requires some helpers.
We start with the notion of "simple types", which are a minimal subset of Scala internal types that capture the concepts mentioned above.

A "simple type" is one of:

• Nothing
• AnyKind
• ´p.C[...X_i]´ a possibly parameterized class type, where ´p´ and ´...X_i´ are arbitrary types (not just simple types)
• ´c´ a literal type
• ´p.C.x´ where C is an enum class and x is one of its value cases
• ´X_1 ＆ X_2´ where ´X_1´ and ´X_2´ are both simple types
• ´X_1 ｜ X_2´ where ´X_1´ and ´X_2´ are both simple types
• ´[...a_i]´ =>> ´X_1´ where ´X_1´ is a simple type

We define ´⌈X⌉´ a function from a full Scala type to a simple type.
Intuitively, it returns the "smallest" simple type that is a supertype of X.
It is defined as follows:

• ´⌈X⌉ = X´ if ´X´ is a simple type
• ´⌈X⌉ = ⌈U⌉´ if ´X´ is a stable type but not a simple type and its underlying type is ´U´
• ´⌈X⌉ = ⌈H⌉´ if ´X´ is a non-class type designator with upper bound ´H´
• ´⌈X⌉ = ⌈η(X)⌉´ if ´X´ is a polymorphic class type designator, where ´η(X)´ is its eta-expansion
• ´⌈X⌉ = ⌈Y⌉´ if ´X´ is a match type that reduces to ´Y´
• ´⌈X⌉ = ⌈H⌉´ if ´X´ is a match type that does not reduce and ´H´ is its upper bound
• ´⌈X[...T_i]⌉ = ⌈Y⌉´ where Y is the beta-reduction of ´X[...T_i]´ if ´X´ is a type lambda
• ´⌈X[...T_i]⌉ = ⌈⌈X⌉[...T_i]⌉´ if ´X´ is neither a type lambda nor a class type designator
• ´⌈X @a⌉ = ⌈X⌉´
• ´⌈X´ { ´R´ }´⌉ = ⌈X⌉´
• ´⌈´{ ´α´ => ´X´ }´ = ⌈X⌉⌉´
• ´⌈X_1 ＆ X_2⌉ = ⌈X_1⌉ ＆ ⌈X_2⌉´
• ´⌈X_1 ｜ X_2⌉ = ⌈X_1⌉ ｜ ⌈X_2⌉´
• ´⌈[...a_i]´ =>> ´X_1⌉ = [...a_i]´ =>> ´⌈X_1⌉´

The following properties hold about ´⌈X⌉´ (we have paper proofs for those):

• ´X <: ⌈X⌉´ for all type ´X´.
• If ´S <: T´, and the subtyping derivation does not use the "lower-bound rule" of ´<:´ anywhere, then ´⌈S⌉ <: ⌈T⌉´.

The "lower-bound rule" states that ´S <: T´ if ´T = q.X´ and ´q.X´ is a non-class type designator and ´S <: L´ where ´L´ is the lower bound of the underlying type definition of ´q.X´".
That rule is known to break transitivy of subtyping in Scala already.

Second, we define the relation ´⋔´ on classes (including traits, hidden classes of objects, and enum terms) as:

• ´C ⋔ D´ if ´C ∉´ baseClasses´(D)´ and ´D´ is final
• ´C ⋔ D´ if ´D ∉´ baseClasses´(C)´ and ´C´ is final
• ´C ⋔ D´ if there exists classes ´C' ∈´ baseClasses´(C)´ and ´D' ∈´ baseClasses´(D)´ such that ´C' ∉´ baseClasses´(D')´ and ´D' ∉´ baseClasses´(C')´.
• ´C ⋔ D´ if ´C´ is sealed without anonymous child and ´C_i ⋔ D´ for all direct children ´C_i´ of ´C´
• ´C ⋔ D´ if ´D´ is sealed without anonymous child and ´C ⋔ D_i´ for all direct children ´D_i´ of ´D´

We can now define ´⋔´ for types.

For arbitrary types ´X´ and ´Y´, we define ´X ⋔ Y´ as ´⌈X⌉ ⋔ ⌈Y⌉´.

Two simple types ´S´ and ´T´ are provably disjoint if there is a finite derivation tree for ´S ⋔ T´ using the following rules.
Most rules go by pair, which makes the whole relation symmetric:

• Nothing is disjoint from everything (including itself):
  • Nothing ´⋔ T´
  • ´S ⋔´ Nothing
• A union type is disjoint from another type if both of its parts are disjoint from that type:
  • ´S ⋔ T_1 ｜ T_2´ if ´S ⋔ T_1´ and ´S ⋔ T_2´
  • ´S_1 ｜ S_2 ⋔ T´ if ´S_1 ⋔ T´ and ´S_2 ⋔ T´
• An intersection type is disjoint from another type if at least one of its parts is disjoint from that type:
  • ´S ⋔ T_1 ＆ T_2´ if ´S ⋔ T_1´ or ´S ⋔ T_2´
  • ´S_1 ＆ S_2 ⋔ T´ if ´S_1 ⋔ T´ or ´S_1 ⋔ T´
• A type lambda is disjoint from any other type that is not a type lambda with the same number of parameters:
  • ´[...a_i]´ =>> ´S_1 ⋔ q.D.y´
  • ´[...a_i]´ =>> ´S_1 ⋔ d´
  • ´[...a_i]´ =>> ´S_1 ⋔ q.D[...T_i]´
  • ´p.C.x ⋔ [...b_i]´ =>> ´T_1´
  • ´c ⋔ [...b_i]´ =>> ´T_1´
  • ´p.C[...S_i] ⋔ [...b_i]´ =>> ´T_1´
  • ´[a_1, ..., a_n]´ =>> ´S_1 ⋔ [b_1, ..., b_m]´ =>> ´T_1´ if ´m \neq n´
• Two type lambdas with the same number of type parameters are disjoint if their result types are disjoint:
  • ´[a_1, ..., a_n]´ =>> ´S_1 ⋔ [b_1, ..., b_n]´ =>> ´T_1´ if ´S_1 ⋔ T_1´
• An enum value case is disjoint from any other enum value case (identified by either not being in the same enum class, or having a different name):
  • ´p.C.x ⋔ q.D.y´ if ´C \neq D´ or ´x \neq y´
• Two literal types are disjoint if they are different:
  • ´c ⋔ d´ if ´c \neq d´
• An enum value case is always disjoint from a literal type:
  • ´c ⋔ q.D.y´
  • ´p.C.x ⋔ d´
• An enum value case or a constant is disjoint from a class type if it does not extend that class (because it's essentially final):
  • ´p.C.x ⋔ q.D[...T_i]´ if baseType´(p.C.x, D)´ is not defined
  • ´p.C[...S_i] ⋔ q.D.y´ if baseType´(q.D.y, C)´ is not defined
  • ´c ⋔ q.D[...T_i]´ if baseType´(c, D)´ is not defined
  • ´p.C[...S_i] ⋔ d´ if baseType´(d, C)´ is not defined
• Two class types are disjoint if the classes themselves are disjoint, or if there exists a common super type with conflicting type arguments.
  • ´p.C[...S_i] ⋔ q.D[...T_i]´ if ´C ⋔ D´
  • ´p.C[...S_i] ⋔ q.D[...T_i]´ if there exists a class ´E´ such that baseType´(p.C[...S_i], E) = a.E[...A_i]´ and baseType´(q.D[...T_i], E) = b.E[...B_i]´ and there exists a pair ´(A_i, B_i)´ such that
    • ´A_i ⋔ B_i´ and it is in covariant position and there exists a field of that type parameter in ´E´, or
    • ´A_i ⋔ B_i´ and it is in invariant position, and:
      • there exists a field of that type parameter in ´E´, or
      • ´A_i´ cannot be instantiated to Nothing, or
      • ´B_i´ cannot be instantiated to Nothing.

It is worth noting that this definition disregards prefixes entirely.
´p.C´ and ´q.C´ are never provably disjoint, even if ´p´ could be proven disjoint from ´q´.
It also disregards type members.

We have a proof sketch of the following property for ´⋔´:

• If ´S <: T´ and ´T ⋔ U´, then ´S ⋔ U´.

This is a very desirable property.
It means that if we make the scrutinee of a match type more precise (a subtype) through substitution, and the match type previously reduced, then the match type will still reduce to the same case.

Note: if ´⋔´ were a "true" disjointness relationship, and not a provably-disjoint relationship, that property would trivially hold based on elementary set theoretic properties.
It would amount to proving that if ´S ⊆ T´ and ´T ⋂ U = ∅´, then ´S ⋂ U = ∅´.

Reduction

The result of reducing ´X´ match { case ´P_1´ => ´R_1; ...;´ case ´P_n´ => ´R_n´ } can be a type, undefined, or a compile error.

For ´n \geq 1´, it is specified as:

• If ´X´ matches ´P_1´ with type capture instantiations ´[...t_i \to t_i']´:
  • If ´X ⋔ P_1´, do not reduce.
  • Otherwise, reduce as ´[...t_i \to t_i']R_1´.
• Otherwise,
  • If ´X ⋔ P1´, the result of reducing ´X´ match { case ´P_2´ => ´R_2; ...;´ case ´P_n´ => ´R_n´ } (i.e., proceed with subsequent cases).
  • Otherwise, do not reduce.

The reduction of an "empty" match type ´X´ match { } (which cannot be written in user programs) is a compile error.

Skolem Types Copy Section

SkolemType  ::=  ‘∃‘ skolemid ‘:‘ Type

Skolem types cannot directly be written in the concrete syntax.
Moreover, although they are proper types, they can never be inferred to be part of the types of term definitions (vals, vars and defs).
They are exclusively used temporarily during subtyping derivations.

Skolem types are stable types.
A skolem type of the form ´∃ \alpha : T´ represents a stable reference to unknown value of type ´T´.
The identifier ´\alpha´ is chosen uniquely every time a skolem type is created.
However, as a skolem type is stable, it can be substituted in several occurrences in other types.
When "copied" through substitution, all the copies retain the same ´\alpha´, and are therefore equivalent.

Methodic Types Copy Chapter

TypeOrMethodic    ::=  Type
                    |  MethodicType
MethodicType      ::=  MethodType
                    |  PolyType

Methodic types are not real types.
They are not part of the type lattice.

However, they share some meta-properties with types.
In particular, when contained within other types that undertake some substitution, the substitution carries to the types within methodic types.
It is therefore often convenient to think about them as types themselves.

Methodic types are used as the "declared type" of def definitions that have at least one term or type parameter list.

Method Types Copy Section

MethodType        ::=  ‘(‘ MethodTypeParams ‘)‘ TypeOrMethodic
MethodTypeParams  ::=  ε
                    |  MethodTypeParam {‘,‘ MethodTypeParam}
MethodTypeParam   ::=  id ‘:‘ Type

A method type is denoted internally as ´(\mathit{Ps})U´, where ´(\mathit{Ps})´ is a sequence of parameter names and types ´(p_1:T_1, ..., p_n:T_n)´ for some ´n \geq 0´ and ´U´ is a (value or method) type.
This type represents named methods that take arguments named ´p_1, ..., p_n´ of types ´T_1, ..., T_n´ and that return a result of type ´U´.

Method types associate to the right: ´(\mathit{Ps}_1)(\mathit{Ps}_2)U´ is treated as ´(\mathit{Ps}_1)((\mathit{Ps}_2)U)´.

Method types do not exist as types of values.
If a method name is used as a value, its type is implicitly converted to a corresponding function type.

Example

The definitions

def a: Int
def b (x: Int): Boolean
def c (x: Int) (y: String, z: String): String

produce the typings

a: Int
b: (Int) Boolean
c: (Int) (String, String) String

Polymorphic Method Types Copy Section

PolyType          ::=  ‘[‘ PolyTypeParams ‘]‘ TypeOrMethodic
PolyTypeParams    ::=  PolyTypeParam {‘,‘ PolyTypeParam}
PolyTypeParam     ::=  ‘id‘ TypeBounds

A polymorphic method type, or poly type for short, is denoted internally as [´\mathit{tps}\,´]´T´ where [´\mathit{tps}\,´] is a type parameter section [´a_1´ >: ´L_1´ <: ´U_1, ..., a_n´ >: ´L_n´ <: ´U_n´] for some ´n \geq 0´ and ´T´ is a (value or method) type.
This type represents named methods that take type arguments ´S_1, ..., S_n´ which conform to the lower bounds ´L_1, ..., L_n´ and the upper bounds ´U_1, ..., U_n´ and that yield results of type ´T´.

Example

The definitions

def empty[A]: List[A]
def union[A <: Comparable[A]] (x: Set[A], xs: Set[A]): Set[A]

produce the typings

empty : [A >: Nothing <: Any] List[A]
union : [A >: Nothing <: Comparable[A]] (x: Set[A], xs: Set[A]) Set[A]

Operations on Types Copy Chapter

This section defines a few meta-functions on types and methodic types.

• baseType(´T´, ´C´): computes the smallest type ´U´ of the form ´p´.´C´[´T_1, ..., T_n´] such that ´T <: U´.
• asSeenFrom(´T´, ´C´, ´p´): rebases the type ´T´ visible inside the class ´C´ "as seen from" the prefix ´p´.
• memberType(´T´, ´id´): finds a member of a type (T.id) and computes its underlying type or bounds.

These meta-functions are mutually recursive.

Base Type Copy Section

The meta-function baseType(´T´, ´C´), where ´T´ is a proper type and ´C´ is a class identifier, computes the smallest type ´U´ of the form ´p.C´ or ´p.C´[´U_1, ..., U_n´] such that ´T <: U´.
If no such type exists, the function is not defined.
The main purpose of baseType is to substitute prefixes and class type parameters along the inheritance chain.

We define baseType(´T´, ´C´) as follows.
For brevity, we write ´p.X´[´U_1, ..., U_n´] instead of ´p.X´ with ´n = 0´.

• baseType(´T = p.C´[´T_1, ..., T_n´], ´C´) ´≜ T´
• baseType(´p.D´[´T_1, ..., T_n´], ´C´) with ´D´ ≠ ´C ≜ \sigma W´ if ´Q´ is defined where
  • ´D´ is declared as ´D[\pm a_1 >: L_1 <: H_1, ..., \pm a_n >: L_n <: H_n]´ extends ´P_1, ..., P_m´
  • ´Q =´ meet(baseType(´P_i´, ´C´) for all ´i´ such that baseType(´P_i´, ´C´) is defined)
  • ´W = Q´ if ´p = \epsilon´ or if ´p´ is a package ref; otherwise, ´W =´ asSeenFrom(´Q´, ´D´, ´p´) (in that case, ´p´ is a stable type and ´D´ must be declared inside another class ´B´)
  • ´\sigma = [a_1 := T_1, ..., a_n := T_n]´ the substitution of the declared type parameters of ´D´ by the actual type arguments
• baseType(´T_1 ＆ T_2´, ´C´) ´≜´ meet´(´baseType(´T_1´, ´C´), baseType(´T_2´, ´C´)´)´
• baseType(´T_1 ｜ T_2´, ´C´) ´≜´ join´(´baseType(´T_1´, ´C´), baseType(´T_2´, ´C´)´)´
• baseType(´T´, ´C´) ´≜´ baseType(superType(´T´), ´C´) if superType(´T´) is defined

The definition above uses the following helper functions.

superType(´T´) computes the "next upper bound" of ´T´, if it exists:

• superType(´T´) where ´T´ is a stable type is its underlying type
• superType(´p.X´) where ´p.X´ is a non-class type designator is the upper bound of its underlying type definition
• superType(´([a_1 >: L_1 <: H_1, ..., a_n >: L_n <: H_n]´ =>> ´U)[T_1, ..., T_n]´) is ´[a_1 =: T_1, ..., a_n := T_n]U´ (i.e., the beta-reduction of the type lambda redex)
• superType(´T[T_1, ..., T_n]´) is superType(´T´)´[T_1, ..., T_n]´ if superType(´T´) is defined

Note that the cases of superType do not overlap with each other nor with any baseType case other than the superType-based one.
The cases of baseType therefore do not overlap with each other either.
That makes baseType an algorithmic partial function.

meet(´p.C[T_1, ..., T_n]´, ´q.C[U_1, ..., U_n]´) computes an intersection of two (parameterized) class types for the same class, and join computes a union:

• if ´p =:= q´ is false, then it is not defined
• otherwise, let ´W_i´ for ´i \in 1, ..., n´ be:
  • ´T_i ＆ U_i´ for meet (resp. ´T_i ｜ U_i´ for join) if the ´i´th type parameter of ´C´ is covariant
  • ´T_i ｜ U_i´ for meet (resp. ´T_i ＆ U_i´ for join) if the ´i´th type parameter of ´C´ is contravariant
  • ´T_i´ if ´T_i =:= U_i´ and the ´i´th type parameter of ´C´ is invariant
  • not defined otherwise
• if any of the ´W_i´ are not defined, the result is not defined
• otherwise, the result is ´p.C[W_1, ..., W_n]´

We generalize meet(´T_1, ..., T_n´) for a sequence as:

• not defined for ´n = 0´
• ´T_1´ if ´n = 1´
• meet(meet(´T_1, ..., T_{n-1}´), ´T_n´) if meet(´T_1, ..., T_{n-1}´) is defined
• not defined otherwise

Examples

Given the following definitions:

trait Iterable[+A]
trait List[+A] extends Iterable[A]
trait Map[K, +V] extends Iterable[(K, V)]
trait Foo

we have the following baseType results:

• baseType(List[Int], List) = List[Int]
• baseType(List[Int], Iterable) = Iterable[Int]
• baseType(List[A] & Iterable[B], Iterable) = meet(Iterable[A], Iterable[B]) = Iterable[A & B]
• baseType(List[A] & Foo, Iterable) = Iterable[A] (because baseType(Foo, Iterable) is not defined)
• baseType(Int, Iterable) is not defined
• baseType(Map[Int, String], Iterable) = Iterable[(Int, String)]
• baseType(Map[Int, String] & Map[String, String], Map) is not defined (because K is invariant)

As Seen From Copy Section

The meta-function asSeenFrom(´T´, ´C´, ´p´), where ´T´ is a type or methodic type visible inside the class ´C´ and ´p´ is a stable type, rebases the type ´T´ "as seen from" the prefix ´p´.
Essentially, it substitutes this-types and class type parameters in ´T´ to appropriate types visible from outside.
Since T is visible inside ´C´, it can contain this-types and class type parameters of ´C´ itself as well as of all its enclosing classes.
This-types of enclosing classes must be mapped to appropriate subprefixes of ´p´, while class type parameters must be mapped to appropriate concrete type arguments.

asSeenFrom(´T´, ´C´, ´p´) only makes sense if ´p´ has a base type for ´C´, i.e., if baseType(´p´, ´C´) is defined.

We define asSeenFrom(´T´, ´C´, ´p´) where baseType(´p´, ´C´) = ´q.C[U_1, ..., U_n]´ as follows:

• If ´T´ is a reference to the ´i´th class type parameter of some class ´D´:
  • If baseType(´p´, ´D´) ´= r.D[W_1, ..., W_m]´ is defined, then ´W_i´
  • Otherwise, if ´q = \epsilon´ or ´q´ is a package ref, then ´T´
  • Otherwise, ´q´ is a type, ´C´ must be defined in another class ´B´ and baseType(´q´, ´B´) must be defined, then asSeenFrom(´T´, ´B´, ´q´)
• Otherwise, if ´T´ is a this-type ´D´.this:
  • If ´D´ is a subclass of ´C´ and baseType(´p´, ´D´) is defined, then ´p´ (this is always the case when ´D = C´)
  • Otherwise, if ´q = \epsilon´ or ´q´ is a package ref, then ´T´
  • Otherwise, ´q´ is a type, ´C´ must be defined in another class ´B´ and baseType(´q´, ´B´) must be defined, then asSeenFrom(´T´, ´B´, ´q´)
• Otherwise, ´T´ where each if of its type components ´T_i´ is mapped to asSeenFrom(´T_i´, ´C´, ´p´).

For convenience, we generalize asSeenFrom to type definitions ´D´.

• If ´D´ is an alias ´= U´, then asSeenFrom(´D´, ´C´, ´p´) = asSeenFrom(´U´, ´C´, ´p´).
• If ´D´ is an abstract type definition with bounds ´>: L <: H´, then asSeenFrom(´D´, ´C´, ´p´) = ´>:´ asSeenFrom(´L´, ´C´, ´p´) ´<:´ asSeenFrom(´H´, ´C´, ´p´).

Member Type Copy Section

The meta-function memberType(´T´, ´id´, ´p´), where ´T´ is a proper type, ´id´ is a term or type identifier, and ´p´ is a stable type, finds a member of a type (T.id) and computes its underlying type (for a term) or type definition (for a type) as seen from the prefix ´p´.
For a term, it also computes whether the term is stable.
memberType is the fundamental operation that computes the underlying type or underlying type definition of a named designator type.

The result ´M´ of a memberType is one of:

• undefined,
• a term result with underlying type or methodic type ´U´ and a stable flag,
• a class result with class ´C´, or
• a type result with underlying type definition ´D´.

As short-hand, we define memberType(´T´, ´id´) to be the same as memberType(´T´, ´id´, ´T´) when ´T´ is a stable type.

We define memberType(´T´, ´id´, ´p´) as follows:

• If ´T´ is a possibly parameterized class type of the form ´q.C[T_1, ..., T_n]´ (with ´n \geq 0´):
  • Let ´m´ be the class member of ´C´ with name ´id´.
  • If ´m´ is not defined, the result is undefined.
  • If ´m´ is a class definition, the result is a class result with class ´m´.
  • If ´m´ is a term definition in class ´D´ with declared type ´U´, the result is a term result with underlying type asSeenFrom(´U´, ´D´, ´p´) and stable flag true if and only if ´m´ is stable.
  • If ´m´ is a type member definition in class ´D´, the result is a type result with underlying type definition asSeenFrom(´U´, ´D´, ´p´) where ´U´ is defined as follows:
    • If ´m´ is an opaque type alias member definition with declared definition ´>: L <: H = V´, then
      • ´U´ is ´= V´ if ´p = D.´this or if we are computing memberType in a transparent mode,
      • ´U´ is ´>: L <: H´ otherwise.
    • ´U´ is the declared type definition of ´m´ otherwise.
• If ´T´ is another monomorphic type designator of the form ´q.X´:
  • Let ´U´ be memberType(´q´, ´X´)
  • Let ´H´ be the upper bound of ´U´
  • The result is memberType(´H´, ´id´, ´p´)
• If ´T´ is another parameterized type designator of the form ´q.X[T_1, ..., T_n]´ (with ´n \geq 0´):
  • Let ´U´ be memberType(´q´, ´X´)
  • Let ´H´ be the upper bound of ´U´
  • The result is memberType(´H[T_1, ..., T_n]´, ´id´, ´p´)
• If ´T´ is a parameterized type lambda of the form ´([\pm a_1 >: L_1 <: H_1, ..., \pm a_n >: L_n <: H_n]´ =>> ´U)[T_1, ..., T_n]´:
  • The result is memberType(´[a_1 := T_1, ..., a_n := T_n] U´, ´id´, ´p´), i.e., we beta-reduce the type redex.
• If ´T´ is a refined type of the form ´T_1´ { ´R´ }:
  • Let ´M_1´ be the result of memberType(´T_1´, ´id´, ´p´).
  • If the name of the refinement ´R´ is not ´id´, let ´M_2´ be undefined.
  • Otherwise, let ´M_2´ be the type or type definition of the refinement ´R´, as well as whether it is stable.
  • The result is mergeMemberType(´M_1´, ´M_2´).
• If ´T´ is a union type of the form ´T_1 ｜ T_2´:
  • Let ´J´ be the join of ´T´.
  • The result is memberType(´J´, ´id´, ´p´).
• If ´T´ is an intersection type of the form ´T_1 ＆ T_2´:
  • Let ´M_1´ be the result of memberType(´T_1´, ´id´, ´p´).
  • Let ´M_2´ be the result of memberType(´T_2´, ´id´, ´p´).
  • The result is mergeMemberType(´M_1´, ´M_2´).
• If ´T´ is a recursive type of the form { ´\alpha´ => ´T_1´ }:
  • The result is memberType(´T_1´, ´id´, ´p ´).
• If ´T´ is a stable type:
  • Let ´U´ be the underlying type of ´T´.
  • The result is memberType(´U´, ´id´, ´p´).
• Otherwise, the result is undefined.

We define the helper function mergeMemberType(´M_1´, ´M_2´) as:

• If either ´M_1´ or ´M_2´ is undefined, the result is the other one.
• Otherwise, if either ´M_1´ or ´M_2´ is a class result, the result is that one.
• Otherwise, ´M_1´ and ´M_2´ must either both be term results or both be type results.
  • If they are term results with underlying types ´U_1´ and ´U_2´ and stable flags ´s_1´ and ´s_2´, the result is a term result whose underlying type is meet(´U_1´, ´U_2´) and whose stable flag is ´s_1 \lor s_2´.
  • If they are type results with underlying type definitions ´D_1´ and ´D_2´, the result is a type result whose underlying type definition is intersect(´D_1´, ´D_2´).

Relations between types Copy Chapter

We define the following relations between types.

Conformance Copy Section

The conformance relation ´(<:)´ is the smallest relation such that ´S <: T´ is true if any of the following conditions hold.
Note that the conditions are not all mutually exclusive.

• ´S = T´ (i.e., conformance is reflexive by definition).
• ´S´ is Nothing.
• ´T´ is AnyKind.
• ´S´ is a stable type with underlying type ´S_1´ and ´S_1 <: T´.
• ´S = p.x´ and ´T = q.x´ are term designators and
  • isSubPrefix(´p´, ´q´).
• ´S = p.X[S_1, ..., S_n]´ and ´T = q.X[T_1, ..., T_n]´ are possibly parameterized type designators with ´n \geq 0´ and:
  • isSubPrefix(´p´, ´q´), and
  • it is not the case that ´p.x´ and ´q.X´ are class type designators for different classes, and
  • for each ´i \in { 1, ..., n }´:
    • the ´i´th type parameter of ´q.X´ is covariant and ´S_i <: T_i´ [^argisnotwildcard], or
    • the ´i´th type parameter of ´q.X´ is contravariant and ´T_i <: S_i´ [^argisnotwildcard], or
    • the ´i´th type parameter of ´q.X´ is invariant and:
      • ´S_i´ and ´T_i´ are types and ´S_i =:= T_i´, or
      • ´S_i´ is a type and ´T_i´ is a wildcard type argument of the form ´? >: L_2 <: H_2´ and ´L_2 <: S_i´ and ´S_i <: H_2´, or
      • ´S_i´ is a wildcard type argument of the form ´? >: L_1 <: H_1´ and ´T_i´ is a wildcard type argument of the form ´? >: L_2 <: H_2´ and ´L_2 <: L_1´ and ´H_1 <: H_2´ (i.e., the ´S_i´ "interval" is contained in the ´T_i´ "interval").
• ´T = q.C[T_1, ..., T_n]´ with ´n \geq 0´ and baseType(´S´, ´C´) is defined and baseType(´S´, ´C´) ´<: T´.
• ´S = p.X[S_1, ..., S_n]´ and ´p.X´ is non-class type designator and ´H <: T´ where ´H´ is the upper bound of the underlying type definition of ´p.X´.
• ´S = p.C´ and ´T = C´.this and ´C´ is the hidden class of an object and:
  • ´p = \epsilon´ or ´p´ is a package ref, or
  • isSubPrefix(´p´, ´D´.this) where ´D´ is the enclosing class of ´C´.
• ´S = C´.this and ´T = q.C´ and ´C´ is the hidden class of an object and:
  • either ´q = \epsilon´ or ´q´ is a package ref, or
  • isSubPrefix(´D´.this, ´q´) where ´D´ is the enclosing class of ´C´.
• ´S = S_1 ｜ S_2´ and ´S_1 <: T´ and ´S_2 <: T´.
• ´T = T_1 ｜ T_2´ and either ´S <: T_1´ or ´S <: T_2´.
• ´T = T_1 ＆ T_2´ and ´S <: T_1´ and ´S <: T_2´.
• ´S = S_1 ＆ S_2´ and either ´S_1 <: T´ or ´S_2 <: T´.
• ´S = S_1´ @a and ´S_1 <: T´.
• ´T = T_1´ @a and ´S <: T_1´ (i.e., annotations can be dropped).
• ´T = q.X´ and ´q.X´ is a non-class type designator and ´S <: L´ where ´L´ is the lower bound of the underlying type definition of ´q.X´.
• ´S = p.X´ and ´p.X´ is a non-class type designator and ´H <: T´ where ´H´ is the upper bound of the underlying type definition of ´p.X´.
• ´S = [\pm a_1 >: L_1 <: H_1, ..., \pm a_n >: L_n <: H_n]´ =>> ´S_1´ and ´T = [\pm b_1 >: M_1 <: G_1, ..., \pm b_n >: M_n <: G_n]´ =>> ´T_1´, and given ´\sigma = [b_1 := a_1, ..., b_n := a_n]´:
  • ´S_1 <: \sigma T_1´, and
  • for each ´i \in { 1, ..., n }´:
    • the variance of ´a_i´ conforms to the variance of ´b_i´ (´+´ conforms to ´+´ and ´\epsilon´, ´-´ conforms to ´-´ and ´\epsilon´, and ´\epsilon´ conforms to ´\epsilon´), and
    • ´\sigma (>: M_i <: G_i)´ is contained in ´>: L_i <: H_i´ (i.e., ´L_i <: \sigma M_i´ and ´\sigma G_i <: H_i´).
• ´S = p.X´ and ´T = [\pm b_1 >: M_1 <: G_1, ..., \pm b_n >: M_n <: G_n]´ =>> ´T_1´ and ´S´ is a type constructor with ´n´ type parameters and:
  • ´([\pm a_1 >: L_1 <: H_1, ..., \pm a_n >: L_n <: H_n]´ =>> ´S[a_1, ..., a_n]) <: T´ where the ´a_i´ are copies of the type parameters of ´S´ (i.e., we can eta-expand ´S´ to compare it to a type lambda).
• ´T = T_1´ { ´R´ } and ´S <: T_1´ and, given ´p = S´ if ´S´ is a stable type and ´p = ∃ \alpha : S´ otherwise:
  • ´R =´ type ´X >: L <: H´ and memberType(´p´, ´X´) is a class result for ´C´ and ´L <: p.C´ and ´p.C <: H´, or
  • ´R =´ type ´X >: L_2 <: H_2´ and memberType(´p´, ´X´) is a type result with bounds ´>: L_1 <: H_1´ and ´L_2 <: L_1´ and ´H_1 <: H_2´, or
  • ´R =´ val ´X: T_2´ and memberType(´p´, ´X´) is a stable term result with type ´S_2´ and ´S_2 <: T_2´, or
  • ´R =´ def ´X: T_2´ and memberType(´p´, ´X´) is a term result with type ´S_2´ and ´T_2´ is a type and ´S_2 <: T_2´, or
  • ´R =´ def ´X: T_2´ and memberType(´p´, ´X´) is a term result with methodic type ´S_2´ and ´T_2´ is a methodic type and matches(´S_2´, ´T_2´).
• ´S = S_1´ { ´R´ } and ´S_1 <: T´.
• ´S =´ { ´\alpha´ => ´S_1´ } and ´T =´ { ´\beta´ => ´T_1´ } and ´S_1 <: [\beta := \alpha]T_1´.
• ´T =´ { ´\beta´ => ´T_1´ } and ´S´ is a proper type but not a recursive type and ´p' <: [\beta := p]T_1´ where:
  • ´p´ is ´S´ if ´S´ is a stable type and ´∃ \alpha : S´ otherwise, and
  • ´p'´ is the result of replacing any top-level recursive type { ´\gamma´ => ´Z´ } in ´p´ with ´[\gamma := p]Z´ (TODO specify this better).
• ´(X´ match <: ´H´ { ... }´) <: T´ if ´X´ match ... reduces to ´S_1´ and ´S_1 <: T´
• ´S <: (X´ match <: ´H´ { ... }´)´ if ´X´ match ... reduces to ´T_1´ and ´S <: T_1´
• ´(X´ match <: ´H´ { ... }´) <: T´ if ´H <: T´
• ´(X´ match <: ´H_X´ { case ´P_1´ => ´A_1´; ...; case ´P_n´ => ´A_n´ }´) <: (Y´ match <: ´H_Y´ { case ´Q_1´ => ´B_1´; ...; ´Q_n´ => ´B_n´ }´)´ if ´X =:= Y´ and ´P_i =:= Q_i´ for each ´i´ and ´A_i <: B_i´ for each ´i´
• ´S = (´=> ´S_1)´ and ´T = (´=> ´T_1)´ and ´S_1 <: T_1´.
• ´S =´ scala.Null and:
  • ´T = q.C[T_1, ..., T_n]´ with ´n \geq 0´ and ´C´ does not derive from scala.AnyVal and ´C´ is not the hidden class of an object, or
  • ´T = q.x´ is a term designator with underlying type ´U´ and scala.Null ´<: U´, or
  • ´T = T_1´ { ´R´ } and scala.Null ´<: T_1´, or
  • ´T =´ { ´\beta´ => ´T_1´ } and scala.Null ´<: T_1´.
• ´S´ is a stable type and ´T = q.x´ is a term designator with underlying type ´T_1´ and ´T_1´ is a stable type and ´S <: T_1´.
• ´S = S_1´ { ´R´ } and ´S_1 <: T´.
• ´S =´ { ´\alpha´ => ´S_1´ } and ´S_1 <: T´.
• ´T =´ scala.Tuple´_n[T_1, ..., T_n]´ with ´1 \leq n \leq 22´, and ´S <: T_1´ *: ... *: ´T_n´ *: scala.EmptyTuple.

We define isSubPrefix(´p´, ´q´) where ´p´ and ´q´ are prefixes as:

• If both ´p´ and ´q´ are types, then ´p <: q´.
• Otherwise, ´p = q´ (for empty prefixes and package refs).

We define matches(´S´, ´T´) where ´S´ and ´T´ are types or methodic types as:

• If ´S´ and ´T´ are types, then ´S <: T´.
• If ´S´ and ´T´ are method types ´(a_1: S_1, ..., a_n: S_n)S'´ and ´(b_1: T_1, ..., b_n: T_n)T'´, then ´\sigma S_i =:= T_i´ for each ´i´ and matches(´\sigma S'´, ´T'´), where ´\sigma = [a_1 := b_1, ..., a_n := b_n]´.
• If ´S´ and ´T´ are poly types ´[a_1 >: L_{s1} <: H_{s1}, ..., a_n >: L_{sn} <: H_{sn}]S'´ and ´[b_1 >: L_{t1} <: H_{t1}, ..., b_n >: L_{tn} <: H_{tn}]T'´, then ´\sigma L_{si} =:= L_{ti}´ and ´\sigma H_{si} =:= H_{ti}´ for each ´i´ and matches(´\sigma S'´, ´T'´), where ´\sigma = [a_1 := b_1, ..., a_n := b_n]´.

Note that conformance in Scala is not transitive.
Given two abstract types ´A´ and ´B´, and one abstract type ´C >: A <: B´ available on prefix ´p´, we have ´A <: p.C´ and ´C <: p.B´ but not necessarily ´A <: B´.

[^argisnotwildcard]: In these cases, if T_i and/or U_i are wildcard type arguments, the simplification rules for parameterized types allow to reduce them to real types.

Least upper bounds and greatest lower bounds

The ´(<:)´ relation forms pre-order between types, i.e. it is transitive and reflexive.
This allows us to define least upper bounds and greatest lower bounds of a set of types in terms of that order.

• the least upper bound of A and B is the smallest type L such that A <: L and B <: L.
• the greatest lower bound of A and B is the largest type G such that G <: A and G <: B.

By construction, for all types A and B, the least upper bound of A and B is A ｜ B, and their greatest lower bound is A ＆ B.

Equivalence Copy Section

Equivalence is defined as mutual conformance.

´S =:= T´ if and only if both ´S <: T´ and ´T <: S´.

Weak Conformance Copy Section

In some situations Scala uses a more general conformance relation.
A type ´S´ weakly conforms to a type ´T´, written ´S <:_w T´, if ´S <: T´ or both ´S´ and ´T´ are primitive number types and ´S´ precedes ´T´ in the following ordering.

Byte  ´<:_w´ Short
Short ´<:_w´ Int
Char  ´<:_w´ Int
Int   ´<:_w´ Long
Long  ´<:_w´ Float
Float ´<:_w´ Double

A weak least upper bound is a least upper bound with respect to weak conformance.

Compatibility Copy Section

A type ´T´ is compatible to a type ´U´ if ´T´ (or its corresponding function type) weakly conforms to ´U´ after applying eta-expansion.
If ´T´ is a method type, it's converted to the corresponding function type.
If the types do not weakly conform, the following alternatives are checked in order:

• dropping by-name modifiers: if ´U´ is of the shape ´=> U'´ (and ´T´ is not), ´T <:_w U'´;
• SAM conversion: if ´T´ corresponds to a function type, and ´U´ declares a single abstract method whose type corresponds to the function type ´U'´, ´T <:_w U'´.
• implicit conversion: there's an implicit conversion from ´T´ to ´U´ in scope;

Examples

Function compatibility via SAM conversion

Given the definitions

def foo(x: Int => String): Unit
def foo(x: ToString): Unit

trait ToString { def convert(x: Int): String }

The application foo((x: Int) => x.toString) resolves to the first overload, as it's more specific:

• Int => String is compatible to ToString -- when expecting a value of type ToString, you may pass a function literal from Int to String, as it will be SAM-converted to said function;
• ToString is not compatible to Int => String -- when expecting a function from Int to String, you may not pass a ToString.

Realizability Copy Chapter

A type ´T´ is realizable if and only if it is inhabited by non-null values.
It is defined as:

• A term designator ´p.x´ with underlying type ´U´ is realizable if ´p´ is ´\epsilon´ or a package ref or a realizable type and
  • memberType(´p´, ´x´) has the stable flag, or
  • the type returned by memberType(´p´, ´x´) is realizable.
• A stable type that is not a term designator is realizable.
• Another type ´T´ is realizable if
  • ´T´ is concrete, and
  • ´T´ has good bounds.

A concrete type ´T´ has good bounds if all of the following apply:

• all its non-class type members have good bounds, i.e., their bounds ´L´ and ´H´ are such that ´L <: H´,
• all its type refinements have good bounds, and
• for all base classes ´C´ of ´T´:
  • baseType(´T´, ´C´) is defined with some result ´p.C[T_1, ..., T_n]´, and
  • for all ´i \in { 1, ..., n }´, ´T_i´ is a real type or (when it is a wildcard type argument) it has good bounds.

Note: it is possible for baseType(´T´, ´C´) not to be defined because of the meet computation, which may fail to merge prefixes and/or invariant type arguments.

Type Erasure Copy Chapter

A type is called generic if it contains type arguments or type variables.
Type erasure is a mapping from (possibly generic) types to non-generic types.
We write ´|T|´ for the erasure of type ´T´.
The erasure mapping is defined as follows.
Internal computations are performed in a transparent mode, which has an effect on how memberType behaves for opaque type aliases.

• The erasure of AnyKind is Object.
• The erasure of a non-class type designator is the erasure of its underlying upper bound.
• The erasure of a term designator is the erasure of its underlying type.
• The erasure of the parameterized type scala.Array´[T_1]´ is scala.Array´[|T_1|]´.
• The erasure of every other parameterized type ´T[T_1, ..., T_n]´ is ´|T|´.
• The erasure of a stable type ´p´ is the erasure of the underlying type of ´p´.
• The erasure of a by-name type => ´T_1´ is scala.Function0.
• The erasure of an annotated type ´T_1 a´ is ´|T_1|´.
• The erasure of a refined type ´T_1´ { ´R´ } is ´|T_1|´.
• The erasure of a recursive type { ´\alpha´ => ´T_1´ } and the associated recursive this type ´\alpha´ is ´|T_1|´.
• The erasure of a union type ´S ｜ T´ is the erased least upper bound (elub) of the erasures of ´S´ and ´T´.
• The erasure of an intersection type ´S ＆ T´ is the eglb (erased greatest lower bound) of the erasures of ´S´ and ´T´.

The erased LUB is computed as follows:

• if both argument are arrays of objects, an array of the erased LUB of the element types
• if both arguments are arrays of same primitives, an array of this primitive
• if one argument is array of primitives and the other is array of objects, Object
• if one argument is an array, Object
• otherwise a common superclass or trait S of the argument classes, with the following two properties:
  • S is minimal: no other common superclass or trait derives from S, and
  • S is last: in the linearization of the first argument type ´|A|´ there are no minimal common superclasses or traits that come after S.
    The reason to pick last is that we prefer classes over traits that way, which leads to more predictable bytecode and (?) faster dynamic dispatch.

The rules for ´eglb(A, B)´ are given below in pseudocode:

eglb(scala.Array[A], JArray[B]) = scala.Array[eglb(A, B)]
eglb(scala.Array[T], _)         = scala.Array[T]
eglb(_, scala.Array[T])         = scala.Array[T]
eglb(A, B)                      = A                     if A extends B
eglb(A, B)                      = B                     if B extends A
eglb(A, _)                      = A                     if A is not a trait
eglb(_, B)                      = B                     if B is not a trait
eglb(A, _)                      = A                     // use first

Spec 04 Basic Definitions (`docs/_spec/04-basic-definitions.md`) Copy Section

title: Basic Definitions layout: default chapter: 4 Copy Chapter

Basic Definitions

PatVarDef   ::=  ‘val’ PatDef
              |  ‘var’ VarDef
Def         ::=  PatVarDef
              |  ‘def’ FunDef
              |  ‘type’ {nl} TypeDef
              |  ‘opaque‘ ‘type‘ {nl} OpaqueTypeDef
              |  TmplDef

A definition introduces names that denote terms and assigns them types, or that denote types and assigns them type definitions.
It can form part of an object or class definition or it can be local to a block.

The scope of a name introduced by a definition is the whole statement sequence containing the definition.
However, there is a restriction on forward references in blocks:
In a statement sequence ´s_1 ... s_n´ making up a block, if a simple name in ´s_i´ refers to an entity defined by ´s_j´ where ´j \geq i´, then for all ´s_k´ between and including ´s_i´ and ´s_j´,

• ´s_k´ cannot be a variable definition.
• If ´s_k´ is a value definition, it must be lazy.

Moreover, in a block, all term definitions must be concrete, and opaque type alias definitions are not allowed.

Value Definitions Copy Chapter

PatVarDef    ::=  ‘val’ PatDef
PatDef       ::=  Pattern2 {‘,’ Pattern2} [‘:’ Type] [‘=’ Expr]
ids          ::=  id {‘,’ id}

An abstract value definition val ´x´: ´T´ introduces ´x´ as a name of a value of declared type ´T´.
´T´ must be explicitly specified and must be a proper type.

A concrete value definition val ´x´: ´T´ = ´e´ defines ´x´ as a name of the value that results from the evaluation of ´e´.
If the value definition is not recursive, the declared type ´T´ may be omitted, in which case the packed type of the expression ´e´ is assumed.
If a type ´T´ is given, then it must be a proper type and ´e´ is expected to conform to it.

Evaluation of the value definition implies evaluation of its right-hand side ´e´, unless it has the modifier lazy.
The effect of the value definition is to bind ´x´ to the value of ´e´ converted to type ´T´.
A lazy value definition evaluates its right hand side ´e´ the first time the value is accessed.

A constant value definition is of the form

final val x = e

where e is a constant expression.
The final modifier must be present and no type annotation may be given.
References to the constant value x are themselves treated as constant expressions; in the generated code they are replaced by the definition's right-hand side e.

Concrete value definitions can alternatively have a pattern as left-hand side.
If ´p´ is some pattern other than a simple name or a name followed by a colon and a type, then the value definition val ´p´ = ´e´ is expanded as follows:

1. If the pattern ´p´ has bound variables ´x_1, ..., x_n´, where ´n > 1´:

val ´\$x´ = ´e´ match {case ´p´ => (´x_1, ..., x_n´)}
val ´x_1´ = ´\$x´._1
...
val ´x_n´ = ´\$x´._n

Here, ´$x´ is a fresh name.

2. If ´p´ has a unique bound variable ´x´:

val ´x´ = ´e´ match { case ´p´ => ´x´ }

3. If ´p´ has no bound variables:

´e´ match { case ´p´ => () }

Example

The following are examples of value definitions

val foo: Int              // abstract value definition
val pi = 3.1415
val pi: Double = 3.1415   // equivalent to first definition
val Some(x) = f()         // a pattern definition
val x :: xs = mylist      // an infix pattern definition

The last two definitions have the following expansions.

val x = f() match { case Some(x) => x }

val x´\$´ = mylist match { case x :: xs => (x, xs) }
val x = x´\$´._1
val xs = x´\$´._2

The name of any defined value may not end in _=.

A value definition val ´x_1, ..., x_n´: ´T´ is a shorthand for the sequence of value definitions val ´x_1´: ´T´; ...; val ´x_n´: ´T´.
A value definition val ´p_1, ..., p_n´ = ´e´ is a shorthand for the sequence of value definitions val ´p_1´ = ´e´; ...; val ´p_n´ = ´e´.
A value definition val ´p_1, ..., p_n: T´ = ´e´ is a shorthand for the sequence of value definitions val ´p_1: T´ = ´e´; ...; val ´p_n: T´ = ´e´.

Variable Definitions Copy Chapter

Dcl            ::=  ‘var’ VarDcl
PatVarDef      ::=  ‘var’ VarDef
VarDcl         ::=  ids ‘:’ Type
VarDef         ::=  PatDef
                 |  ids ‘:’ Type ‘=’ ‘_’

An abstract variable definition var ´x´: ´T´ is equivalent to the definition of both a getter method ´x´ and a setter method ´x´_=:

def ´x´: ´T´
def ´x´_= (´y´: ´T´): Unit

An implementation of a class may implement a defined abstract variable using a concrete variable definition, or by defining the corresponding setter and getter methods.

A concrete variable definition var ´x´: ´T´ = ´e´ introduces a mutable variable with type ´T´ and initial value as given by the expression ´e´.
The type ´T´ can be omitted, in which case the type of ´e´ is assumed.
If ´T´ is given, then it must be a proper type and ´e´ is expected to conform to it.

Variable definitions can alternatively have a pattern as left-hand side.
A variable definition var ´p´ = ´e´ where ´p´ is a pattern other than a simple name or a name followed by a colon and a type is expanded in the same way as a value definition val ´p´ = ´e´, except that the free names in ´p´ are introduced as mutable variables, not values.

The name of any defined variable may not end in _=.

The right-hand-side of a mutable variable definition that is a member of a template can be the special reference scala.compiletime.uninitialized: var ´x´: ´T´ = scala.compiletime.uninitialized.
It introduces a mutable field with type ´T´ and a default initial value.
The default value depends on the type ´T´ as follows:

scala.compiletime.uninitialized can never appear anywhere else.
For compatibility with Scala 2, the syntax var ´x´: ´T´ = _ is accepted as equivalent to using uninitialized.

When they occur as members of a template, both forms of concrete variable definition also introduce a setter method ´x´_= which changes the value currently assigned to the variable.
The setter has the same signatures as for an abstract variable definition.
It is then not possible to directly modify the value assigned to the variable; mutations always go through the corresponding setter.

Example

The following example shows how properties can be simulated in Scala.
It defines a class TimeOfDayVar of time values with updatable integer fields representing hours, minutes, and seconds.
Its implementation contains tests that allow only legal values to be assigned to these fields.
The user code, on the other hand, accesses these fields just like normal variables.

class TimeOfDayVar {
  private var h: Int = 0
  private var m: Int = 0
  private var s: Int = 0

  def hours              =  h
  def hours_= (h: Int)   =  if (0 <= h && h < 24) this.h = h
                            else throw new DateError()

  def minutes            =  m
  def minutes_= (m: Int) =  if (0 <= m && m < 60) this.m = m
                            else throw new DateError()

  def seconds            =  s
  def seconds_= (s: Int) =  if (0 <= s && s < 60) this.s = s
                            else throw new DateError()
}
val d = new TimeOfDayVar
d.hours = 8; d.minutes = 30; d.seconds = 0
d.hours = 25                  // throws a DateError exception

A variable definition var ´x_1, ..., x_n´: ´T´ is a shorthand for the sequence of variable definitions var ´x_1´: ´T´; ...; var ´x_n´: ´T´.
A variable definition var ´x_1, ..., x_n´ = ´e´ is a shorthand for the sequence of variable definitions var ´x_1´ = ´e´; ...; var ´x_n´ = ´e´.
A variable definition var ´x_1, ..., x_n: T´ = ´e´ is a shorthand for the sequence of variable definitions var ´x_1: T´ = ´e´; ...; var ´x_n: T´ = ´e´.

Type Member Definitions Copy Chapter

Dcl             ::=  ‘type’ {nl} TypeDcl
TypeDcl         ::=  id [TypeParamClause] [‘>:’ Type] [‘<:’ Type]
Def             ::=  ‘type’ {nl} TypeDef
                  |  ‘opaque‘ ‘type‘ {nl} OpaqueTypeDef
TypeDef         ::=  id [TypeParamClause] ‘=’ Type
                  |  id [TypeParamClause] ‘<:’ Type ‘=’ MatchType
OpaqueTypeDef   ::=  id [TypeParamClause] [‘>:’ Type] [‘<:’ Type] ‘=’ Type

Type members can be abstract type members, type aliases, or opaque type aliases.

A possibly parameterized abstract type member definition type ´t´[´\mathit{tps}\,´] >: ´L´ <: ´H´ declares ´t´ to be an abstract type.
If omitted, ´L´ and ´H´ are implied to be Nothing and scala.Any, respectively.

A possibly parameterized type alias definition type ´t´[´\mathit{tps}\,´] = ´T´ defines ´t´ to be a concrete type member.
The alternative type ´t´[´\mathit{tps}\,´] <: ´H´ = ´T´ match { ´Cs´ } desugars to type ´t´[´\mathit{tps}\,´] = (´T´ match { ´Cs´ } <: ´H´), i.e., a match type with an upper bound, which cannot otherwise be expressed in the concrete syntax.

A possibly parameterized opaque type alias definition opaque type ´t´[´\mathit{tps}\,´] >: ´L´ <: ´H´ = ´T´ defines ´t´ to be an opaque type alias with public bounds >: ´L´ <: ´H´ and a private alias = ´T´.

If a type parameter clause [´\mathit{tps}\,´] is present, it is desugared away according to the rules in the following section.

Desugaring of parameterized type definitions Copy Section

A parameterized type definition is desugared into an unparameterized type definition whose bounds are type lambdas with explicit variance annotations.

The scope of a type parameter extends over the bounds >: ´L´ <: ´U´ or the alias = ´T´ and the type parameter clause ´\mathit{tps}´ itself.
A higher-order type parameter clause (of an abstract type constructor ´tc´) has the same kind of scope, restricted to the definition of the type parameter ´tc´.

To illustrate nested scoping, these definitions are all equivalent: type t[m[x] <: Bound[x], Bound[x]], type t[m[x] <: Bound[x], Bound[y]] and type t[m[x] <: Bound[x], Bound[_]], as the scope of, e.g., the type parameter of ´m´ is limited to the definition of ´m´.
In all of them, ´t´ is an abstract type member that abstracts over two type constructors: ´m´ stands for a type constructor that takes one type parameter and that must be a subtype of Bound, ´t´'s second type constructor parameter.
t[MutableList, Iterable] is a valid use of ´t´.

Abstract Type

A parameterized abstract type

type ´t´[´\mathit{tps}\,´] >: ´L´ <: ´H´

is desugared into an unparameterized abstract type as follows:

• If L conforms to Nothing, then,

  scala Copy

type ´t´ >: Nothing
<: [´\mathit{tps'},´] =>> ´H´

- otherwise,

```scala
type ´t´ >: [´\mathit{tps'}\,´] =>> ´L´
     <: [´\mathit{tps'}\,´] =>> ´H´

If at least one of the ´\mathit{tps}´ contains an explicit variance annotation, then ´\mathit{tps'} = \mathit{tps}´, otherwise we infer the variance of each type parameter as with the user-written type lambda [´\mathit{tps}\,´] =>> ´H´.

The same desugaring applies to type parameters.
For instance,

[F[X] <: Coll[X]]

is treated as a shorthand for

[F >: Nothing <: [X] =>> Coll[X]]

Type Alias

A parameterized type alias

type ´t´[´\mathit{tps}\,´] = ´T´

is desugared into an unparameterized type alias

type ´t´ = [´\mathit{tps'}\,´] =>> ´T´

where ´\mathit{tps'}´ is computed as in the previous case.

Opaque Type Alias

A parameterized type alias

type ´t´[´\mathit{tps}\,´] >: ´L´ <: ´H´ = ´T´

is desugared into an unparameterized opaque type alias as follows:

• If L conforms to Nothing, then,

  scala Copy

type ´t´ >: Nothing <: [´\mathit{tps'},´] =>> ´H´ = [´\mathit{tps'},´] =>> ´T´

- otherwise,

```scala
type ´t´ >: [´\mathit{tps'}\,´] =>> ´L´ <: [´\mathit{tps'}\,´] =>> ´H´ = [´\mathit{tps'}\,´] =>> ´T´

where ´\mathit{tps'}´ is computed as in the previous cases.

Non-Parameterized Type Member Definitions Copy Section

An abstract type member definition type ´t´ >: ´L´ <: ´H´ declares ´t´ to be an abstract type whose type definition has the lower bound type ´L´ and upper bound type ´H´.

If a type definition appears as a member definition of a type, implementations of the type may implement ´t´ with any type ´T´ for which ´L <: T <: H´.
It is a compile-time error if ´L´ does not conform to ´H´.

A type alias definition type ´t´ = ´T´ defines ´t´ to be an alias name for the type ´T´.

An opaque type alias definition opaque type ´t´ >: ´L´ <: ´H´ = ´T´ defines ´t´ to be an opaque type alias with public bounds >: ´L´ <: ´H´ and a private alias = ´T´.
An opaque type alias can only be declared within a template.
It cannot be private and cannot be overridden in subclasses.
In order for the definition to be valid, ´T´ must satisfy some constraints:

• ´L <: T´ and ´T <: H´ must be true,
• ´T´ must not be a context function type, and
• If ´T´ is a type lambda, its result must be a proper type (i.e., it cannot be a curried type lambda).

When viewed from within its enclosing template, an opaque type alias behaves as a type alias with type definition = ´T´.
When viewed from anywhere else, it behaves as an abstract type member with type definition >: ´L´ <: ´H´.
See memberType for the precise mechanism that governs this dual view.

The scope rules for definitions and type parameters make it possible that a type name appears in its own bounds or in its right-hand side.
However, it is a static error if a type alias refers recursively to the defined type itself.
That is, the type ´T´ in a type alias type ´t´[´\mathit{tps}\,´] = ´T´ may not refer directly or indirectly to the name ´t´.
It is also an error if an abstract type is directly or indirectly its own upper or lower bound.

Example

The following are legal type definitions:

type IntList = List[Integer]
type T <: Comparable[T]
type Two[A] = Tuple2[A, A] // desugars to Two = [A] =>> Tuple2[A, A]
type MyCollection[+X] <: Iterable[X] // desugars to MyCollection <: [+X] =>> Iterable[X]

The following are illegal:

type Abs = Comparable[Abs]      // recursive type alias

type S <: T                     // S, T are bounded by themselves.
type T <: S

type T >: Comparable[T.That]    // Cannot select from T.
                                // T is a type, not a value
type MyCollection <: Iterable   // The reference to the type constructor
                                // Iterable must explicitly state its type arguments.

If a type alias type ´t´ = ´S´ refers to a class type ´S´ (or to a type lambda that is the eta-expansion of class type ´S´), the name ´t´ can also be used as a constructor for objects of type ´S´.

Example

Suppose we make Pair an alias of the parameterized class Tuple2, as follows:

type Pair[+A, +B] = Tuple2[A, B]
object Pair {
  def apply[A, B](x: A, y: B) = Tuple2(x, y)
  def unapply[A, B](x: Tuple2[A, B]): Option[Tuple2[A, B]] = Some(x)
}

As a consequence, for any two types ´S´ and ´T´, the type Pair[´S´, ´T\,´] is equivalent to the type Tuple2[´S´, ´T\,´].
Pair can also be used as a constructor instead of Tuple2, as in:

val x: Pair[Int, String] = new Pair(1, "abc")

Type Parameters Copy Chapter

TypeParamClause  ::= ‘[’ VariantTypeParam {‘,’ VariantTypeParam} ‘]’
VariantTypeParam ::= {Annotation} [‘+’ | ‘-’] TypeParam
TypeParam        ::= (id | ‘_’) [TypeParamClause] [‘>:’ Type] [‘<:’ Type] [‘:’ Type]

Type parameters appear in type definitions, class definitions, and method definitions.
In this section we consider only type parameter definitions with lower bounds >: ´L´ and upper bounds <: ´U´ whereas a discussion of context bounds : ´U´ and view bounds <% ´U´ is deferred to here.

The most general form of a proper type parameter is
´@a_1 ... @a_n´ ´\pm´ ´t´ >: ´L´ <: ´U´.
Here, ´L´, and ´U´ are lower and upper bounds that constrain possible type arguments for the parameter.
It is a compile-time error if ´L´ does not conform to ´U´.
´\pm´ is a variance, i.e. an optional prefix of either +, or -. One or more annotations may precede the type parameter.

The names of all type parameters must be pairwise different in their enclosing type parameter clause.
The scope of a type parameter includes in each case the whole type parameter clause.
Therefore it is possible that a type parameter appears as part of its own bounds or the bounds of other type parameters in the same clause.
However, a type parameter may not be bounded directly or indirectly by itself.

A type constructor parameter adds a nested type parameter clause to the type parameter.
The most general form of a type constructor parameter is ´@a_1 ... @a_n \pm t[\mathit{tps}\,]´ >: ´L´ <: ´U´.

The above scoping restrictions are generalized to the case of nested type parameter clauses, which declare higher-order type parameters.
Higher-order type parameters (the type parameters of a type parameter ´t´) are only visible in their immediately surrounding parameter clause (possibly including clauses at a deeper nesting level) and in the bounds of ´t´.
Therefore, their names must only be pairwise different from the names of other visible parameters.
Since the names of higher-order type parameters are thus often irrelevant, they may be denoted with a ‘_’, which is nowhere visible.

Example

Here are some well-formed type parameter clauses:

[S, T]
[@specialized T, U]
[Ex <: Throwable]
[A <: Comparable[B], B <: A]
[A, B >: A, C >: A <: B]
[M[X], N[X]]
[M[_], N[_]] // equivalent to previous clause
[M[X <: Bound[X]], Bound[_]]
[M[+X] <: Iterable[X]]

The following type parameter clauses are illegal:

[A >: A]                  // illegal, `A' has itself as bound
[A <: B, B <: C, C <: A]  // illegal, `A' has itself as bound
[A, B, C >: A <: B]       // illegal lower bound `A' of `C' does
                          // not conform to upper bound `B'.

Variance Annotations Copy Chapter

Variance annotations indicate how instances of parameterized types vary with respect to subtyping.
A ‘+’ variance indicates a covariant dependency, a ‘-’ variance indicates a contravariant dependency, and a missing variance indication indicates an invariant dependency.

A variance annotation constrains the way the annotated type variable may appear in the type or class which binds the type parameter.
In a type definition type ´T´[´\mathit{tps}\,´] = ´S´, type ´T´[´\mathit{tps}\,´] >: ´L´ <: ´U´ or opaque type ´T´[´\mathit{tps}\,´] >: ´L´ <: ´U´ = ´S´, type parameters labeled ‘+’ must only appear in covariant position whereas type parameters labeled ‘-’ must only appear in contravariant position.
Analogously, for a class definition class ´C´[´\mathit{tps}\,´](´\mathit{ps}\,´) extends ´T´ { ´x´: ´S´ => ...}, type parameters labeled ‘+’ must only appear in covariant position in the self type ´S´ and the template ´T´, whereas type parameters labeled ‘-’ must only appear in contravariant position.

The variance position of a type parameter in a type or template is defined as follows.
Let the opposite of covariance be contravariance, and the opposite of invariance be itself.
The top-level of the type or template is always in covariant position.
The variance position changes at the following constructs.

• The variance position of a method parameter is the opposite of the variance position of the enclosing parameter clause.
• The variance position of a type parameter is the opposite of the variance position of the enclosing type parameter clause.
• The variance position of the lower bound of a type definition or type parameter is the opposite of the variance position of the type definition or parameter.
• The type of a mutable variable is always in invariant position.
• The right-hand side of a type alias is always in invariant position.
• The prefix ´p´ of a type selection ´p.T´ is always in invariant position.
• For a type argument ´T´ of a type ´S´[´..., T, ...´]:
  • If the corresponding type parameter of ´S´ is invariant, then ´T´ is in invariant position.
  • If the corresponding type parameter of ´S´ is contravariant, the variance position of ´T´ is the opposite of the variance position of the enclosing type ´S´[´..., T, ...´].

References to the type parameters in object-private values, types, variables, or methods of the class are not checked for their variance position.
In these members the type parameter may appear anywhere without restricting its legal variance annotations.

Example

The following variance annotation is legal.

abstract class P[+A, +B] {
  def fst: A
  def snd: B
}

With this variance annotation, type instances of ´P´ subtype covariantly with respect to their arguments.
For instance,

P[IOException, String] <: P[Throwable, AnyRef]

If the members of ´P´ are mutable variables, the same variance annotation becomes illegal.

abstract class Q[+A, +B](x: A, y: B) {
  var fst: A = x           // **** error: illegal variance:
  var snd: B = y           // `A', `B' occur in invariant position.
}

If the mutable variables are object-private, the class definition becomes legal again:

abstract class R[+A, +B](x: A, y: B) {
  private var fst: A = x        // OK
  private var snd: B = y        // OK
}

Example

The following variance annotation is illegal, since ´A´ appears in contravariant position in the parameter of append:

abstract class Sequence[+A] {
  def append(x: Sequence[A]): Sequence[A]
                  // **** error: illegal variance:
                  // `A' occurs in contravariant position.
}

The problem can be avoided by generalizing the type of append by means of a lower bound:

abstract class Sequence[+A] {
  def append[B >: A](x: Sequence[B]): Sequence[B]
}

Example

abstract class OutputChannel[-A] {
  def write(x: A): Unit
}

With that annotation, we have that OutputChannel[AnyRef] conforms to OutputChannel[String].
That is, a channel on which one can write any object can substitute for a channel on which one can write only strings.

Method Definitions Copy Chapter

Def                ::=  ‘def’ FunDef
FunDef             ::=  FunSig [‘:’ Type] [‘=’ Expr]
FunSig             ::=  id [FunTypeParamClause] ParamClauses
FunTypeParamClause ::=  ‘[’ TypeParam {‘,’ TypeParam} ‘]’
ParamClauses       ::=  {ParamClause} [[nl] ‘(’ ‘implicit’ Params ‘)’]
ParamClause        ::=  [nl] ‘(’ [Params] ‘)’
Params             ::=  Param {‘,’ Param}
Param              ::=  {Annotation} id [‘:’ ParamType] [‘=’ Expr]
ParamType          ::=  Type
                     |  ‘=>’ Type
                     |  Type ‘*’

An abstract method definition has the form def ´f\,\mathit{psig}´: ´T´, where ´f´ is the method's name, ´\mathit{psig}´ is its parameter signature and ´T´ is its result type.
A concrete method definition def ´f\,\mathit{psig}´: ´T´ = ´e´ also includes a method body ´e´, i.e. an expression which defines the method's result.
A parameter signature consists of an optional type parameter clause [´\mathit{tps}\,´], followed by zero or more value parameter clauses (´\mathit{ps}_1´)...(´\mathit{ps}_n´).

If there is no type or term parameter clause, a method definition introduces a method with a proper type, which is also its result type.
Otherwise, it introduces a method with a methodic type whose parameter types and result type are as given.

The type of the method body is expected to conform to the method's declared result type, if one is given.
If the method definition is not recursive, the result type may be omitted, in which case it is determined from the packed type of the method body.

A type parameter clause ´\mathit{tps}´ consists of one or more type definitions, which introduce type parameters, possibly with bounds.
The scope of a type parameter includes the whole signature, including any of the type parameter bounds as well as the method body, if it is present.

A value parameter clause ´\mathit{ps}´ consists of zero or more formal parameter bindings such as ´x´: ´T´ or ´x: T = e´, which bind value parameters and associate them with their types.

A unary operator must not have explicit parameter lists even if they are empty.
A unary operator is a method named "unary_´op´" where ´op´ is one of +, -, !, or ~.

Default Arguments Copy Section

Each value parameter may optionally define a default argument.
The default argument expression ´e´ is type-checked with an expected type ´T'´ obtained by replacing all occurrences of the method's type parameters in ´T´ by the undefined type.

For every parameter ´p_{i,j}´ with a default argument, a method named ´f\$´default´\$´n is generated which computes the default argument expression.
Here, ´n´ denotes the parameter's position in the method definition.
These methods are parametrized by the type parameter clause [´\mathit{tps}\,´] and all value parameter clauses (´\mathit{ps}_1´)...(´\mathit{ps}_{i-1}´) preceding ´p_{i,j}´.
The ´f\$´default´\$´n methods are inaccessible for user programs.

Example

In the method

def compare[T](a: T = 0)(b: T = a) = (a == b)

the default expression 0 is type-checked with an undefined expected type.
When applying compare(), the default value 0 is inserted and T is instantiated to Int.
The methods computing the default arguments have the form:

def compare´\$´default´\$´1[T]: Int = 0
def compare´\$´default´\$´2[T](a: T): T = a

The scope of a formal value parameter name ´x´ comprises all subsequent parameter clauses, as well as the method return type and the method body, if they are given.
Both type parameter names and value parameter names must be pairwise distinct.

A default value which depends on earlier parameters uses the actual arguments if they are provided, not the default arguments.

def f(a: Int = 0)(b: Int = a + 1) = b // OK
// def f(a: Int = 0, b: Int = a + 1)  // "error: not found: value a"
f(10)()                               // returns 11 (not 1)

If an implicit argument is not found by implicit search, it may be supplied using a default argument.

implicit val i: Int = 2
def f(implicit x: Int, s: String = "hi") = s * x
f                                     // "hihi"

By-Name Parameters Copy Section

ParamType          ::=  ‘=>’ Type

The type of a value parameter may be prefixed by =>, e.g. ´x´: => ´T´.
The type of such a parameter is then the by-name type => ´T´.
This indicates that the corresponding argument is not evaluated at the point of method application, but instead is evaluated at each use within the method.
That is, the argument is evaluated using call-by-name.

The by-name modifier is disallowed for parameters of classes that carry a val or var prefix, including parameters of case classes for which a val prefix is implicitly generated.

Example

The definition

def whileLoop (cond: => Boolean) (stat: => Unit): Unit

indicates that both parameters of whileLoop are evaluated using call-by-name.

Repeated Parameters Copy Section

ParamType          ::=  Type ‘*’

The last value parameter of a parameter section may be suffixed by '*', e.g. (..., ´x´:´T´*).
The type of such a repeated parameter inside the method is then the sequence type scala.Seq[´T´].
Methods with repeated parameters ´T´* take a variable number of arguments of type ´T´.
That is, if a method ´m´ with type (´p_1:T_1, ..., p_n:T_n, p_s:S´*)´U´ is applied to arguments ´(e_1, ..., e_k)´ where ´k \geq n´, then ´m´ is taken in that application to have type ´(p_1:T_1, ..., p_n:T_n, p_s:S, ..., p_{s'}:S)U´, with ´k - n´ occurrences of type ´S´ where any parameter names beyond ´p_s´ are fresh. The only exception to this rule is if the last argument is marked to be a sequence argument via a _* type annotation.
If ´m´ above is applied to arguments (´e_1, ..., e_n, e'´: _*), then the type of ´m´ in that application is taken to be (´p_1:T_1, ... , p_n:T_n,p_{s}:´scala.Seq[´S´]).

It is not allowed to define any default arguments in a parameter section with a repeated parameter.

Example

The following method definition computes the sum of the squares of a variable number of integer arguments.

def sum(args: Int*) = {
  var result = 0
  for (arg <- args) result += arg
  result
}

The following applications of this method yield 0, 1, 6, in that order.

sum()
sum(1)
sum(1, 2, 3)

Furthermore, assume the definition:

val xs = List(1, 2, 3)

The following application of method sum is ill-formed:

sum(xs)       // ***** error: expected: Int, found: List[Int]

By contrast, the following application is well formed and yields again the result 6:

sum(xs: _*)

Method Return Type Inference Copy Section

A class member definition ´m´ that overrides some other method ´m'´ in a base class of ´C´ may leave out the return type, even if it is recursive.
In this case, whether or not m is recursive, its return type will be the return type of ´m'´.

Example

Assume the following definitions:

trait I {
  def factorial(x: Int): Int
}
class C extends I {
  def factorial(x: Int) = if (x == 0) 1 else x * factorial(x - 1)
}

Here, it is OK to leave out the result type of factorial in C, even though the method is recursive.

Tail-Recursive Call Elimination Copy Section

Method definitions which contain self-recursive invocations in tail position are optimized for stack safety.
Self-invocations which are the last operation before returning from the method are replaced with jumps to the beginning of the method, much as in a while loop.
Sibling-invocations, in which a method calls itself but with a different instance as receiver, are also optimized.

This transform is performed automatically by the compiler whenever possible.
A method definition bearing the annotation, scala.annotation.tailrec, will fail to compile if the transform is not possible.
(The annotation is intended for cases where deoptimization would likely result in a stack overflow.)

@annotation.tailrec
def sum(xs: List[Int], acc: Int): Int =
  xs match { case h :: t => sum(t, acc + h) case _ => acc }

Import Clauses Copy Chapter

Import            ::=  ‘import’ ImportExpr {‘,’ ImportExpr}
ImportExpr        ::= SimpleRef {‘.’ id} ‘.’ ImportSpecifier
                    | SimpleRef `as` id
ImportSpecifier   ::=  NamedSelector
                    |  WildcardSelector
                    | ‘{’ ImportSelectors ‘}’
NamedSelector     ::=  id [(‘as’ | ’=>’) (id | ‘_’)]
WildcardSelector  ::=  ‘*’ | ’_’ | ‘given’ [InfixType]
ImportSelectors   ::=  NamedSelector [‘,’ ImportSelectors]
                    |  WildCardSelector {‘,’ WildcardSelector}

• In a NamedSelector, => can only be used when inside an ImportSelectors and is then equivalent to as, to be deprecated in the future.
• In a WildcardSelector, _ is equivalent to *, to be deprecated in the future.

An ImportSpecifier that is a single NamedSelector or WildcardSelector is equivalent to an ‘{‘ ImportSelectors ‘}‘ list with that single selector.

An import clause with multiple import expressions import ´p_1´.´I_1, ..., p_n´.´I_n´ is interpreted as a sequence of import clauses import ´p_1´.´I_1´; ...; import ´p_n´.´I_n´.

An import clause with a single import expression has the form import ´p´.´I´ where ´p´ is a prefix and ´I´ is an import specifier.
The import specifier determines a set of names of importable members of ´p´ which are made available without qualification as well as a set of importable given members which are made available in the implicit scope.
A member ´m´ of ´p´ is importable if it is accessible.
The most general form of an import specifier is a list of import selectors

{ ´x_1´ as ´y_1, ..., x_n´ as ´y_n´, *, given ´T_1´, ..., given ´T_m´, given }

for ´n \geq 0´ and ´m \geq 0´, where the wildcards ‘*’ and ’given’ may be absent.
They are decomposed into non-given selectors and given selectors.

Non-given Imports Copy Section

Non-given selectors make available each importable member ´p´.´x_i´ under the unqualified name ´y_i´.
In other words, every import selector ´x_i´ as ´y_i´ renames ´p´.´x_i´ to ´y_i´.
When as ´y_i´ is omitted, ´y_i´ is assumed to be ´x_i´.
If a final wildcard ‘*’ is present, all non-given importable members ´z´ of ´p´ other than ´x_1, ..., x_n, y_1, ..., y_n´ are also made available under their own unqualified names.

Non-given import selectors work in the same way for type and term members.
For instance, an import clause import ´p´.´x´ as ´y´ renames the term name ´p´.´x´ to the term name ´y´ and the type name ´p´.´x´ to the type name ´y´.
At least one of these two names must reference an importable member of ´p´.

If the target in an import selector is an underscore as _, the import selector hides access to the source member instead of importing it.
For instance, the import selector ´x´ as _ “renames” ´x´ to the underscore symbol (which is not accessible as a name in user programs), and thereby effectively prevents unqualified access to ´x´.
This is useful if there is a final wildcard in the same import selector list, which imports all members not mentioned in previous import selectors.

The scope of a binding introduced by a non-given import clause starts immediately after the import clause and extends to the end of the enclosing block, template, package clause, or compilation unit, whichever comes first.

Given Imports Copy Section

Given selectors make available in the implicit scope all the importable given and implicit members ´p´.´x´ such that ´p.x´ is a subtype of ´T_i´.
A bare given selector without type is equivalent to given scala.Any.

The names of the given members are irrelevant for the selection, and are not made available in the normal scope of unqualified names.

Example

Consider the object definition:

object M {
  def z = 0
  def one = 1
  def add(x: Int, y: Int): Int = x + y
}

Then the block

{
  import M.{one, z as zero, *}
  add(zero, one)
}

is equivalent to the block

{
  M.add(M.z, M.one)
}

Spec 05 Classes And Objects (`docs/_spec/05-classes-and-objects.md`) Copy Section

title: Classes & Objects layout: default chapter: 5 Copy Chapter

Classes and Objects

TmplDef          ::= [‘case’] ‘class’ ClassDef
                  |  [‘case’] ‘object’ ObjectDef
                  |  ‘trait’ TraitDef

Classes and objects are both defined in terms of templates.

Templates Copy Chapter

ClassTemplate   ::=  [EarlyDefs] ClassParents [TemplateBody]
TraitTemplate   ::=  [EarlyDefs] TraitParents [TemplateBody]
ClassParents    ::=  Constr {‘with’ AnnotType}
TraitParents    ::=  AnnotType {‘with’ AnnotType}
TemplateBody    ::=  [nl] ‘{’ [SelfType] TemplateStat {semi TemplateStat} ‘}’
SelfType        ::=  id [‘:’ Type] ‘=>’
                 |   this ‘:’ Type ‘=>’

A template defines the type signature, behavior and initial state of a trait or class of objects or of a single object.
Templates form part of instance creation expressions, class definitions, and object definitions.
A template ´sc´ with ´mt_1´ with ... with ´mt_n´ { ´\mathit{stats}´ } consists of a constructor invocation ´sc´ which defines the template's superclass, trait references ´mt_1, ..., mt_n´ ´(n \geq 0)´, which define the template's traits, and a statement sequence ´\mathit{stats}´ which contains initialization code and additional member definitions for the template.

Each trait reference ´mt_i´ must denote a trait.
By contrast, the superclass constructor ´sc´ normally refers to a class which is not a trait.
It is possible to write a list of parents that starts with a trait reference, e.g. ´mt_1´ with ... with ´mt_n´.
In that case the list of parents is implicitly extended to include the supertype of ´mt_1´ as the first parent type.
The new supertype must have at least one constructor that does not take parameters.
In the following, we will always assume that this implicit extension has been performed, so that the first parent class of a template is a regular superclass constructor, not a trait reference.

The list of parents of a template must be well-formed.
This means that the class denoted by the superclass constructor ´sc´ must be a subclass of the superclasses of all the traits ´mt_1, ..., mt_n´.
In other words, the non-trait classes inherited by a template form a chain in the inheritance hierarchy which starts with the template's superclass.

It is forbidden for a template's superclass constructor ´sc´ to be an enum class, unless the template is the implementation of an enum case of ´sc´.

The least proper supertype of a template is the class type or compound type consisting of all its parent class types.

The statement sequence ´\mathit{stats}´ contains member definitions that define new members or overwrite members in the parent classes.
If the template forms part of an abstract class or trait definition, the statement part ´\mathit{stats}´ may also contain definitions of abstract members.
If the template forms part of a concrete class definition, ´\mathit{stats}´ may still contain definitions of abstract type members, but not of abstract term members.
Furthermore, ´\mathit{stats}´ may in any case also contain expressions; these are executed in the order they are given as part of the initialization of a template.

The sequence of template statements may be prefixed with a formal parameter definition and an arrow, e.g. ´x´ =>, or ´x´:´T´ =>.
If a formal parameter is given, it can be used as an alias for the reference this throughout the body of the template.
If the formal parameter comes with a type ´T´, this definition affects the self type ´S´ of the underlying class or object as follows:
Let ´C´ be the type of the class or trait or object defining the template.
If a type ´T´ is given for the formal self parameter, ´S´ is the greatest lower bound of ´T´ and ´C´.
If no type ´T´ is given, ´S´ is just ´C´.
Inside the template, the type of this is assumed to be ´S´.

The self type of a class or object must conform to the self types of all classes which are inherited by the template ´t´.

A second form of self type annotation reads just this: ´S´ =>.
It prescribes the type ´S´ for this without introducing an alias name for it.

Example

Consider the following class definitions:

class Base extends Object {}
trait Mixin extends Base {}
object O extends Mixin {}

In this case, the definition of O is expanded to:

object O extends Base with Mixin {}

Inheriting from Java Types

A template may have a Java class as its superclass and Java interfaces as its mixins.

Template Evaluation

Consider a template ´sc´ with ´mt_1´ with ´mt_n´ { ´\mathit{stats}´ }.

If this is the template of a trait then its mixin-evaluation consists of an evaluation of the statement sequence ´\mathit{stats}´.

If this is not a template of a trait, then its evaluation consists of the following steps.

• First, the superclass constructor ´sc´ is
  evaluated.
• Then, all base classes in the template's linearization up to the template's superclass denoted by ´sc´ are evaluated.
  evaluation happens in reverse order of occurrence in the linearization. Each evaluation occurs as follows:
  • First, arguments to ´mt_i´ are evaluated from left to right, and set as parameters of ´mt_i´.
  • ´mt_i´ is then mixin-evaluated.
• Finally, the statement sequence ´\mathit{stats},´ is evaluated.

Constructor Invocations Copy Section

Constr  ::=  AnnotType {‘(’ [Exprs] ‘)’}

Constructor invocations define the type, members, and initial state of objects created by an instance creation expression, or of parts of an object's definition which are inherited by a class or object definition.
A constructor invocation is a method application ´x´.´c´[´\mathit{targs}´](´\mathit{args}_1´)...(´\mathit{args}_n´), where ´x´ is a stable identifier, ´c´ is a type name which either designates a class or defines an alias type for one, ´\mathit{targs}´ is a type argument list, ´\mathit{args}_1, ..., \mathit{args}_n´ are argument lists, and there is a constructor of that class which is applicable to the given arguments.
If the constructor invocation uses named or default arguments, it is transformed into a block expression using the same transformation as described here.

The prefix ´x´. can be omitted.
A type argument list can be given only if the class ´c´ takes type parameters.
Even then it can be omitted, in which case a type argument list is synthesized using local type inference.
If no explicit arguments are given, an empty list () is implicitly supplied.

An evaluation of a constructor invocation ´x´.´c´[´\mathit{targs}´](´\mathit{args}_1´)...(´\mathit{args}_n´) consists of the following steps:

• First, the prefix ´x´ is evaluated.
• Then, the arguments ´\mathit{args}_1, ..., \mathit{args}_n´ are evaluated from left to right.
• Finally, the class being constructed is initialized by evaluating the template of the class referred to by ´c´.

Class Linearization Copy Section

The classes reachable through transitive closure of the direct inheritance relation from a class ´C´ are called the base classes of ´C´.
Because of mixins, the inheritance relationship on base classes forms in general a directed acyclic graph.
A linearization of this graph is defined as follows.

Definition: linearization

Let ´C´ be a class with template ´C_1´ with ... with ´C_n´ { ´\mathit{stats}´ }`.
The linearization of ´C´, ´\mathcal{L}(C)´ is defined as follows:
$$
\mathcal{L}(C) = C, \mathcal{L}(C_n) ; \vec{+} ; ... ; \vec{+} ; \mathcal{L}(C_1)
$$

Here ´\vec{+}´ denotes concatenation where elements of the right operand replace identical elements of the left operand:

$$
\begin{array}{lcll}
{a, A} ;\vec{+}; B &=& a, (A ;\vec{+}; B) &{\bf if} ; a \not\in B \\
&=& A ;\vec{+}; B &{\bf if} ; a \in B
\end{array}
$$

Example

Consider the following class definitions.

abstract class AbsIterator extends AnyRef { ... }
trait RichIterator extends AbsIterator { ... }
class StringIterator extends AbsIterator { ... }
class Iter extends StringIterator with RichIterator { ... }

Then the linearization of class Iter is

{ Iter, RichIterator, StringIterator, AbsIterator, AnyRef, Any }

Note that the linearization of a class refines the inheritance relation: if ´C´ is a subclass of ´D´, then ´C´ precedes ´D´ in any linearization where both ´C´ and ´D´ occur.
Linearization also satisfies the property that a linearization of a class always contains the linearization of its direct superclass as a suffix.

For instance, the linearization of StringIterator is

{ StringIterator, AbsIterator, AnyRef, Any }

which is a suffix of the linearization of its subclass Iter.
The same is not true for the linearization of mixins.
For instance, the linearization of RichIterator is

{ RichIterator, AbsIterator, AnyRef, Any }

which is not a suffix of the linearization of Iter.

Class Members Copy Section

A class ´C´ defined by a template ´C_1´ with ... with ´C_n´ { ´\mathit{stats}´ } can define members in its statement sequence ´\mathit{stats}´ and can inherit members from all parent classes.
Scala adopts Java and C#'s conventions for static overloading of methods.
It is thus possible that a class defines and/or inherits several methods with the same name.
To decide whether a defined member of a class ´C´ overrides a member of a parent class, or whether the two co-exist as overloaded variants in ´C´, Scala uses the following definition of matching on members:

Definition: matching

A member definition ´M´ matches a member definition ´M'´, if ´M´ and ´M'´ bind the same name, and one of following holds.

1. Neither ´M´ nor ´M'´ is a method definition.
2. ´M´ and ´M'´ define both monomorphic methods with equivalent argument types.
3. ´M´ is defined in Java and defines a method with an empty parameter list () and ´M'´ defines a parameterless method.
4. ´M´ and ´M'´ define both polymorphic methods with equal number of argument types ´\overline T´, ´\overline T'´ and equal numbers of type parameters ´\overline t´, ´\overline t'´, say, and ´\overline T' = [\overline t'/\overline t]\overline T´.

Member definitions fall into two categories: concrete and abstract.
Members of class ´C´ are either directly defined (i.e. they appear in ´C´'s statement sequence ´\mathit{stats}´) or they are inherited.
There are two rules that determine the set of members of a class, one for each category:

A concrete member of a class ´C´ is any concrete definition ´M´ in some class ´C_i \in \mathcal{L}(C)´, except if there is a preceding clas ´C_j \in \mathcal{L}(C)´ where ´j < i´ which directly defines a concrete member ´M'´ matching ´M´.

An abstract member of a class ´C´ is any abstract definition ´M´ in some class ´C_i \in \mathcal{L}(C)´, except if ´C´ contains already a concrete member ´M'´ matching ´M´, or if there is a preceding class ´C_j \in \mathcal{L}(C)´ where ´j < i´ which directly defines an abstract member ´M'´ matching ´M´.

This definition also determines the overriding relationships between matching members of a class ´C´ and its parents.
First, a concrete definition always overrides an abstract definition.
Second, for definitions ´M´ and ´M´' which are both concrete or both abstract, ´M´ overrides ´M'´ if ´M´ appears in a class that precedes (in the linearization of ´C´) the class in which ´M'´ is defined.

It is an error if a template directly defines two matching members.
It is also an error if a template contains two members (directly defined or inherited) with the same name and the same erased type.
Finally, a template is not allowed to contain two methods (directly defined or inherited) with the same name which both define default arguments.

Example

Consider the trait definitions:

trait A { def f: Int }
trait B extends A { def f: Int = 1 ; def g: Int = 2 ; def h: Int = 3 }
trait C extends A { override def f: Int = 4 ; def g: Int }
trait D extends B with C { def h: Int }

Then trait D has a directly defined abstract member h.
It inherits member f from trait C and member g from trait B.

Overriding Copy Section

A member ´M´ of class ´C´ that matches a non-private member ´M'´ of a base class of ´C´ is said to override that member.
In this case the binding of the overriding member ´M´ must subsume the binding of the overridden member ´M'´.
Furthermore, the following restrictions on modifiers apply to ´M´ and ´M'´:

• ´M'´ must not be a class.

• ´M'´ must not be labeled final.

• ´M´ must not be private.

• If ´M´ is labeled private[´C´] for some enclosing class or package ´C´, then ´M'´ must be labeled private[´C'´] for some class or package ´C'´ where ´C'´ equals ´C´ or ´C'´ is contained in ´C´.

• If ´M´ is labeled protected, then ´M'´ must also be labeled protected.

• If ´M'´ is not an abstract member, then ´M´ must be labeled override.
  Furthermore, one of two possibilities must hold:

  • either ´M´ is defined in a subclass of the class where is ´M'´ is defined,
  • or both ´M´ and ´M'´ override a third member ´M''´ which is defined in a base class of both the classes containing ´M´ and ´M'´

• If ´M'´ is incomplete in ´C´ then ´M´ must be labeled abstract override.

• If ´M´ and ´M'´ are both concrete value definitions, then either none of them is marked lazy or both must be marked lazy.

• A stable member can only be overridden by a stable member.
  For example, this is not allowed:

class X { val stable = 1}
class Y extends X { override var stable = 1 } // error

Another restriction applies to abstract type members:
An abstract type member with a volatile type as its upper bound may not override an abstract type member which does not have a volatile upper bound.

A special rule concerns parameterless methods.
If a parameterless method defined as def ´f´: ´T´ = ... or def ´f´ = ... overrides a method defined in Java of type ´()T'´ which has an empty parameter list, then ´f´ is also assumed to have an empty parameter list.

An overriding method inherits all default arguments from the definition in the superclass.
By specifying default arguments in the overriding method it is possible to add new defaults (if the corresponding parameter in the superclass does not have a default) or to override the defaults of the superclass (otherwise).

Example

Consider the definitions:

trait Root { type T <: Root }
trait A extends Root { type T <: A }
trait B extends Root { type T <: B }
trait C extends A with B

Then the class definition C is not well-formed because the binding of T in C is type T <: B, which fails to subsume the binding type T <: A of T
in type A.
The problem can be solved by adding an overriding definition of type T in class C:

class C extends A with B { type T <: C }

Inheritance Closure Copy Section

Let ´C´ be a class type.
The inheritance closure of ´C´ is the smallest set ´\mathscr{S}´ of types such that

• ´C´ is in ´\mathscr{S}´.
• If ´T´ is in ´\mathscr{S}´, then every type ´T'´ which forms syntactically a part of ´T´ is also in ´\mathscr{S}´.
• If ´T´ is a class type in ´\mathscr{S}´, then all parents of ´T´ are also in ´\mathscr{S}´.

It is a static error if the inheritance closure of a class type consists of an infinite number of types.
(This restriction is necessary to make subtyping decidable[^kennedy]).

[^kennedy]: Kennedy, Pierce. On Decidability of Nominal Subtyping with Variance. in FOOL 2007

Modifiers Copy Chapter

Modifier          ::=  LocalModifier
                    |  AccessModifier
                    |  ‘override’
LocalModifier     ::=  ‘abstract’
                    |  ‘final’
                    |  ‘sealed’
                    |  ‘implicit’
                    |  ‘lazy’
                    |  ‘infix’
AccessModifier    ::=  (‘private’ | ‘protected’) [AccessQualifier]
AccessQualifier   ::=  ‘[’ (id | ‘this’) ‘]’

Member definitions may be preceded by modifiers which affect the accessibility and usage of the identifiers bound by them.
If several modifiers are given, their order does not matter, but the same modifier may not occur more than once.
Modifiers preceding a repeated definition apply to all constituent definitions.
The rules governing the validity and meaning of a modifier are as follows.

`private` Copy Section

The private modifier can be used with any definition in a template.
Private members of a template can be accessed only from within the directly enclosing template and its companion module or companion class.

The private modifier is also valid for top-level templates.

A private modifier can be qualified with an identifier ´C´ (e.g. private[´C´]) that must denote a class or package enclosing the definition.
Members labeled with such a modifier are accessible respectively only from code inside the package ´C´ or only from code inside the class ´C´ and its companion module.

A different form of qualification is private[this].
A member ´M´ marked with this modifier is called object-protected; it can be accessed only from within the object in which it is defined.
That is, a selection ´p.M´ is only legal if the prefix is this or ´O´.this, for some class ´O´ enclosing the reference.
In addition, the restrictions for unqualified private apply.

Members marked private without a qualifier are called class-private, whereas members labeled with private[this] are called object-private.
A member is private if it is either class-private or object-private, but not if it is marked private[´C´] where ´C´ is an identifier; in the latter case the member is called qualified private.

Class-private or object-private members may not be abstract, and may not have protected or override modifiers.
They are not inherited by subclasses and they may not override definitions in parent classes.

`protected` Copy Section

The protected modifier applies to class member definitions.
Protected members of a class can be accessed from within

• the template of the defining class,
• all templates that have the defining class as a base class,
• the companion module of any of those classes.

A protected modifier can be qualified with an identifier ´C´ (e.g. protected[´C´]) that must denote a class or package enclosing the definition.
Members labeled with such a modifier are also accessible respectively from all code inside the package ´C´ or from all code inside the class ´C´ and its companion module.

A protected identifier ´x´ may be used as a member name in a selection ´r´.´x´ only if one of the following applies:

• The access is within the template defining the member, or, if a qualification ´C´ is given, inside the package ´C´, or the class ´C´, or its companion module, or
• ´r´ is one of the reserved words this and super, or
• ´r´'s type conforms to a type-instance of the class which contains the access.

A different form of qualification is protected[this].
A member ´M´ marked with this modifier is called object-protected; it can be accessed only from within the object in which it is defined. That is, a selection ´p.M´ is only legal if the prefix is this or ´O´.this, for some class ´O´ enclosing the reference. In addition, the restrictions for unqualified protected apply.

`override` Copy Section

The override modifier applies to class member definitions which are not themselves classes.
It is mandatory for member definitions that override some other concrete member definition in a parent class.
If an override modifier is given, there must be at least one overridden member definition (either concrete or abstract).

`abstract override` Copy Section

The override modifier has an additional significance when combined with the abstract modifier.
That modifier combination is only allowed for value members of traits.

We call a member ´M´ of a template incomplete if it is either abstract, or it is labeled abstract and override and every member overridden by ´M´ is again incomplete.

Note that the abstract override modifier combination does not influence the concept whether a member is concrete or abstract.

`abstract` Copy Section

The abstract modifier is used in class definitions.
It is redundant for traits, and mandatory for all other classes which have incomplete members.
Abstract classes cannot be instantiated with a constructor invocation unless followed by mixins and/or a refinement which override all incomplete members of the class.
Only abstract classes and traits can have abstract term members.

The abstract modifier can also be used in conjunction with override for class member definitions.
In that case the previous discussion applies.

`final` Copy Section

The final modifier applies to class member definitions and to class definitions.
A final class member definition may not be overridden in subclasses.
A final class may not be inherited by a template.
final is redundant for object definitions.
Members of final classes or objects are implicitly also final, so the final modifier is generally redundant for them, too.
Note, however, that constant value definitions do require an explicit final modifier, even if they are defined in a final class or object.
final is permitted for abstract classes but it may not be applied to traits or incomplete members, and it may not be combined in one modifier list with sealed.

`sealed` Copy Section

The sealed modifier applies to class definitions.
A sealed class may not be directly inherited, except if the inheriting template is defined in the same source file as the inherited class.
However, subclasses of a sealed class can be inherited anywhere.

`lazy` Copy Section

The lazy modifier applies to value definitions.
A lazy value is initialized the first time it is accessed (which might never
happen at all).
Attempting to access a lazy value during its initialization might lead to looping behavior.
If an exception is thrown during initialization, the value is considered uninitialized, and a later access will retry to evaluate its right hand side.

`infix` Copy Section

The infix modifier applies to method definitions and type definitions.
It signals that the method or type is intended for use in infix position, even if it has an alphanumeric name.

If a method overrides another, their infix annotations must agree. Either both are annotated with infix, or none of them are.

The first non-receiver parameter list of an infix method must define exactly one parameter. Examples:

infix def op1(x: S): R             // ok
infix def op2[T](x: T)(y: S): R    // ok
infix def op3[T](x: T, y: S): R    // error: two parameters
extension (x: A)
  infix def op4(y: B): R          // ok
  infix def op5(y1: B, y2: B): R  // error: two parameters

infix modifiers can also be given to type, trait or class definitions that have exactly two type parameters. An infix type like

infix type op[X, Y]

can be applied using infix syntax, i.e., A op B.

Example

The following code illustrates the use of qualified private:

package outerpkg.innerpkg
class Outer {
  class Inner {
    private[Outer] def f()
    private[innerpkg] def g()
    private[outerpkg] def h()
  }
}

Here, accesses to the method f can appear anywhere within Outer, but not outside it.
Accesses to method g can appear anywhere within the package outerpkg.innerpkg, as would be the case for package-private methods in Java.
Finally, accesses to method h can appear anywhere within package outerpkg, including packages contained in it.

Example

A useful idiom to prevent clients of a class from constructing new instances of that class is to declare the class abstract and sealed: